Image

@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 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') }}

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

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.

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

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(); // 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

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->inline('Logo', ['class' => 'image-rounded']);

Twig

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

Image

Image

Introduction

Sources

Alterations

Supported Alterations

Combining Alterations

Path Hints

Available Path Hints

Registering Path Hints

Basic Usage

Image::make()

Returns: Anomaly\Streams\Platform\Image\Image

Arguments

Example

Twig

Image::output()

Returns: mixed

Example

Twig

Image::rename()

Returns: Anomaly\Streams\Platform\Image\Image

Arguments

Example

Image::path()

Returns: string

Example

Twig

Image::url()

Returns: string

Arguments

Example

Twig

Image::image()

Returns: string

Arguments

Example

Twig

Image::img()

Returns: string

Image::data()

Returns: string

Example

Image::srcsets()

Returns: $this

Arguments

Example

Twig

Image::srcset()

Returns: string

Example

Twig

Image::sources()

Returns: $this

Arguments

Example

Twig

Image::picture()

Returns: string

Arguments

Example

Twig

Image::quality()

Returns: $this

Arguments

Example

Twig

Image::version()

Returns: Anomaly\Streams\Platform\Image\Image

Arguments

Example

Twig

Image::width()

Returns: $this

Arguments

Example

Twig

Image::height()

Returns: $this

Arguments

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

Returns: `mixed`

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

Returns: `string`

Returns: `string`

Returns: `string`

Returns: `string`

Returns: `string`

Returns: `$this`

Returns: `string`

Returns: `$this`

Returns: `string`

Returns: `$this`

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

Returns: `$this`

Returns: `$this`

Returns: `$this`

Returns: `$this`

Returns: `string`

Returns: `string`