Named transforms

Named transforms is a new concept in Imager X. It's a way to manage your transforms from a central location, and is required for some of the new features in Imager X, like automatic generation of transforms and transforms in GraphQL.

You can configure your named transforms by creating a config file in your config folder named imager-x-transforms.php, and add transforms as needed. The following example defines two transforms, one with the handle 'heroImage' and one with handle 'listThumbnail'.

<?php

return [
    'heroImage' => [
        'displayName' => 'Hero Image',
        'transforms' => [
            ['width' => 600],
            ['width' => 1800],
        ],
        'defaults' => [
            'ratio' => 16/9,
            'jpegQuality' => 80
        ],
        'configOverrides' => [
            'fillTransforms' => true,
            'fillInterval' => 300,
        ]
    ],
    'listThumbnail' => [
        'displayName' => 'List Thumbnail',
        'transforms' => [
            ['width' => 200],
            ['width' => 400],
            ['width' => 600],
        ],
        'defaults' => [
            'ratio' => 4/3,
            'format' => 'jpg'
        ]
    ]
];

You can use these transforms in your templates by passing in the transform handle instead of a transform object:

{% set transforms = craft.imagerx.transformImage(image, 'heroImage') %}

For transform attributes that are dynamic, you can supply a function that will be processed before the transform is used. The function gets the image value that was passed to the transform method as a parameter:

return [
    'articleImage' => [
        'transforms' => [
            ['width' => 600],
            ['width' => 800],
            ['width' => 1000],
            ['width' => 1200],
        ],
        'defaults' => [
            'ratio' => static function ($image) {
                if ($image instanceof \craft\elements\Asset) {
                    if ($image->getWidth() / $image->getHeight() > 1) {
                        return 16/9;
                    } 
                    return 2/3;
                }
                return 16/9;
            },
            'jpegQuality' => 70
        ]
    ],
];

TIP

It's a good idea to code defensively in config files, since any edge case errors will be extra hard to catch if it occurs, for instance, during automatic generation inside an event handler.

Nested named transforms

To make things more maintainable, please note that you can even nest named transforms inside other named transforms. This is awesome when you only need to override some of the default transform parameters or override config settings.

<?php

return [
    'myTransform' => [
        'transforms' => [
            ['width' => 800],
            ['width' => 1600],
        ],
        'configOverrides' => [
            'fillTransforms' => true,
            'fillInterval' => 400,
        ]
    ],
    'myTransformLandscape' => [
        'transforms' => 'myTransform',
        'defaults' => [
            'ratio' => 16/9,
        ],
    ],
    'myTransformLandscapeWebp' => [
        'transforms' => 'myTransformLandscape',
        'defaults' => [
            'format' => 'webp',
        ]
    ]
];