1. Documentation
  2. Application
  3. Streams Platform
  4. Image
Edit this Page

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() }}"/>