Imager X 3.0 Docs

# Extending Imager X

In addition to the built-in functionality, you can extend Imager to make it even more powerful. You can add your own effects, optimizers, external storages PRO, and even transformers PRO.

# Effects

Custom effects can be added by listening for the EVENT_REGISTER_EFFECTS event:

Event::on(\spacecatninja\imagerx\ImagerX::class,
    \spacecatninja\imagerx\ImagerX::EVENT_REGISTER_EFFECTS,
    static function (\spacecatninja\imagerx\events\RegisterEffectsEvent $event) {
        $event->effects['myeffect'] = MyEffect::class;
    }
);

The registered class must implement the ImagerEffectsInterface (opens new window), and can then be used in your templates like this:

{% set transform = craft.imagerx.transformImage(image, { width: 800 }, { effects: { myeffect: [0.6, 'rgb(210,89,222)'] } }) %}

Have a look at the built-in effects (opens new window) for more examples of how effects can manipulate the image.

# Optimizers

Custom optimizers can be added by listening for the EVENT_REGISTER_OPTIMIZERS event:

Event::on(\spacecatninja\imagerx\ImagerX::class,
    \spacecatninja\imagerx\ImagerX::EVENT_REGISTER_OPTIMIZERS,
    static function (\spacecatninja\imagerx\events\RegisterOptimizersEvent $event) {
        $event->optimizers['myoptimizer'] = MyOptimizer::class;
    }
);

The registered class must implement the ImagerOptimizeInterface (opens new window), and can then be used in your config like this:

'optimizers' => ['myoptimizer'],
'optimizerConfig' => [
    'myoptimizer' => [
        'extensions' => ['jpg'],
        'path' => '/usr/local/bin/myoptimizer',
        'options' => '-t -n40',
    ],
],

Please note that you decide yourself which config parameters your optimizer needs, but you should always add an 'extensions' parameter as shown above.

Have a look at the built-in optimizers (opens new window) for more examples of what optimizers can do.

# External storages

Custom external storages can be added by listening for the EVENT_REGISTER_EXTERNAL_STORAGES event:

Event::on(\spacecatninja\imagerx\ImagerX::class,
    \spacecatninja\imagerx\ImagerX::EVENT_REGISTER_EXTERNAL_STORAGES,
    static function (\spacecatninja\imagerx\events\RegisterExternalStoragesEvent $event) {
        $event->storages['mystorage'] = MyExternalStorage::class;
    }
);

The registered class must implement the ImagerStorageInterface (opens new window), and can then be used in your config like this:

'storages' => ['mystorage'],
'storageConfig' => [
    'mystorage' => [
        'accessKey' => 'KJA5GH8FDD3FR9T',
        'secretAccessKey' => 'awIoJA76e3baHGD94DaeF6',
        'region' => 'eu-west-1',
        'bucket' => 'mytransforms',
    ],
],

Please note that you decide yourself which config parameters your external storage needs.

Have a look at the built-in storages (opens new window) for more examples of how external storages work.

# Transformers

TIP

Transformers are the most complex thing you can extend Imager with, and is not for the faint hearted. 😮 If you still want to give it a go, make sure you have a look at the existing transformers and get an understanding of the overall flow.

Custom transformers can be added by listening for the EVENT_REGISTER_TRANSFORMERS event:

Event::on(\spacecatninja\imagerx\ImagerX::class,
    \spacecatninja\imagerx\ImagerX::EVENT_REGISTER_TRANSFORMERS,
    static function (\spacecatninja\imagerx\events\RegisterTransformersEvent $event) {
        $event->transformers['mytransformer'] = MyTransformer::class;
    }
);

The registered class must implement the TransformerInterface (opens new window), and can then be used in your config like this:

'transformer' => 'mytransformer',

The transformer should return a model representing the transformed image which implements TransformedImageInterface (opens new window). Some properties may not be applicable for all kinds of transformers, but the model should handle this gracefully (ie, return empty values that the template code can check for).

← Troubleshooting →