README

Pretransform any Assets on save, with Imager

Requirements

This plugin requires Craft CMS 3.0.0-beta.23 or later.

Installation

To install the plugin, follow these instructions.

Open your terminal and go to your Craft project:
```
 cd /path/to/project
```

Then tell Composer to load the plugin:

 composer require superbig/craft-imagerpretransform

In the Control Panel, go to Settings → Plugins and click the “Install” button for Imager Pretransform.

Imager Pretransform Overview

If you have suffered from memory or execution time issues when creating many transforms on demand, you should look into pre-generating transforms per image.

This plugin, combined with a long cache duration time, will make sure transforms will only be generated once, and one at a time.

When users upload an Asset, a task will be created, which in turn will use Imager to pre-generate the transform(s).

Configuring Imager Pretransform

Copy the config template from vendor/superbig/craft-imagerpretransform/src/config.php to craft/config as imager-pretransform.php and make your changes there to override default settings.

You can either have a set of transforms per Asset source handle:

<?php
return [
    // Toggle pretransforming as needed
    'enabled' => true,
    // This will process each image in a separate job. Perfect in combination with Async Queue.
    'processImagesInJobs' => false,
    // Transforms - these options are passed straight to Imager
    'transforms' => [
        // Global transform, will be applied to all images
        [
            'width' => 1400,
        ],
        // Images source, with handle images
        'images' => [
            [
                'width' => 1400,
            ],
            [
                'width'       => 600,
                'jpegQuality' => 65
            ],
            [
                'width'       => 380,
                'height'      => 380,
                'mode'        => 'crop',
                'position'    => 'center-center',
                'jpegQuality' => 65
            ],

            'defaults' => [

            ],

            'configOverrides' => [
                'resizeFilter'         => 'catrom',
                'instanceReuseEnabled' => true,
            ]
        ],

        'anotherSourceHandle' => [
            [
                'height' => 600
            ]
        ]
    ]
];

Or just a set of transforms that will be applied to all Assets on upload/save:

<?php
return [
    'transforms' => [
        [
            'width' => 1400,
        ],
        [
            'width'       => 600,
            'jpegQuality' => 65
        ],
        [
            'width'       => 380,
            'height'      => 380,
            'mode'        => 'crop',
            'position'    => 'center-center',
            'jpegQuality' => 65
        ],

        'defaults' => [],
        'configOverrides' => []
    ]
];

You can also use a Twig template to setup your transforms:

<?php
return [
    'transforms' => [
        [
            'template' => '_imager-pretransform',
        ],
    ]
];

The Twig template will be passed the variables asset and pretransform. You can check if pretransform is defined if you need to conditionally do transforms in a certain way.

_imager-pretransform.twig:

{% set transforms = [
    { width: 800 },
    { width: 400, height: 400 },
] %}

{% if pretransform is defined %}
    {% do craft.imager.transformImage(asset, transforms) %}
{% else %}
    {# Your normal image partial #}
{% endif %}

This way you can keep your transforms in one place.

You should also set Imager's cache duration to a long time, say 1 year:

In imager.php:

'cacheDuration' => 31536000, // 1 year

If any of your transform settings depends on a value from the specific Asset, you can pass a function instead of a string.

The function will be passed the Asset.

As an example, this is how you would use the built-in focal point selector in Craft:

<?php
return [
    'transforms' => [
        [
            'width'       => 400,
            'height'      => 400,
            'mode'        => 'croponly',
            'position'    => function (Asset $asset) {
                return $asset->getFocalPoint();
            },
        ],
    ]
];

Using Imager Pretransform

There is 3 ways to pretransform images:

Automatically on upload
Manually through element action
Console command that takes either folder id or volume handle as argument

Console command

To transform assets in a volume: ./craft imager-pretransform/default/index --volume=<volumeHandle> or -v <volumeHandle>

To transform assets in a folder: ./craft imager-pretransform/default/index --folderId=<folder id>

By default, the command will only transform the topmost folder of the volume or the specified folder by id. To include all subfolders, add the --include-subfolders / -s param.

Brought to you by Superbig

superbig / craft-imagerpretransform

Maintainers

Details