---
title: Image
---

# Image

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

@TODO remove Laravel links to preserve version integrity

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

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

    use Anomaly\Streams\Platform\Image\Image;

    class ImageController
    {

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

An example in Twig might look like this:

    {{ image('theme::users/avatar.jpg').fit(100, 100).quality(60).url() }}

## Introduction

This section will introduce you to the `Image` class and it's components.

### Sources

The source for making an image instance can be nearly anything. We'll explore this more later in the `make` method.

### 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`.

### Supported Alterations

Alteration methods are mapped through the [Intervention package](http://image.intervention.io/):

*   [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)

### Combining Alterations

Alterations as well as any other method but `output` methods can be chained together:

    $image
        ->make('theme::img/logo.jpg')
        ->fit(100, 100)
        ->brightness(15)
        ->greyscale()
        ->class('img-rounded');

You can enjoy the same fluent API in Twig:

    {{ image('theme::img/logo.jpg')
        .fit(100, 100)
        .brightness(15)
        .greyscale()
        .class('img-rounded')|raw }}

### Path Hints

To avoid having to use full paths to your images there are a number of path hints available. Hints are a namespace that prefixes the image path.

    "theme::img/logo.jpg" // path-to-your-active-theme/resources/img/logo.jpg

    "anomaly.module.products::img/no-image.jpg" // path-to-products-module/resources/img/no-image.jpg

### Available Path Hints

All paths are relative to your application's base path.

*   `public`: public/
*   `node`: node_modules/
*   `asset`: public/app/{app_reference}/
*   `storage`: storage/streams/{app_reference}/
*   `download`: public/app/{app_reference}/assets/downloads/
*   `streams`: vendor/anomaly/streams-platform/resources/
*   `bower`: bin/bower_components/
*   `theme`: {active_theme_path}/resources/
*   `module`: {active_module_path}/resources/

Addons also have path hints associated to them:

*   `vendor.module.example`: {addon_path}/resources/

### Registering Path Hints

Registering path hints is easy. Just inject the `\Anomaly\Streams\Platform\Image\Image` class into your service provider or function and use the `addPath` method:

    $image->addPath("foo", base_path("example/path"));

Now you can use that path:

    {{ image('foo::example/image.png') }}

## Basic Usage

To get started simply include the `\Anomaly\Streams\Platform\Image\Image` class in your own class or method.

### Image::make()

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

#### Returns: `Anomaly\Streams\Platform\Image\Image`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$source

</td>

<td>

true

</td>

<td>

mixed

</td>

<td>

none

</td>

<td>

The source to make the image from.

</td>

</tr>

<tr>

<td>

$output

</td>

<td>

false

</td>

<td>

string

</td>

<td>

url

</td>

<td>

The output method. Any valid output method name can be used.

</td>

</tr>

</tbody>

</table>

#### Example

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

#### Twig

    // Set output to tag
    {{ image('theme::img/logo.jpg') }}

    // Set output to tag
    {{ img('theme::img/logo.jpg') }}

    // Set output to URL
    {{ image_url('theme::img/logo.jpg') }}

    // Set output to path
    {{ image_path('theme::img/logo.jpg') }}

> The input method can always be overriden by calling the output method manually. The initial output setting only applies to the **output** method and **__toString**.{.tip}

### Image::output()

The `output` method returns the output as defined during the `make` call. This method is typically triggered from `__toString`.

#### Returns: `mixed`

#### Example

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

    $image->output(); // the image path

#### Twig

    // Set output to tag
    {{ image_url('theme::img/logo.jpg').output() }}

    // Same output because of __toString
    {{ image_url('theme::img/logo.jpg') }}

    // Also same output.
    {{ image('theme::img/logo.jpg').url() }}

### Image::rename()

The `rename` method renames the output file. Generally images will retain their original name unless modified in which the file names are hashed by default.

#### Returns: `Anomaly\Streams\Platform\Image\Image`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$filename

</td>

<td>

false

</td>

<td>

string

</td>

<td>

The name of the source image.

</td>

<td>

The name / path of the desired output image.

</td>

</tr>

</tbody>

</table>

#### Example

    $image->rename('example.jpg');

### Image::path()

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

#### Returns: `string`

#### Example

    $image->path();

#### Twig

    {{ image('theme::img/logo.jpg').path() }}

### Image::url()

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

#### Returns: `string`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$parameters

</td>

<td>

false

</td>

<td>

array

</td>

<td>

null

</td>

<td>

The query string parameters to append to the URL.

</td>

</tr>

<tr>

<td>

$secure

</td>

<td>

false

</td>

<td>

boolean

</td>

<td>

true or false depending on if current request is HTTP/HTTPS.

</td>

<td>

Whether to return HTTP or secure HTTPS URL.

</td>

</tr>

</tbody>

</table>

#### Example

    $image->url();

#### Twig

    {{ image('theme::img/logo.jpg').url() }}

### Image::image()

The `image` method returns an `<image>` tag referencing the cached image path.

#### Returns: `string`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$alt

</td>

<td>

false

</td>

<td>

string

</td>

<td>

null

</td>

<td>

The image alt tag.

</td>

</tr>

<tr>

<td>

$attributes

</td>

<td>

false

</td>

<td>

array

</td>

<td>

null

</td>

<td>

A `key=>value` array of tag attributes.

</td>

</tr>

</tbody>

</table>

#### Example

    $image->image('Logo', ['class' => 'image-rounded']);

#### Twig

    // Inferred example.
    {{ image('theme::img/logo.jpg') }}

### Image::img()

The `img` method is an alias for `image`.

#### Returns: `string`

### Image::data()

The `data` method returns the encoded image data.

#### Returns: `string`

#### Example

    $image->data();

### Image::srcsets()

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

#### Returns: `$this`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$srcsets

</td>

<td>

true

</td>

<td>

array

</td>

<td>

none

</td>

<td>

An array of `Descriptor => Alterations` per srcset.

</td>

</tr>

</tbody>

</table>

#### Example

    $image->srcsets(
        [
            "1x" => [
                "resize"  => 400,
                "quality" => 60
            ],
            "2x" => [
                "resize"  => 800,
                "quality" => 90
            ],
            "640w" => [
                "resize"  => 800,
                "quality" => 90
            ]
        ]
    );

    // Output
    $image->img();

#### Twig

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

    // Output
    {{ example.img|raw }}

### Image::srcset()

The `srcset` returns the HTML5 srcset attribute value.

#### Returns: `string`

#### Example

    $image->srcset();

#### Twig

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

    <img src="{{ example.path }}" srcset="{{ example.srcset }}">

### Image::sources()

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

#### Returns: `$this`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$sources

</td>

<td>

true

</td>

<td>

array

</td>

<td>

none

</td>

<td>

An array of `Media => Alterations` sources.

</td>

</tr>

<tr>

<td>

$merge

</td>

<td>

false

</td>

<td>

boolean

</td>

<td>

false

</td>

<td>

If true existing alterations will be merged into source alterations.

</td>

</tr>

</tbody>

</table>

#### Example

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

#### Twig

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

### Image::picture()

The `picture` method returns the HTML5 picture element.

#### Returns: `string`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$attributes

</td>

<td>

false

</td>

<td>

array

</td>

<td>

none

</td>

<td>

An array of HTML tag attributes to include.

</td>

</tr>

</tbody>

</table>

#### Example

    $image->picture(['class' => 'example']);

#### Twig

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

### Image::quality()

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

#### Returns: `$this`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$quality

</td>

<td>

true

</td>

<td>

integer

</td>

<td>

none

</td>

<td>

The quality of the output image.

</td>

</tr>

</tbody>

</table>

#### Example

    $image->quality(60);

#### Twig

    {{ image('theme::img/logo.jpg').quality(60) }}

### Image::version()

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

> The default behavior for versioning is controlled by the **streams::images.version** config value which is true by default.{.notice}

#### Returns: `Anomaly\Streams\Platform\Image\Image`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$version

</td>

<td>

true

</td>

<td>

bool

</td>

<td>

Whether or not to version the current image path returned.

</td>

</tr>

</tbody>

</table>

#### Example

    $image->version(false);

#### Twig

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

### Image::width()

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

#### Returns: `$this`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$width

</td>

<td>

false

</td>

<td>

integer

</td>

<td>

The actual width of the image.

</td>

<td>

The value of the width attribute.

</td>

</tr>

</tbody>

</table>

#### Example

    $image->width(100);

#### Twig

    {{ image('theme::img/logo.jpg').width(100) }}

### Image::height()

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

#### Returns: `$this`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$height

</td>

<td>

false

</td>

<td>

integer

</td>

<td>

The actual height of the image.

</td>

<td>

The value of the height attribute.

</td>

</tr>

</tbody>

</table>

#### Example

    $image->height(100);

#### Twig

    {{ image('theme::img/logo.jpg').height(100) }}

### Image::attr()

The `attr` method sets an HTML attribute for the image tag output.

#### Returns: `$this`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$attribute

</td>

<td>

true

</td>

<td>

string

</td>

<td>

none

</td>

<td>

The attribute name.

</td>

</tr>

<tr>

<td>

$value

</td>

<td>

true

</td>

<td>

string

</td>

<td>

none

</td>

<td>

The attribute value.

</td>

</tr>

</tbody>

</table>

#### Example

    $image->attr('data-toggle', 'example');

#### Twig

    {{ image('theme::img/logo.jpg').attr('data-toggle', 'example') }}

##### 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. You can publish stream configuration with Artisan:

    php artisan streams:publish

Macros can be set with an array just like `srcset` or `picture` sources:

    "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.

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

### Image::macro()

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

#### Returns: `$this`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$macro

</td>

<td>

true

</td>

<td>

string

</td>

<td>

none

</td>

<td>

The name of the macro to run.

</td>

</tr>

</tbody>

</table>

#### Example

    $image->macro("thumb")->img();

    $image
    	->macro("thumb")
    	->macro("desaturate")
    	->macro("responsive") // Set's common srcsets maybe?
    	->img();

#### Twig

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

    {{ image('theme::img/logo.jpg')
    	.macro("thumb")
    	.macro("desaturate")
    	.macro("responsive")|raw }}
        
### Image::base64()

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

#### Returns: `string`
#### Example
    $base64 = $image->base64(); // data:image/png;base64,iVBORw0KGgoAAAANSU...
    
#### Twig
    <image src="{{ image('theme::img/logo.jpg').base64() }}"/>


### Image::inline()

The `inline` method returns an `<image>` tag with a base64 encoded data URI.

#### Returns: `string`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$alt

</td>

<td>

false

</td>

<td>

string

</td>

<td>

null

</td>

<td>

The image alt tag.

</td>

</tr>

<tr>

<td>

$attributes

</td>

<td>

false

</td>

<td>

array

</td>

<td>

null

</td>

<td>

A `key=>value` array of tag attributes.

</td>

</tr>

</tbody>

</table>

#### Example

    $image->inline('Logo', ['class' => 'image-rounded']);

#### Twig

    // Inferred example.
    {{ img('theme::img/logo.jpg').inline|raw }}

