README

This module provides an Small Pics transformer for Imager X.

Requirements

Craft CMS 5.0.0+
Imager X 5.1.0+
PHP 8.2+

Installation

composer require smallpics/imagerx-smallpics
php craft plugin/install imagerx-smallpics

Configuration

Add the Small Pics configuration to your Imager X Small Pics transformer config file (config/imagerx-smallpics.php):

Options

baseUrl

Base URL for your Small Pics origin.

Example: https://your-origin.smallpics.io/

secret

Default: null.

Optional signing secret for your Small Pics image origin.

Setting this will enable URL signing for generated URLs. If your Small Pics config has signed URL disabled, then including a signature will have no effect on the transformed images.

transformSvgs

Default: false.

Whether SVG images should be transformed.

transformAnimatedGifs

Default: false.

Whether animated GIF images should be transformed.

defaultParams

Global default parameters for Small Pics transformations. See the Small Pics API documentation for available options.

These are applied in addition to any default parameters configured per origin (if any), and are merged with any transformerParams passed when transforming an image.

origins

An array of named origin configurations.

If you require multiple Small Pics origins, you can configure them here instead of configuring the root-level options.

Each origin configuration supports the same options as above, see multi-origin config below for an example configuration and multi-origin usage for how to select an origin when transforming an image.

Example configurations

Single origin config

return [
    'baseUrl' => getenv('SMALLPICS_BASE_URL'),
    'secret' => getenv('SMALLPICS_SECRET') ?: null,
    'transformSvgs' => false,
    'transformAnimatedGifs' => false,
    'defaultParams' => [],
];

Multi-origin config

It is possible to configure multiple origins. You can then select the origin to use when transforming an image by setting the origin key in the transformerParams array.

return [
    'defaultParams' => [
        'format' => 'webp',
    ],
    'origins' => [
        \smallpics\imagerx\smallpics\models\Settings::DEFAULT_ORIGIN_NAME => [ // Or simply 'default'
            'baseUrl' => getenv('SMALLPICS_DEFAULT_ORIGIN_BASE_URL'),
            'secret' => getenv('SMALLPICS_DEFAULT_ORIGIN_SECRET') ?: null,
            'transformSvgs' => false,
            'transformAnimatedGifs' => false,
            'defaultParams' => [
                'quality' => 80,
            ],
        ],
        'origin2' => [
            'baseUrl' => getenv('SMALLPICS_ORIGIN2_BASE_URL'),
            'secret' => getenv('SMALLPICS_ORIGIN2_SECRET') ?: null,
            'transformSvgs' => true,
            'transformAnimatedGifs' => false,
            'defaultParams' => [
                'format' => 'png',
                'quality' => 90
            ],
        ],
    ],
];

You can also set the name of the default origin by setting the defaultOrigin key in the config:

return [
    'defaultOrigin' => 'spaces',
    'origins' => [
        'spaces' => [
            'baseUrl' => getenv('SMALLPICS_SPACES_BASE_URL'),
            // ...
        ],
        's3' => [
            'baseUrl' => getenv('SMALLPICS_S3_BASE_URL'),
            // ...
        ],
    ],
];

Usage

Once installed and configured, you can use the transformer with Imager X:

{% set transformedImages = craft.imagerx.transformImage(rawImage, [
  { width: 74, height: 74 },
  { width: 120, height: 120 },
  { width: 172, height: 172 },
  { width: 254, height: 254 }
], {
  mode: 'crop',
  transformerParams: {
    padding: 10,
    background: 'ff0000',
    border: {
      width: 10,
      color: '000000',
      borderMethod: 'overlay',
    }
  },
}) %}

Multi-origin usage

{% set transformedImages = craft.imagerx.transformImage(rawImage, [
  { width: 74, height: 74 },
  { width: 120, height: 120 },
  { width: 172, height: 172 },
  { width: 254, height: 254 }
], {
  mode: 'crop',
  transformerParams: {
    origin: 'origin2',
    padding: 10,
    background: 'ff0000',
    border: {
      width: 10,
      color: '000000',
      borderMethod: 'overlay',
    }
  },
}) %}

Notes

Take a look at the Small Pics API for a list of available options to use in the defaultParams and transformerParams arrays.

This transformer uses smallpics/smallpics-php under the hood. Take a look there for more usage information.

smallpics / imagerx-smallpics

Maintainers

Details