README

A plugin for using Imgix as a transformer in Imager X.

This functionality was originally part of Imager X core, but has been extracted into a separate plugin as of Imager X 6.0.

Requirements

This plugin requires Craft CMS 5.0.0 or later, Imager X 6.0.0 or later, and an account at Imgix.

Usage

Install and configure this transformer as described below. Then, in your Imager X config, set the transformer to imgix, ie:

'transformer' => 'imgix',

Transforms are now by default transformed with Imgix, test your configuration with a simple transform like this:

{% set transform = craft.imagerx.transformImage(asset, { width: 600 }) %}
<img src="{{ transform.url }}" width="600">
<p>URL is: {{ transform.url }}</p>

If this doesn't work, make sure you've configured a defaultProfile, have a profile with the correct name, and that Imgix is configured correctly.

Note

If you're upgrading from Imager X 5.x, and overriding imgixProfile in your templates, this will not work anymore. You instead need to set profile in a transformerConfig object. Ie. { imgixProfile: 'someprofile' } becomes { transformerConfig: { profile: 'someprofile' } }.

Cave-ats, shortcomings, and tips

This transformer only supports a subset of what Imager X can do when using the default craft transformer.

To pass additional options directly to Imgix, you can use the transformerParams transform parameter. Example:

{% set transforms = craft.imagerx.transformImage(asset, 
    [{width: 400}, {width: 600}, {width: 800}], 
    { ratio: 2/1, transformerParams: { sharp: 10 } }
) %}

Refer to the Imgix Rendering API Documentation for more information and parameters to use.

Installation

To install the plugin, follow these instructions:

1. Install with composer via composer require spacecatninja/imager-x-imgix-transformer from your project directory.
2. Install the plugin in the Craft Control Panel under Settings > Plugins, or from the command line via ./craft plugin/install imager-x-imgix-transformer.

Configuration

You can configure the transformer by creating a file in your config folder called imager-x-imgix-transformer.php, and override settings as needed.

<?php

return [
    '*' => [
        'defaultProfile' => 'default',
        'apiKey' => '',
        'autoPurge' => true,
        'purgeElementAction' => true,

        'profiles' => [
            'default' => [
                'domain' => '',
                'useHttps' => true,
                'signKey' => '',
                'sourceIsWebProxy' => false,
                'useCloudSourcePath' => true,
                'addPath' => '',
                'getExternalImageDimensions' => true,
                'defaultParams' => [],
                'excludeFromPurge' => false,
                'apiKey' => '',
            ],
        ],
    ],
];

Plugin settings

defaultProfile (string, default 'default') The profile to use by default. Can be overridden per transform by passing imgixProfile as a transform parameter.

apiKey (string, default '') Global Imgix API key, used for purging. Can be overridden per profile via the profile's own apiKey setting.

autoPurge (bool, default true) Automatically purge assets from Imgix when they are replaced or moved in Craft.

purgeElementAction (bool, default true) Show a "Purge from Imgix" element action in the Assets index when purging is possible (i.e. a valid API key is configured).

profiles (array) A map of named Imgix source profiles. Each key is the profile name (referenced by defaultProfile or the per-transform imgixProfile parameter), and the value is a profile config array. See profile settings below.

Profile settings

domain (string, default '') Your Imgix source domain, e.g. my-source.imgix.net.

useHttps (bool, default true) Whether to use HTTPS for generated URLs.

signKey (string, default '') Token used to sign URLs. Required when sourceIsWebProxy is true. Found in your Imgix source settings page.

sourceIsWebProxy (bool, default false) Set to true if your Imgix source is a Web Proxy source. A signKey is required in this case.

useCloudSourcePath (bool, default true) Prepend the cloud storage subfolder path to the asset path. Useful when your Imgix source points directly to an S3 or GCS bucket that also has a Craft volume subfolder configured.

addPath (string|array, default '') Prepend an additional path segment to all asset paths. Can be a string to apply to all volumes, or an array keyed by volume handle to apply different prefixes per volume.

getExternalImageDimensions (bool, default true) Fetch image dimensions for external URL sources by downloading the image. Disable this if you are using external URLs and don't need accurate width/height on the transformed image model.

defaultParams (array, default []) Default Imgix URL parameters to apply to every transform using this profile. Example: ['auto' => 'compress,format'].

excludeFromPurge (bool, default false) Exclude this profile from purge operations.

apiKey (string, default '') Profile-specific Imgix API key for purging. Overrides the plugin-level apiKey for this profile.

Price, license and support

The plugin is released under the MIT license. It requires Imager X, which is a commercial plugin available in the Craft plugin store. If you need help, or found a bug, please post an issue in this repo, or in Imager X' repo (preferably).