Image

The image service provides powerful image manipulation and management with zero setup. The Image class is built over the Intervention Image framework by Oliver Vogel.

<?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:

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
Key Required Type Default Description
$source true mixed none The source to make the image from.
$output false string url The output method. Any valid output method name can be used.
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') }}
**Pro Tip:** 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**.
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
Key Required Type Default Description
$filename false string The name of the source image. The name / path of the desired output image.
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
Key Required Type Default Description
$parameters false array null The query string parameters to append to the URL.
$secure false boolean true or false depending on if current request is HTTP/HTTPS. Whether to return HTTP or secure HTTPS URL.
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
Key Required Type Default Description
$alt false string null The image alt tag.
$attributes false array null A `key=>value` array of tag attributes.
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
Key Required Type Default Description
$srcsets true array none An array of `Descriptor => Alterations` per srcset.
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
Key Required Type Default Description
$sources true array none An array of `Media => Alterations` sources.
$merge false boolean false If true existing alterations will be merged into source alterations.
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
Key Required Type Default Description
$attributes false array none An array of HTML tag attributes to include.
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
Key Required Type Default Description
$quality true integer none The quality of the output image.
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.

**Note:** The default behavior for versioning is controlled by the **streams::images.version** config value which is true by default.
Returns: Anomaly\Streams\Platform\Image\Image
Arguments
Key Required Type Description
$version true bool Whether or not to version the current image path returned.
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
Key Required Type Default Description
$width false integer The actual width of the image. The value of the width attribute.
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
Key Required Type Default Description
$height false integer The actual height of the image. The value of the height attribute.
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
Key Required Type Default Description
$attribute true string none The attribute name.
$value true string none The attribute value.
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
Key Required Type Default Description
$macro true string none The name of the macro to run.
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(); // iVBORw0KGgoAAAANSU...
Twig
<image src="data:image/png;base64,{{ image('theme::img/logo.jpg').base64() }}"/>