Storage & naming

Last updated: August 21st 2026

Configure adapters in system/user/config/super_images.php. Derivatives live outside File Manager upload folders unless you point an adapter there on purpose.

Local

'storage' => [
    'default' => $_ENV['SUPER_IMAGES_STORAGE'] ?? 'local',
    'markers' => [
        'enabled' => true,
        'path' => '{cache_path}super_images/markers',
    ],
    'adapters' => [
        'local' => [
            'type' => 'local',
            'path' => '{site_path}transforms/super-images',
            'baseUrl' => '{site_url}transforms/super-images',
        ],
    ],
],

{site_path}, {site_url}, and {cache_path} are Super Images path tokens in config, not EE template tags.

S3-compatible (S3, Spaces, R2)

's3' => [
    'type' => 's3', // or spaces, r2
    'keyId' => $_ENV['SUPER_IMAGES_S3_KEY'] ?? null,
    'secret' => $_ENV['SUPER_IMAGES_S3_SECRET'] ?? null,
    'bucket' => $_ENV['SUPER_IMAGES_S3_BUCKET'] ?? null,
    'region' => $_ENV['SUPER_IMAGES_S3_REGION'] ?? 'us-east-1',
    'endpoint' => $_ENV['SUPER_IMAGES_S3_ENDPOINT'] ?? null,
    'prefix' => 'transforms/super-images/',
    'baseUrl' => $_ENV['SUPER_IMAGES_S3_BASE_URL'] ?? '',
    'usePathStyle' => true,
],

Do not commit credentials. baseUrl must be the hostname that actually serves the objects.

Naming

'naming' => [
    // File Manager files (and Assets URLs that resolve to File IDs)
    'assetPath' => '{folderHash}/{transformHash}/{fileId}/{basename}-{variant}.{ext}',
    // Local path / true remote URL sources
    'path' => '{folderHash}/{transformHash}/{sourceKey}/{basename}-{variant}.{ext}',
    'transformHashLength' => 16,
    'includeUploadDirInFolderHash' => false,
],

{transformHash} groups all variants and formats for the same profile into one folder (it excludes variant/format from the hash). Changing the profile, custom operations, driver, or encode policy creates a new folder.

Assets {url} values that point at an EE upload-directory file are resolved to a File Manager fileId, so they use assetPath just like {file:ID:url}.

Tokens include {folderHash}, {transformHash}, {fileId}, {sourceKey}, {basename}, {variant}, {profile}, {ext}, {identity}, {identityShard}.

Existence markers

Remote adapters (S3, Spaces, R2) use small local marker files (default under {cache_path}super_images/markers) so cache hits do not require a remote object check every time.

Flow on a cache hit:

  1. Check the local marker file (fast).
  2. If no marker, check the per-file derivative index.
  3. If still unknown, call the adapter’s remote exists check (S3 doesObjectExist — typically ~100–300 ms).

Markers are written automatically after each successful remote upload. Metadata (width, height, size) is stored in the marker so Playground and tags can show dimensions without re-fetching the object.


If cache hits look slow after a storage switch, or Playground shows cache hit with high duration on remote storage:
php eecli.php super_images:cleanup --all --dry-run
php eecli.php super_images:cleanup --all
php eecli.php super_images:generate --upload-dir=images