Configuration

Primary file:

system/user/config/super_images.php

Start from:

system/user/addons/super_images/config/super_images.example.php

All deployable settings — including derivative naming and sources — live in the PHP file. Control Panel → Settings is read-only (displays effective values, examples, and token glossary).

Never put access keys in the example file or in documentation. Use environment variables.

Top-level keys

Key	Purpose
enabled	Master switch. false = no transforms
defaultProfile / defaultFormat	Used when tags/CLI omit profile or format
driver	auto \| libvips \| imagick \| gd — see Drivers
delivery	Before-page-load generation + thumbnail placeholder
autoGenerate	Queue on file upload / replace
sources	Local path roots + remote host allow-list
runtime	Signed lazy-generate URL settings
storage	Adapters, markers, naming templates
encoders	Native encode quality
optimizers	Post-encode binaries
profiles	Named variant × format sets
upload_directories / folders / fields	Scoped overrides
cleanup	Preview / generated retention
policies	Encode, geometry, safety, cleanup, fallback — Policies

Core

return [
    'enabled' => true,
    'defaultProfile' => 'responsive',
    'defaultFormat' => 'webp',
    'driver' => 'auto', // libvips → imagick → gd when auto
];

Profiles

'profiles' => [
    'responsive' => [
        'formats' => ['jpg', 'webp'],
        'variants' => [
            'sm' => ['width' => 576],
            'md' => ['width' => 768],
            'lg' => ['width' => 992],
            'xl' => ['width' => 1280],
            '2xl' => ['width' => 1600],
        ],
        'defaults' => [
            'position' => 'center-center',
            'mode' => 'fit',
            'jpegQuality' => 80,
        ],
    ],
],

Passing operations on a tag replacesthe profile variant pipeline. Always start custom ops with geometry (fit/crop / fill).

Sources

'sources' => [
    'local' => [
        'enabled' => true,
        'allowedRoots' => [
            '{site_path}images',
            '{site_path}uploads',
        ],
    ],
    'remote' => [
        'enabled' => true,
        'allowedHosts' => [
            'picsum.photos',
            '*.picsum.photos',
        ],
        'timeout' => 10,
        'maxBytes' => 25_000_000,
        'maxRedirects' => 3,
    ],
],

Remote URLs are denied unless the host is allow-listed. Required for the portable demo’s Picsum original.

CP → Settings → Sources shows the current allow-lists and a copy-paste snippet for adding roots/hosts.

Environment variables

Variable	Use
SUPER_IMAGES_SIGNING_KEY	Runtime URL HMAC when runtime.signingSecret is null
SUPER_IMAGES_STORAGE	Default adapter handle
SUPER_IMAGES_S3_* / CDN URL	Remote storage credentials and public URL
SUPER_IMAGES_JPEGOPTIM, SUPER_IMAGES_CWEBP, …	Optimizer binary paths — see Encoders & optimizers

Delivery & runtime

See Delivery.

'delivery' => [
    'generateBeforePageLoad' => true,
    'thumbnail' => [
        'enabled' => true,
        'width' => 32,
        'format' => 'jpg',
        'quality' => 50,
        'variant' => 'thumb',
    ],
],

'runtime' => [
    'enabled' => true,
    'signingSecret' => getenv('SUPER_IMAGES_SIGNING_KEY') ?: null,
    'urlTtl' => 3600,
    'maxWidth' => 4096,
    'maxHeight' => 4096,
    'maxPixels' => 20_000_000,
],

Auto-generate

'autoGenerate' => [
    'enabled' => true,
    'onUpload' => true,
    'onReplace' => true,
    'queue' => true,
],

Upload directories & fields

Per upload-directory handle (not Craft volumes):

'upload_directories' => [
    'images' => [
        'profile' => 'responsive',
        'storage' => 'local',
        'autoGenerate' => true,
    ],
],

'folders' => [],
'fields' => [],