superbig / craft-imagerpretransform
Pretransform any Assets on save, with Imager
Installs: 11 426
Dependents: 0
Suggesters: 0
Security: 0
Stars: 22
Watchers: 2
Forks: 1
Open Issues: 1
Type:craft-plugin
Requires
- aelvan/imager: ^2.0.0
- craftcms/cms: ^3.0.0
This package is auto-updated.
Last update: 2024-05-15 21:24:29 UTC
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