Policies

Last updated: August 21st 2026
Behaviour that applies across generation, cleanup, and tag delivery lives under policies in system/user/config/super_images.php.
'policies' => [
    'encode' => [ /* … */ ],
    'geometry' => [ /* … */ ],
    'safety' => [ /* … */ ],
    'cleanup' => [ /* … */ ],
    'fallback' => [ /* … */ ],
],

Encode

Controls how encoded derivatives are written (metadata stripping, progressive JPEG, PNG compression level).
KeyDefaultEffect
stripMetadatatrueRemove EXIF/IPTC when the driver supports it
progressivefalseProgressive/interlaced output where supported
pngCompression6PNG compression level (0–9)

Geometry

KeyDefaultEffect
allowUpscalefalseResize/fit will not enlarge beyond the source
sharpnesssharpDownscale sharpness: soft | normal | sharp | extra

Changing sharpness regenerates derivatives (it is part of the identity). Prefer Imagick or libvips over GD for the sharpest downscales.

Safety

KeyDefaultEffect
maxSourcePixels40_000_000Soft cap on source width × height after load

Cleanup (file lifecycle)

Automatic derivative removal when EE files are deleted or replaced.

KeyDefaultEffect
onFileDeletetruePurge indexed derivatives when a File is deleted
onFileReplacetruePurge indexed derivatives when a File is replaced

Indexed entries record identity, storage path, and adapter. Preview artifacts under preview/ use cleanup.previewRetentionDays instead.

Bulk CLI cleanup (--orphaned / --all) is also gated by cleanup.generatedRetentionDays.

Fallback

Optional delivery fallback when planning fails (missing file, invalid source).

KeyDefaultEffect
enabledfalseRetry planning once with the fallback File
fileIdnullFile ID to use as fallback
Example:
'policies' => [
    'fallback' => [
        'enabled' => true,
        'fileId' => 42,
    ],
],

Fallback is attempted at most once per call. Strict PHP generate() still throws.