# Configuration
Imager X has no control panel settings, everything is configured through standard
Craft config files in the config folder.
# General configuration
These settings can be configured by creating an imager-x.php file
in your config folder, and adding parameters as needed. Please refer to
the Settings.php file (opens new window)
for additional pointers regarding available parameters and defaults.
# transformer [string]
Default: 'craft'
Allowed values: 'craft', 'imgix' PRO
Transformers provides an interface for doing image transforms. There are two built-in transformers at the moment,
the default 'craft' which transforms images on your webserver using the Imagine library that Craft ships with
and GD or Imagick, and 'imgix' which offloads your image transforms to Imgix (opens new window).
If you want to use Imgix, please refer to the imgixProfile and imgixConfig config settings, which are required.
TIP
The Imgix transformer, and the ability to extend Imager with custom transformers, are only available in the PRO edition.
There're also a several other first party transformers available for free in the plugin store (opens new window).
# imagerSystemPath [string]
Default: '@webroot/imager/'
File system path to the folder where you want to store the transformed images.
Please note: This folder acts as the cache for transformed images, even if you choose to upload images to some other storage (ie AWS or similar). If you use atomic deploys (ServerPilot, Opworks, or similar), you'd want this folder to be on a shared storage.
# imagerUrl [string|array]
Default: '/imager/'
Url to the transformed images. The imagerUrl will be prepended to the path and filename of the transformed image.
Can be a relative url, or a full url. If you upload files to AWS, you'd set the imagerUrl to the AWS/CloudFront URL, like so:
'imagerUrl' => 'http://s3-eu-west-1.amazonaws.com/imagertransforms/',
You can localize this setting per site, for instance if you have a pull proxy where you want to use different distributions per site. Example:
'imagerUrl' => [
'siteOneHandle' => 'http://one.pullproxy.com/',
'siteTwoHandle' => 'http://two.pullproxy.com/',
],
# safeFileFormats [array]
Default: ['jpg', 'jpeg', 'gif', 'png']
Specifies which file formats should be considered safe to transform.
Note! This setting is used for auto generation and CP transforms. You can still pass any file format to the transform method.
# cacheEnabled [bool]
Default: true
Enables or disables caching of transformed images.
# cacheRemoteFiles [bool]
Default: true
Enables or disables caching of remote files. This includes files on asset sources that are not local, and images on remote URLs.
By default images will be downloaded to your storages folder when first encountered, and cached for the duration of cacheDurationRemoteFiles. If you disable it, the downloaded images will be deleted automatically after each transform request.
# cacheDuration [string|int|bool]
Default: false
The cache duration of transformed images.
# cacheDurationRemoteFiles [string|int|bool]
Default: 1209600
When a remote file is downloaded, it will be cached locally for this duration.
# cacheDurationExternalStorage [string|int|bool]
Default: 1209600
The cache duration that is set on images uploaded to external storages.
# cacheDurationNonOptimized [string|int|bool]
Default: 300
The cache duration that is set on images uploaded to external storages if a post optimization for the image is scheduled.
# jpegQuality [int]
Default: 80
Defines the JPEG compression level. Higher values equals better quality and bigger filesizes.
# pngCompressionLevel [int]
Default: 2
Defines the PNG compression level. PNG compression is always lossless, so this setting doesn't have any effect on quality. It only affects speed and filesize. A lower value means faster compression, but bigger filesizes. A value of 0 means "no compression", which is the preferred setting if you're doing any post optimizations of png images (with Optipng or TinyPNG).
# webpQuality [int]
Default: 80
Defines the WebP compression level. Higher values equals better quality and bigger filesizes.
# webpImagickOptions [array]
Default: array()
Additional options you want to pass to Imagick when creating WebP files. See the ImageMagick documentation (opens new window) for possible options (although, all are not supported by Imagick).
Example on how to use it in config files:
'webpImagickOptions' => array(
'lossless' => 'true',
'method' => '5',
),
Example on how to use it in your template code:
{% set webpImage = craft.imagerx.transformImage(image, { width: 500, format: 'webp', webpImagickOptions: { lossless: 'true', method: '1' } }) %}
# avifQuality [int]
Default: 80
Defines the AVIF compression level. Higher values equals better quality and bigger filesizes.
# jxlQuality [int]
Default: 80
Defines the JPEG XL compression level. Higher values equals better quality and bigger filesizes.
# customEncoders [array]
Default: []
Support for modern file formats like WebP, AVIF and JPEG XL in distributed versions of
GD and Imagick is spotty at best. To let you take advantage of these new formats even
if your image driver doesn't, Imager implements the concept of custom encoders.
A custom encoder is a command line tool that can convert an image in a legacy format,
to a modern one. For each format you can define a path to the runtime, a set of
options, and a paramsString that will be parsed to include the options specified,
in addition to src and dest paths, and passed to the runtime.
WARNING
Please note that when using custom encoders, the quality config settings for
WebP, AVIF and JPEG XL will not be used. You have to merge in this using
your paramString.
Example configuration:
'customEncoders' => [
'webp' => [
'path' => '/usr/local/bin/cwebp',
'options' => [
'quality' => 80,
'effort' => 4,
],
'paramsString' => '-q {quality} -m {effort} {src} -o {dest}'
],
'avif' => [
'path' => '/usr/local/bin/cavif',
'options' => [
'quality' => 80,
'speed' => 7,
],
'paramsString' => '--quality {quality} --speed {speed} --overwrite -o {dest} {src}'
],
'jxl' => [
'path' => '/usr/local/bin/cjxl',
'options' => [
'quality' => 80,
'effort' => 7,
],
'paramsString' => '-q {quality} -e {effort} {src} {dest}'
]
]
At the template level, you can use the customEncoderOptions transform parameter
to override the options for the encoder being used.
See "WebP, AVIF, and JPEG XL support" for more information.
# interlace [bool|string]
Default: false
Allowed values: false, true 'line', 'none', 'line', 'plane', 'partition'
Defines the interlace method for creating progressive images. Imagick is required for the plane and partition methods.
GD only supports one interlace mode, so it only makes sense to set a specific interlace mode if you use Imagick.
# allowUpscale [bool]
Default: true
If set to false, images will never be upscaled.
# resizeFilter [string]
Default: 'lanczos'
Allowed values: 'point', 'box', 'triangle', 'hermite', 'hanning', 'hamming', 'blackman', 'gaussian', 'quadratic', 'cubic', 'catrom', 'mitchell', 'lanczos', 'bessel', 'sinc'
Sets the resize filter. Imagick is required. By default Craft uses the lanczos filter for interpolation when resizing. It yields good visual result, but is one of the slower ones. There is a bunch of different filters available, and Imager let's you decide which one to use (lanczos is still the default).
The difference in quality and encoding speed varies a lot, so you should choose what is most important for your project, speed or quality. The difference in speed will be more pronounced the bigger the original image is. The difference in quality will be more prononounced the bigger the resulting image is.
Here's the result of a speed test posted on php.net (opens new window):
FILTER_POINT took: 0.334532976151 seconds
FILTER_BOX took: 0.777871131897 seconds
FILTER_TRIANGLE took: 1.3695909977 seconds
FILTER_HERMITE took: 1.35866093636 seconds
FILTER_HANNING took: 4.88722896576 seconds
FILTER_HAMMING took: 4.88665103912 seconds
FILTER_BLACKMAN took: 4.89026689529 seconds
FILTER_GAUSSIAN took: 1.93553304672 seconds
FILTER_QUADRATIC took: 1.93322920799 seconds
FILTER_CUBIC took: 2.58396601677 seconds
FILTER_CATROM took: 2.58508896828 seconds
FILTER_MITCHELL took: 2.58368492126 seconds
FILTER_LANCZOS took: 3.74232912064 seconds
FILTER_BESSEL took: 4.03305602074 seconds
FILTER_SINC took: 4.90098690987 seconds
# smartResizeEnabled [bool]
Default: false
When set to true, the new smartResize method that was added in Craft 2.5 will be used when Imagick is installed. This method is based on the research done by Dave Newton (opens new window) and yields smaller filesizes without any noticeable loss of quality.
Using smartResize may drastically decrease performance, especially when resizing pngs, and is therefore disabled by default.
# removeMetadata [bool]
Default: false
Strips meta data from image, resulting in smaller images. Only available with Imagick.
# preserveColorProfiles [bool]
Default: false
Can be turned on to preserve color profiles if meta data is stripped. Only available with Imagick.
# bgColor [string]
Default: ''
Adds a background color (in hexadecimal) to the transformed image (obviously only relevant if the source image has transparency).
# position [string]
Default: '50% 50%'
By default, Imager will use the native focal point for Asset elements. For other types of source elements, like external images, this setting will be used as default when cropping an image.
# letterbox [array]
Default: ['color'=>'#000', 'opacity'=>0]
Specifies the color and opacity to use for the background when using the letterbox resize method. Opacity is only applicable when saving the transformed file in png format. Animated gifs will always have transparent backgrounds.
# blurhashComponents [array]
Default: [4, 3]
Specifies the number of components (x and y) to use when generating a blurhash (only relevant for local ones, Imgix uses fixed values). Value must be between 1 and 9.
# useFilenamePattern [bool]
Default: true
When enabled, the path of the transformed asset will be created using the filenamePattern.
# filenamePattern [string]
Default: '{basename}_{transformString|hash}.{extension}'
Pattern that defines how the filename of the transformed file should look. The following variables are available:
{basename}: The base name of the original file that was transformed (everything before the extension).
{extension}: The extension of the transformed file.
{fullname}: The full name of the transformed file, basename plus the transform string.
{transformString}: The generated transform string.
{transformName}: The named transform that was used (blank if a named transform was not used).
{timestamp}: Timestamp of the source file.
{basename}, {fullname}, and {transformString} can be hashed, either with a long md5 hash, or a shorter, truncated one based the shortHashLength config setting.
Examples:
// Show name and transform string (good for debugging
'filenamePattern' => '{fullname}.{extension}'
// Show name and a hashed transform string (default)
'filenamePattern' => '{basename}_{transformString|hash}.{extension}'
// Show name and a shorter hashed transform string
// (prettier, but could result in name collisions (not likely though))
'filenamePattern' => '{basename}_{transformString|shorthash}.{extension}'
You could use this config setting in your templates to create more SEO-friendly image filenames.
Example:
{% set employeeImage = craft.imagerx.transformImage(employee.image, { width: 400 }, {},
{ filenamePattern: employee.name ~ '_{fullname|shorthash}.{extension}' })
%}
Make sure to always include the transform string in some way or another to avoid transforms getting the same name and overwriting each other.
# shortHashLength [int]
Default: 10
The length of the short hash when using the shorthash filter in filenamePattern.
# hashFilename [bool|string]
hashFilename has been deprecated, use filenamePattern instead
Default: 'postfix'
Allowed values: true, false, 'postfix'
When doing an transform, Imager creates a filename based on the properties in the transform. By default ('postfix'), the generated part of the filenamed is hashed, and added as a postfix to the original filename. This makes the filename still relevant for SEO purposes, but still reasonably short.
If set to false, the filename will contain the generated string in clear text. This can result in really long filenames, but is great for debugging purposes.
If set to true, the whole filename is hashed. This will result in a short, but obscured, filename.
# hashPath [bool]
Default: false
When enabled, the path of the transformed asset will be hashed.
# addVolumeToPath [bool]
Default: true
When enabled, the handle for the volume is added to the path of the transformed image. When disabled, transformes from different volumes with the exact same name and transform string could overwrite each other.
# hashRemoteUrl [bool|string]
Default: false
Allowed values: true, false, 'host'
When tranforming remote images, the hostname and remote path will be used as path inside your imager system path. If you want to shorten or obfuscate the remote url, you can set this to true or 'host'.
If you set this to true, the whole url will be hashed and used as the path.
If set to 'host', only the hostname will be hashed, while the remote path will be kept.
# useRemoteUrlQueryString [bool]
Default: false
By default, query strings on external urls are not used when creating the filename of the transformed file, to improve caching. When enabled, any query string on the external url will be hashed and added as a part of the filename.
# instanceReuseEnabled [bool]
Default: false
By default, both in Imager and Craft's built in transform functionality, the original image is loaded into memory for every transform. This ensures that the quality of the resulting transform is as good as possible.
If set to true, the original image is only loaded once, and every transform will continue working on the same image instance. This significantly increases performance and memory use, but will most likely decrease quality.
# noop [bool]
Default: false
Setting noop (no operation) to true makes Imager return the source image untouched. Useful if you don't want to do image transforms in
some environments.
# suppressExceptions [bool]
Default: false if devMode is enabled, otherwise true
By default Imager throws exceptions if file based operations fail, an external image can't be downloaded, etc. If suppressExceptions is set to true, Imager will instead log errors to the log file, and return null to the template.
# fallbackImage [int|string|Asset]
Default: null
If a transform fails for some reason, Imager can fallback to using a fallback image for transforms. The value of the config setting can
either be an id for an Asset, a URL for an external image, a relative url to an image inside your document root, or an actual Asset.
This setting is primarily a way to gracefully recover from errors which would occur from missing image files or similar, during development. If used in production environments, be mindful of any caching that could keep fallback images from being updated when errors gets fixed. It's always better to write your template code defensively to account for production errors, than relying on this setting.
# mockImage [int|string|Asset]
Default: null
You can use this config setting to override whatever image is passed into Imager's transform method. The value of the config setting can
either be an id for an Asset, a URL for an external image, a relative url to an image inside your document root, or an actual Asset.
This setting is primarily a way to keep working on a site when you don't have access to, or don't care about, the real assets.
# convertToRGB [bool]
Default: false
Enable this setting to ensure that transformed images are saved as RGB.
# useRawExternalUrl [bool]
Default: false
By default Imager will do some basic URL encoding to external URL's to fix common issues. If your external URL's is prepped for
use by an external service, you might need to disable this by enabling this setting.
# skipExecutableExistCheck [bool]
Default: false
By default Imager will check if the executables for the post-transform optimizations exists. If you have basedir restrictions on, or for some other reason doesn't want to do this check, set this to true.
# removeTransformsOnAssetFileops [bool]
Default: false
If enabled, transforms will be remove when an asset is deleted or moved to a different folder.
Please note, Imager will only delete the transforms in the local file system path, it will not remove anything from external storages.
WARNING
If you're using any kind of front-side cache that doesn't break automatically when your assets change, it's probably a bad idea to enable this. You'll end up having references to image transforms that have been deleted, in your cached code.
# curlOptions [array]
Default: array()
Allows you to add cURL options (opens new window) to be used when downloading images from an external host.
Example:
'curlOptions' => array(
CURLOPT_SSL_VERIFYPEER => false,
CURLOPT_SSLVERSION => 1,
CURLOPT_SSL_CIPHER_LIST => 'TLSv1'
),
You can also override the default options, which currently is:
$defaultOptions = array(
CURLOPT_HEADER => 0,
CURLOPT_FOLLOWLOCATION => 1,
CURLOPT_TIMEOUT => 30
);
Make sure you don't set CURLOPT_FILE, since it is set by Imager to be the output location for the downloaded file.
# runJobsImmediatelyOnAjaxRequests [bool]
Default: true
Craft automatically runs any pending tasks on normal site requests, but not on ajax-request, leaving any optimization jobs that Imager has created in a queue that is run on the next CP request. By default Imager solves this by triggering queue/run manually if the request was an ajax request, and a task was created (curl needed). You can disable this behavior by changing this setting to false.
# fillTransforms [bool|string]
Default: false
Enable this setting to automatically fill a transform array with additional transforms based on fillAttribute and fillInterval.
As of 4.3.0, you can use 'auto' as the value, to use autoFillCount to fill with the necessary transforms.
# fillAttribute [string]
Default: 'width'
Attribute to be used when filling in the transforms array. Can be any valid numeric attribute.
# fillInterval [string]
Default: 200
Interval to be used when filling in the transforms array. This should always be a positive integer, Imager will automatically figure out if
the transform has been ordered in an ascending or descending order.
# autoFillCount [int|string]
Default: 3
As of 4.3.0, if fillTransforms is set to 'auto', autoFillCount will be used to calculate the necessary transforms to fill, based
on the value given. A value of 3 means that Imager will create three transforms between the two transforms supplied, for a total of five.
It's also possible to set it to 'auto', in which case Imager will use the transforms supplied to automagically calculate a reasonable
number of transforms to fill with (don't blame me if it isn't the same amount that you expected!).
# clearKey [string]
Default: ''
Key to use when clearing the transform or remote images cache with the controller actions. An empty string means clearing is disabled.
# useForNativeTransforms [bool]
Default: false
Overrides Craft's internal transform functionality with Imager's. When enabled, myAsset.getUrl({ width: 400 }) will result in an Imager transform.
# useForCpThumbs [bool]
Default: false
Overrides Craft's internal thumb transform in the control panel with Imager's. Mostly a good idea if you're using Imgix, if not you'd probably be better off not enabling this.
# hideClearCachesForUserGroups [array]
Default: []
By default, clear cache paths will be added to Craft's native cache utility for all users who have
access to it. If you want to disable this for certain user groups, you can add the group handle or id
to this array.
# transformerConfig [array]
Default: null
Config settings that can be used by custom transformers.
TIP
For more information check out the documentation on custom transformers.
# imgixProfile [string]
Default: 'default'
Imgix config settings profile to be used. Must correspond to a key in imgixConfig.
# imgixApiKey [string]
Default: ''
A valid Imgix API key is required to enable the Imgix purging (opens new window) features. Note that in addition to setting the imgixApiKey setting, you can also add per-profile API keys for specific sources inside the imgixConfig configuration object – useful if you're using sources belonging to different Imgix accounts.
# imgixEnableAutoPurging [bool]
Default: true
Attempts to purge (opens new window) images automatically when the Asset is replaced, or edited with the Image Editor (i.e. cropped, resized etc). An Imgix API key is required to enable purging.
# imgixEnablePurgeElementAction [bool]
Default: true
Adds a "Purge from Imgix" element action to the Asset index, for manually triggering purge. Note that if purging is not possible (i.e. if there's no Imgix API key set or there are no purgable profiles in the imgixConfig array) the element action will not display, regardless of this setting.
# imgixConfig [array]
An array of configuration objects for Imgix, where the key is the profile handle. The configuration object takes the following settings:
domain (string): The Imgix source domain.
useHttps (bool): Indicates if generated Imgix URLs should be https or not.
signKey (string): If you've protected your source with secure URLs, you must provide the sign key/token. An empty string indicates that the source is not secure.
sourceIsWebProxy (bool): Indicates if your Imgix source is a web proxy or not. Note that web proxy sources will be excluded from purging.
useCloudSourcePath (bool): If enabled, Imager will prepend the Craft source path to the asset path, before passing it to the Imgix URL builder. This makes it possible to have one Imgix source pulling images from many Craft volumes when they are on the same S3 bucket, but in different subfolder. This only works on volumes that implements a path setting (AWS S3 and GCS does, local volumes does not).
addPath (string|array): Prepends a path to the asset's path. Can be useful if you have several volumes that you want to serve with one Imgix web folder source. If this setting is an array, the key should be the volume handle, and the value the path to add. See example below.
getExternalImageDimensions (bool): Imager does its best at determining the dimensions of the transformed images. If the supplied asset is on Craft source, it's easy because Craft records the original dimensions of the image in the database. But if the image is external, it's not that easy. Imager will try to determine the size based on the transform parameters, and if both width and height, or ratio is provided, it'll usually be able to. But if you only transform by one attribute, it may not be possible. In these cases Imager will by default download the source image and check the dimensions to calculate the missing bits.
By disabling this setting, you're telling Imager to never download external images, and to just give up on trying to figure out the dimensions. If you supplied only width to the transform, height will then be set to 0. If you don't need to use height in your code, that's totally fine, and you've managed to squeeze out a bit more performance.
excludeFromPurge (bool): Exclude this source from purging. Note that profiles with the sourceIsWebProxy setting set to true will be excluded from purging regardless of this value. This setting affects both automatic purging when Assets are replaced (or edited with the Image Editor) and manual purges triggered by the element action.
apiKey (string): Will override the imgixApiKey setting when Imager attempts to purge images for a particular profile. Useful if you use sources belonging to different Imgix accounts.
defaultParams (array): You can use this setting to set default parameters that you want passed to all your Imgix transforms. Example:
'defaultParams' => ['auto'=>'compress,format', 'q'=>80]
The following example shows a setup that uses two Imgix sources, one that's pointed to a Craft volume, and one that is used for external images:
'imgixConfig' => [
'default' => [
'domain' => 'imager.imgix.net',
'useHttps' => true,
'signKey' => 'XxXxXxXx',
'sourceIsWebProxy' => false,
'useCloudSourcePath' => true,
'getExternalImageDimensions' => true,
'defaultParams' => ['auto'=>'compress,format', 'q'=>80],
],
'external' => [
'domain' => 'imager-external.imgix.net',
'useHttps' => true,
'signKey' => 'XxXxXxXx',
'sourceIsWebProxy' => true,
'useCloudSourcePath' => true,
'getExternalImageDimensions' => true,
'defaultParams' => ['auto'=>'compress,format', 'q'=>80],
]
]
This example shows how you can serve several Craft volumes from one Imgix web folder source using addPath. The Imgix source should
be set up to point to a location that lets you append the path in addPath, and the assets full path, to it, to create the full, public URL:
'imgixConfig' => [
'default' => [
'domain' => 'imager-multi.imgix.net',
'useHttps' => true,
'signKey' => 'XxXxXxXx',
'sourceIsWebProxy' => false,
'addPath' => [
'images' => 'images',
'documents' => 'documents',
'otherstuff' => 'other/stuff',
],
'getExternalImageDimensions' => true,
'defaultParams' => ['auto'=>'compress,format', 'q'=>80],
]
]
To specify which profile to use in your templates you override imgixProfile like this:
{% set transform = craft.imagerx.transformImage(externalUrl, { width: 400 }, {}, { imgixProfile: 'external' }) %}
# optimizeType [string]
Default: 'job'
Allowed values: 'job', 'runtime'
By default all post-transform optimizations are done as a Craft queue job that is run after the request has ended. This speeds up the initial transform request, but makes non-optimized images available for a short while until the task has been run. If set to 'runtime', all optimizations will be run immediately.
# optimizers [array]
Default: []
An array of handles to enabled optimizers. Optimizers needs to be configured in optimizerConfig. You can enable as many optimizers as you wish.
Example:
'optimizers' => ['jpegtran', 'gifsicle', 'pngquant']
They will be run in the order specified. It probably isn't a good idea to use several optimizers that optimizes the same file types.
Imager X comes with optimizers for jpegoptim, jpegtran, mozjpeg, optipng, pngquant, gifsicle, tinypng, kraken and imageoptim. More can be added through the new optimizer interface (more info coming!).
# optimizerConfig [array]
The Settings model provides the following default optimizerConfig:
'optimizerConfig' => [
'jpegoptim' => [
'extensions' => ['jpg'],
'path' => '/usr/bin/jpegoptim',
'optionString' => '-s',
],
'jpegtran' => [
'extensions' => ['jpg'],
'path' => '/usr/bin/jpegtran',
'optionString' => '-optimize -copy none',
],
'mozjpeg' => [
'extensions' => ['jpg'],
'path' => '/usr/bin/mozjpeg',
'optionString' => '-optimize -copy none',
],
'optipng' => [
'extensions' => ['png'],
'path' => '/usr/bin/optipng',
'optionString' => '-o2',
],
'pngquant' => [
'extensions' => ['png'],
'path' => '/usr/bin/pngquant',
'optionString' => '--strip --skip-if-larger',
],
'gifsicle' => [
'extensions' => ['gif'],
'path' => '/usr/bin/gifsicle',
'optionString' => '--optimize=3 --colors 256',
],
'tinypng' => [
'extensions' => ['png','jpg'],
'apiKey' => '',
],
'kraken' => [
'extensions' => ['png', 'jpg', 'gif'],
'apiKey' => '',
'apiSecret' => '',
'additionalParams' => [
'lossy' => true,
]
],
'imageoptim' => [
'extensions' => ['png', 'jpg', 'gif'],
'apiUsername' => '',
'quality' => 'medium'
],
]
Please note, the path and options given are just suggestions. You probably need to change this to reflect your environment, and make sure that the options do what you want them to do. Also, not all options is necessarily available in the compiled version of the optimizers (for instance, pngquant doesn't necessarily have --strip compiled in).
Configuration for additional, custom optimizers can also be added.
# storages [array]
Default: []
An array of handles to enabled storages. Storages needs to be configured in storageConfig.
Imager X comes with support for Amazon S3 and Google Cloud Storage.
# storageConfig [array]
The Settings model provides the following default storageConfig:
'storageConfig' => [
'aws' => [
'accessKey' => '',
'secretAccessKey' => '',
'region' => '',
'bucket' => '',
'folder' => '',
'requestHeaders' => array(),
'storageType' => 'standard',
'public' => true,
'cloudfrontInvalidateEnabled' => false,
'cloudfrontDistributionId' => '',
],
'gcs' => [
'keyFile' => '',
'bucket' => '',
'folder' => '',
],
]
Here's an example of how this could look when populated:
'storageConfig' => [
'aws' => [
'accessKey' => 'XYXYYYY99YXYZXXX1YXY',
'secretAccessKey' => 'xY9xXXyYxXXyX9xYxxYyxy9XXyyxxy9XX99XYX9x',
'region' => 'eu-west-1',
'bucket' => 'transformbucket',
'folder' => 'transforms',
'requestHeaders' => array(),
'storageType' => 'standard',
'public' => true,
'cloudfrontInvalidateEnabled' => true,
'cloudfrontDistributionId' => 'YXYZ99ZX99YXY',
],
'gcs' => [
'keyFile' => '/absolute/path/to/key/gcs-31a21242cf7c.json',
'bucket' => 'transformbucket',
'folder' => 'transforms',
]
]
This is just provided as an example, make sure you override this with your own credentials.
And, make sure that you remember to enable the storage configs you want to use by default,
using the storages config setting, like so:
'storages' => ['aws'],
'storageConfig' => [
'aws' => [
'accessKey' => 'XYXYYYY99YXYZXXX1YXY',
'secretAccessKey' => 'xY9xXXyYxXXyX9xYxxYyxy9XXyyxxy9XX99XYX9x',
'region' => 'eu-west-1',
'bucket' => 'transformbucket',
'folder' => 'transforms',
'requestHeaders' => array(),
'storageType' => 'standard',
'cloudfrontInvalidateEnabled' => true,
'cloudfrontDistributionId' => 'YXYZ99ZX99YXY',
],
'gcs' => [
'keyFile' => '/absolute/path/to/key/gcs-31a21242cf7c.json',
'bucket' => 'transformbucket',
'folder' => 'transforms',
]
]
TIP
The keyFile parameter of the Google Cloud external storage, can also be
set to the contents of the key file. You can provide this via an environment
variable. Remember to encode the \n characters in the file as \\n, since
\ is an escape character in the environment file.
For more information about the concept of storages, please refer to this section.
# Configuring named transforms
Named transforms can be configured by creating an imager-x-transforms.php file
in your config folder, and adding transforms as needed.
The config file should return an array where the keys are the handles of the
named transforms, and each value is an array that can have the values
transforms, defaults and configOverrides, which corresponds to the
three last parameters of the transformImage method.
<?php
return [
'heroImage' => [
'transforms' => [
['width' => 600],
['width' => 1800],
],
'defaults' => [
'ratio' => 16/9,
'jpegQuality' => 80
],
'configOverrides' => [
'fillTransforms' => true,
'fillInterval' => 300,
]
],
'listThumbnail' => [
'transforms' => [
['width' => 200],
['width' => 400],
['width' => 600],
],
'defaults' => [
'ratio' => 4/3,
'format' => 'jpg'
]
]
];
For more information, see the documentation page for named transforms.
# Configuring automatic generation of transforms
To set up automatic generation of transforms on file upload or entry/field save,
create an imager-x-generate.php file in your config folder, and configure the
parameters below.
# generateOnlyForLiveElements [bool]
Default: false
By default, Imager will generate images for all elements, no matter what
their status is. By setting this to true, Imager will only generate
transforms for live elements.
# generateForDrafts [bool]
Default: false
By default, Imager does not generate transforms for drafts. By setting
this to true, Imager will also generate transforms for drafts.
# volumes [array]
Default: []
Defines which transforms should be created for each volume. The key should
be the handle of the volume, and the value is an array of handles for
named transforms that should be generated for
this volume.
'volumes' => [
'images' => ['heroImage', 'standardImage', 'listImage'],
'employeeImages' => ['employeeListImage', 'employeeImage']
]
TIP
Creating transforms based on volumes can be quite... unpresise. Usually, you'll have a few volumes (in our case, usually one for all images), and the images in them are used for alot of different transforms. If you create all possible transforms for all images, you'll end up with alot of redundant transforms. We recommend using this feature only for the most frequently used transforms, and using elements and fields transforms for the more specific transforms.
# elements [array]
Default: []
Defines transforms that are created when an element is saved, based on an
element type and criteria. The setting takes an array of arrays with the
following four keys:
# elementType [string]
The class definition of the element type that should trigger this defintion.
# criteria [array]
The criteria that will be used to query for matching elements.
# fields [array]
The asset fields that should be used checked for assets.
# transforms [array]
The named transforms that should be generated for the matching assets.
An example says more than a thousand words:
'elements' => [
[
'elementType' => \craft\elements\Entry::class,
'criteria' => [
'section' => 'news',
],
'fields' => ['image', 'articleBlocks:images.images'],
'transforms' => ['heroImage', 'listImage', 'metaImage']
],
[
'elementType' => \craft\elements\Entry::class,
'criteria' => [
'section' => 'news',
],
'fields' => ['listImage'],
'transforms' => ['listImage']
]
],
TIP
The criteria parameter is passed directly to the element query, and takes exactly the same parameters as a standard Craft element query.
# fields [array]
Default: []
Defines transforms that are created when an element is saved, based on fields on the element. The key should be the handle of the fields, and the value is an array of handles for named transforms.
'fields' => [
'employeeImage' => ['employeeThumbnail', 'employeeImage'],
'heroImage' => ['heroImage', 'listImage'],
'listImage' => ['listImage'],
]
TIP
The field handles in fields will target all elements, meaning also for matrix blocks
(which are just another element in Craft). So if you have a field called
image that is attached to an entry type, and a field called image inside
a matrix block, both will match the key image in the example above.