---
title: Images
---

# Images

<div class="documentation__toc"></div>

## Introduction

The `image` service provides powerful image manipulation and management with zero setup. The service is built over the [Intervention Image](https://github.com/Intervention/image) framework by [Oliver Vogel](https://olivervogel.com/).

```twig
{{ img('theme::users/avatar.jpg').fit(100, 100).quality(60).inline()|raw }}
```

To get started you need to include the `\Anomaly\Streams\Platform\Image\Image` class in your code.

```php
<?php namespace Anomaly\Streams\Platform\Image;

use Anomaly\Streams\Platform\Image\Image;
use Anomaly\Streams\Platform\Http\Controller\PublicController;

class AvatarController extends PublicController
{

    public function thumb(Image $image)
    {
        return $image
            ->make('anomaly.theme.example::users/avatar.jpg')
            ->rename(auth().id() . '-avatar.jpg')
            ->fit(100, 100)
            ->quality(60)
            ->data();
    }
}
```

## The Basics

### Image Sources

The `source` for making an image instance can be a `file` instance or `id`, a `hint::path` value, or another `image` instance.

### Making an Image Instance

The `make` method is the entry point to the image service. It returns a unique instance of the image class ready for `alteration` and `output`.

```php
$image = app(\Anomaly\Streams\Platform\Image\Image::class);

$image = $image->make($source, $output);
```


```twig
{{ img('theme::img/logo.jpg') }} // img tag
{{ img('theme::img/logo.jpg').url }}
{{ img('theme::img/logo.jpg').path }}
{{ img('theme::img/logo.jpg').data }}
{{ img('theme::img/logo.jpg').base64 }}
{{ img('theme::img/logo.jpg').inline }} // img tag with data URI
```

## Macros

Macros are stored procedures that can apply a single or multiple alterations to an image at once.

### Creating Macros

Macros are stored in the `streams::images.macros` configuration.

[Streams Configuration](../getting-started/configuration){.link}

Macros are set with an array just like [srcset](#srcset) or [picture](#picture) sources.

```php
"macros" => [
    "example" => [
        "resize"  => 800,
        "quality" => 90,
    ],
],
```

You can also define a macro as a Closure that accepts an Image $image argument. Closure macros are called from Laravel`s service container and as such, support method injection.

```php
"macros" => [
    "pink" => function(\Anomaly\Streams\Platform\Image\Image $image) {
        $image->colorize(100, 0, 100);
    }
],
```

### Running Macros

The `macro` method runs a macro on the image.

```twig
{{ img('theme::img/logo.jpg').macro('thumb')|raw }}
```

```php
$image = app(\Anomaly\Streams\Platform\Image\Image::class);

$image
    ->make('theme::img/logo.jpg')
    ->macro("thumb")
    ->path();
```


## Alterations

An alteration method modifies the image. To apply alterations to an image simply call the method on the image instance. Examples of an alteration might be blur or fit.

- [blur](http://image.intervention.io/api/blur)
- [brightness](http://image.intervention.io/api/brightness)
- [colorize](http://image.intervention.io/api/colorize)
- [contrast](http://image.intervention.io/api/contrast)
- [crop](http://image.intervention.io/api/crop)
- [encode](http://image.intervention.io/api/encode)
- [fit](http://image.intervention.io/api/fit)
- [flip](http://image.intervention.io/api/flip)
- [gamma](http://image.intervention.io/api/gamma)
- [greyscale](http://image.intervention.io/api/greyscale)
- [heighten](http://image.intervention.io/api/heighten)
- [invert](http://image.intervention.io/api/invert)
- [insert](http://image.intervention.io/api/insert)
- [limitColors](http://image.intervention.io/api/limitColors)
- [pixelate](http://image.intervention.io/api/pixelate)
- [opacity](http://image.intervention.io/api/opacity)
- [resize](http://image.intervention.io/api/resize)
- [rotate](http://image.intervention.io/api/rotate)
- [amount](http://image.intervention.io/api/amount)
- [widen](http://image.intervention.io/api/widen)
- [orientate](http://image.intervention.io/api/orientate)

### quality

The `quality` method adjusts the quality of the output image.

```twig
{{ img('theme::img/logo.jpg').quality(60)|raw }}
```

```php
$image = app(\Anomaly\Streams\Platform\Image\Image::class);

$image
    ->make('theme::img/logo.jpg')
    ->quality(60);
```

### width

The `width` method set's the HTML width attribute.

```twig
{{ img('theme::img/logo.jpg').width(120)|raw }}
```

```php
$image = app(\Anomaly\Streams\Platform\Image\Image::class);

$image
    ->make('theme::img/logo.jpg')
    ->width(100);
```

### height

The `height` method set's the HTML height attribute.

```twig
{{ img('theme::img/logo.jpg').height(120)|raw }}
```

```php
$image = app(\Anomaly\Streams\Platform\Image\Image::class);

$image
    ->make('theme::img/logo.jpg')
    ->height(100);
```

### attr

The `attr` method set's an HTML attribute and value.

```twig
{{ img('theme::img/logo.jpg').attr('data-lazy', true)|raw }}
```

```php
$image = app(\Anomaly\Streams\Platform\Image\Image::class);

$image
    ->make('theme::img/logo.jpg')
    ->attr('data-lazy', true);
```


## Output

### rename

The `rename` method renames the `output` file. By default, images will retain their original name unless modified in which case the file names are uniquely hashed.

```twig
{{ img('theme::img/logo.jpg').rename('example.jpg')|raw }}
```

```php
$image = app(\Anomaly\Streams\Platform\Image\Image::class);

$image
    ->make('theme::img/logo.jpg')
    ->rename('example.jpg');
```

### path

The `path` method returns the relative path for the cached image.

```twig
<img src="{{ img('theme::img/logo.jpg').path }}">
```

```php
$image = app(\Anomaly\Streams\Platform\Image\Image::class);

$image
    ->make('theme::img/logo.jpg')
    ->path();
```

### url

The `url` method returns the absolute URL for the cached image.

```twig
<img src="{{ img('theme::img/logo.jpg').url }}">
```

```php
$image = app(\Anomaly\Streams\Platform\Image\Image::class);

$image
    ->make('theme::img/logo.jpg')
    ->url();
```

### image

The `image` method returns the `img` tag for the cached image.

> Image output also automates alt tags.{.tip}

```twig
<img src="{{ img('theme::img/logo.jpg') }}">
```

> Image output is the default plugin output format.{.tip}

```php
$image = app(\Anomaly\Streams\Platform\Image\Image::class);

$image
    ->make('theme::img/logo.jpg')
    ->image();
```

### version

The `version` method will allow you to disable or enable asset versioning query parameters from respective outputs.

[Image Configuration](../reference/configuration#images){.link}

```twig
{{ img('theme::img/logo.jpg').version(false)|raw }}
```

```php
$image = app(\Anomaly\Streams\Platform\Image\Image::class);

$image
    ->make('theme::img/logo.jpg')
    ->version(false)
    ->image();
```

### base64

The `base64` method returns the base64 encoded data of the image.

```twig
<img src="{{ img('theme::img/logo.jpg').base64() }}"/>
```

```php
$image = app(\Anomaly\Streams\Platform\Image\Image::class);

$image
    ->make('theme::img/logo.jpg')
    ->base64();
```

### inline

The `inline` method returns an `img` tag with a `base64` encoded data URI.

```twig
{{ img('theme::img/logo.jpg').inline()|raw }}
```

```php
$image = app(\Anomaly\Streams\Platform\Image\Image::class);

$image
    ->make('theme::img/logo.jpg')
    ->inline();
```


### srcsets

The `srcsets` method let's you define the srcset HTML5 attribute for output.

```twig
{{ img('theme::img/logo.jpg').srcsets(
    {
        "1x": {
            "resize": 400,
            "quality": 60
        },
        "2x": {
            "resize": 800,
            "quality": 90
        },
        "640w": {
            "resize": 800,
            "quality": 90
        }
    }
)|raw }}
```

```php
$image = app(\Anomaly\Streams\Platform\Image\Image::class);

$image
    ->make('theme::img/logo.jpg')
    ->srcsets(
        [
            "1x" => [
                "resize"  => 400,
                "quality" => 60
            ],
            "2x" => [
                "resize"  => 800,
                "quality" => 90
            ],
            "640w" => [
                "resize"  => 800,
                "quality" => 90
            ]
        ]
    )->image();
```

### srcsets

The `srcset` returns the HTML5 srcset attribute value.

```twig
{% set image = img('theme::img/logo.jpg').srcsets(
   {
       "1x": {
           "resize": 400,
           "quality": 60
       },
       "2x": {
           "resize": 800,
           "quality": 90
       },
       "640w": {
           "resize": 800,
           "quality": 90
       }
   }
)  %}

<img src="{{ image.path }}" srcset="{{ image.srcset }}">
```

```php
$image = app(\Anomaly\Streams\Platform\Image\Image::class);

$srcsets = $image
    ->make('theme::img/logo.jpg')
    ->srcsets(
        [
            "1x" => [
                "resize"  => 400,
                "quality" => 60
            ],
            "2x" => [
                "resize"  => 800,
                "quality" => 90
            ],
            "640w" => [
                "resize"  => 800,
                "quality" => 90
            ]
        ]
    )->srcset();
```

### sources

The `sources` method allows you to set the sources for the HTML5 picture element.

```twig
{{ img('theme::img/logo.jpg').sources(
     {
         "(min-width: 600px)": {
             "resize": 400,
             "quality": 60
         },
         "(min-width: 1600px)": {
             "resize": 800,
             "quality": 90
         },
         "fallback": {
             "resize": 1800
         }
     }
 )|raw }}
```

```php
$image = app(\Anomaly\Streams\Platform\Image\Image::class);

$image->sources(
    [
        "(min-width: 600px)" => [
            "resize"  => 400,
            "quality" => 60
        ],
        "(min-width: 1600px)" => [
            "resize"  => 800,
            "quality" => 90
        ],
        "fallback" => [
            "resize"  => 1800
        ]
    ]
);
```

### picture

The `picture` method returns the HTML5 picture element.

```twig
{{ img('theme::img/logo.jpg').sources(
     {
         "(min-width: 600px)": {
             "resize": 400,
             "quality": 60
         },
         "(min-width: 1600px)": {
             "resize": 800,
             "quality": 90
         },
         "fallback": {
             "resize": 1800
         }
     }
 ).picture()|raw }}
```

```php
$image = app(\Anomaly\Streams\Platform\Image\Image::class);

$image->sources(
    [
        "(min-width: 600px)" => [
            "resize"  => 400,
            "quality" => 60
        ],
        "(min-width: 1600px)" => [
            "resize"  => 800,
            "quality" => 90
        ],
        "fallback" => [
            "resize"  => 1800
        ]
    ]
);
```
