Usage

If you've ever done an image transform in a Craft template, this probably looks familiar:

{% set image = craft.assets().one() %}
<img src="{{ image.getUrl({ width: 1000 }) }}">

The same code using Imager would look like this:

{% set image = craft.assets().one() %}
{% set transformedImage = craft.imager.transformImage(image, { width: 1000 }) %}
<img src="{{ transformedImage.url }}">

So far, it's more code than the Craft way. But, let's say you need to resize the image to six different widths, because you're using srcset to serve up responsive images. And you want the crop position on all the images to be in the bottom-right corner, an aspect ratio of 16:9, and while the large images should have a high jpeg quality, the smaller ones should be more optimized.

Here's how the code would look with Imager:

{% set transformedImages = craft.imager.transformImage(image, [
    { width: 1200 }, 
    { width: 1000 }, 
    { width: 800 }, 
    { width: 600, jpegQuality: 65 }, 
    { width: 400, jpegQuality: 65 }
    ], { ratio: 16/9, position: '100% 100%', jpegQuality: 80 }) %}

TIP

Please note that if you pass in a single transform object as the second parameter to transformImage, a single transformed image will be returned. If you pass an array of transform objects, an array of transformed images will be returned.

Imager 1.5.0 also introduced a convenient fillTransforms config setting which makes the above code even simpler:

{% set transformedImages = craft.imager.transformImage(image, [
    { width: 1200 }, 
    { width: 600, jpegQuality: 65 }, 
    { width: 400, jpegQuality: 65 }
    ], { ratio: 16/9, position: '100% 100%', jpegQuality: 80 }, 
    { fillTransforms: true }) %}

See the fillTransforms, fillAttribute and fillInterval settings for more information.

The plugin also includes some additional methods that helps you streamline the creation of responsive images. With the above transformed images, you can output the appropriate srcset like this, with a base64-encoded placeholder in the src attribute:

<img src="{{ craft.imager.placeholder({ width: 160, height: 90 }) }}" 
     sizes="100vw" 
     srcset="{{ craft.imager.srcset(transformedImages) }}">

Additional information about the template variables can be found in Templating.

Transform the transform

In the above examples, an Asset element is passed to the transformImage method. You can also pass a transformed image returned by Imager, a path or an url to an image that has already been transformed by Imager. This can be useful for increasing performance, or simplifying your template code. In the below example, an image is first resized and have effects applied to it, before being resized to the final sizes:

{% set newBaseImage = craft.imager.transformImage(selectedImage, { 
    width: 1200, 
    height: 1200, 
    effects: { modulate: [110, 100, 100], colorBlend: ['#ffcc33', 0.3], gamma: 1.2 },
    jpegQuality: 95 }) %}

{% set transformedImages = craft.imager.transformImage(newBaseImage, [
    { width: 600, height: 600 },
    { width: 500, height: 500 },
    { width: 400, height: 400 }
    ]) %}

Transforming external images

You can also transform remote images by passing an url for an image to transformImage:

{% set externalImage = 'http://www.nasa.gov/sites/default/files/styles/full_width_feature/public/thumbnails/image/pia19808-main_tight_crop-monday.jpg' %}

{% set transformedImages = craft.imager.transformImage(externalImage, [
    { width: 600, height: 600 },
    { width: 500, height: 500 },
    { width: 400, height: 400 }
    ]) %}

When transforming external images, the remote image is downloaded to your storage folder, usually storage/runtime, and cached for the duration selected in the cacheDurationRemoteFiles config parameter. If you don't want to cache remote images, you can set cacheRemoteFiles to false, which will result in any downloaded files being deleted at the end of the session.