README

Beta release – The configuration API is stable enough for production use, but we may still make small non-breaking refinements before 1.0. Report issues on GitHub so we can lock the final shape.

Replace Craft CMS built-in image transforms with config-driven external service URLs. Zero template changes — asset.getUrl(), .srcset(), named transforms, GraphQL @transform, and CP thumbnails all work as before, but transform URLs point to your external image service.

Scope and Requirements

This plugin does not provide filesystem providers or storage services.

Craft Transform Mapper does not register or implement any filesystem adapters (local, S3, GCS, etc.) and does not supply any external image optimization or CDN services (Imgix, Cloudflare Images, etc.).

Users must install and configure their own storage provider plugins and transform services separately. Those plugins handle registering the actual filesystem volumes and transform backends.

This plugin’s only role is to ensure that transforms use the correct URL based transforms service you decide to employ.

Requirements

• Craft CMS 5.0.0 or later
• PHP 8.2 or later

Installation

composer require craftyhedge/craft-transform-mapper
php craft plugin/install transform-mapper

The plugin is currently in beta. The configuration API and behavior are stable enough for production use, but we may still make small non-breaking refinements before the 1.0 release.

During the beta period, we recommend using a version constraint such as ^0.1 or 0.1.* so you can control upgrades. Once we reach 1.0, the plain composer require command above will continue to work and will install the stable release.

Quick Start

1. Install the plugin (see the Installation section above).
2. Open example-configs and copy the file closest to your image service (Cloudflare, imgix, Bunny, Cloudinary, or the generic webhook example). These are starting points — not all have been tested in production.
3. Save it as config/transform-mapper.php and set the environment variables it requires.
4. Point your AI assistant at the @see links in that file’s header (plus the Available Tokens table below) to adapt the urlPattern, parameter mappings, signing, and purge settings.
5. Ensure 'replaceDefault' => true (the default) so the plugin handles all transforms.

For the full list of configuration options and token behavior, continue to the sections below.

How It Works

The plugin overrides Craft's default ImageTransformer via the Yii DI container. When replaceDefault is true, all calls to Craft::createObject(['class' => ImageTransformer::class]) resolve to TransformMapper — intercepting inline transforms, DB-stored named transforms, and GraphQL @transform directives.

The CP image editor (crop, rotate, flip) continues to work via inherited parent methods.

Limitations

• External purge only runs when configured (purgeEnabled + webhook URL or purge callable).
• The CP image editor still processes images locally and writes to the transform filesystem.

Configuration

The example-configs directory contains ready-to-adapt starting points for the most common providers:

• cloudflare.php – Cloudflare Image Resizing
• imgix.php – imgix
• bunny.php – Bunny Optimizer
• cloudinary.php – Cloudinary
• webhook.php – Generic webhook-based purge (use as a template for other services)

Note on the examples: These are provided as starting points and reference implementations. Not all configurations have been tested in production by the maintainers. If you get one working well for your service, please consider contributing your version — it helps improve the plugin for others.

Each file includes @see links in the header pointing to the official service documentation.

Point your AI agent at the documentation links inside the relevant example (plus the Available Tokens table below) to generate or customize the exact config/transform-mapper.php for your setup.

Copy the closest example to config/transform-mapper.php, set the environment variables it references, and adapt the URL pattern, mappings, signing, and purge logic according to the provider docs linked in the file.

Available Tokens

Tokens with null values become empty strings. Empty query parameters are automatically stripped. See cleanUrl() in src/helpers/UrlBuilder.php.

Use {path} / {pathRaw} when your provider expects an unencoded source path (for example, Cloudflare Image Resizing and standard imgix source URLs). Use {pathEncoded} when your provider or URL shape requires percent-encoding.

URL Signing

To sign transform URLs, set the optional sign callable in config. The callable receives the unsigned URL and must return a signed URL string. Exceptions thrown by the callable are caught and re-thrown as ImageTransformException. Non-string return values likewise throw ImageTransformException.

'sign' => function(string $url): string {
    // Add provider-specific signing here.
    return $url;
},

See the provider-specific examples (and the official documentation links embedded in their file headers) in example-configs. Use them as templates and point your AI agent at the docs referenced there (plus the Available Tokens table above) to generate the exact config needed for your use case.

Purge Invalidations

When Craft invalidates transforms for an asset, Transform Mapper can notify your external image service so that cached variants are cleared.

Set purgeEnabled to true, then choose one of two transports:

• Webhook transport via purgeWebhookUrl (plus optional method, headers, and timeout)
• Custom callable via purge, for provider SDKs or complex logic

purgeMode controls execution strategy:

• async (recommended): dispatches a queue job
• sync: runs the purge in the request lifecycle

If both webhook settings and a custom purge callable are configured, the callable takes precedence. A custom callable returning false is treated as a non-retryable failure.

Async purges require queue workers to be running.

For full details on transports, async retry controls, webhook response policies, status code overrides, logging behavior, payload customization, the webhook JSON format, and production recommendations, see PURGING.md.

A few commonly tuned flags are also available at the top level:

• purgeFailSilently (default true)
• purgeDryRun (default false)