Processors
The processor setting selects who turns the source
file into the derivatives that land in srcset. Both local modes drive
TYPO3's ImageService exclusively (the binary is whatever your GFX config
selects — GraphicsMagick or ImageMagick); there are no direct
GraphicsMagick/ImageMagick/GD calls.
local:async(default)- Processing is deferred to the first request per variant: a cold
srcsetcandidate points at the signed/_imaginator/endpoint and the middleware materializes the derivative, then 302-redirects to the processed file. Once a derivative exists,srcsetpoints at the static_processed_/…file directly, so warm images skip the middleware entirely. local:sync- Files are processed synchronously at first render time and the static
_processed_/…file URL is written straight intosrcset. Just like the TYPO3 core processes files on first page load if<f:image>is used. The middleware is never involved and requests are plain static-file serves. imgproxy- Offloaded;
srcsetpoints straight at the provider (see Offloaded processing with imgproxy). imgproxy has no result cache — a fronting CDN / reverse-proxy cache is mandatory in production. imagor- Offloaded;
srcsetpoints straight at the provider (see Offloaded processing with imagor). Enable imagor's result storage (or put a fronting cache in front) so derivatives are rendered once, not per hit.
Tip
Integrators can register a custom processor by putting
# on their class (a plain URL
builder is enough for a new CDN provider) and selecting it here — no YAML.
See Custom Processor.
The image endpoint & signing
In local:async mode each candidate URL has one of these forms:
reference: /_imaginator/{16-hex-signature}/r{referenceUid}/{cropVariant}/{width}x{height}.{ext}
file: /_imaginator/{16-hex-signature}/f{fileUid}/{cropVariant}/{width}x{height}.{ext}
The uid is site-unique, so no storage segment is needed. A PSR-15 middleware
verifies the signature, re-checks the width against the
ladder, processes the image and 302-redirects to the
processed file with Cache-.
Note
A forged or tampered URL returns 403, and only ladder-quantized widths are ever processed — so the endpoint cannot be abused to exhaust the server with arbitrary sizes.
The signing secret is derived automatically from the global
encryption; no configuration is needed. See Signing,
and Crop & Focus Area for how the editor's crop is
honoured server-side.
Offloaded processing with imgproxy
With processor set to imgproxy, srcset URLs
point straight at an imgproxy service, the webserver
never touches pixels, and the signed /_imaginator/ endpoint is unused. Each
candidate is built as:
{processorBaseUrl}/{signature}/rs:fill:{w}:{h}/g:sm/q:{quality}/plain/{source}@{ext}
For a reference with a stored crop or focus area the editor's crop variant
is replayed externally: the same ratio-fitted, focus-positioned rect local
processing uses goes into imgproxy's crop op (c:{cw}:{ch}:nowe:{x}:{y},
replacing g:sm), so external output matches local output. Plain files and
references without editor crop use smart gravity.
Offloading also sidesteps local encoder limits: e.g. AVIF at large dimensions that a thin GraphicsMagick build fails to encode.
Tip
For local development, the ddev-imgproxy add-on runs imgproxy next to the web container:
ddev add-on get barbieswimcrew/ddev-imgproxy
ddev restart
It sets IMGPROXY_BASE_URL to the web container and runs keyless, so
processorBaseUrl is the add-on URL
(https://<project>.ddev.site:8081) and the sign key/salt stay empty.
Offloaded processing with imagor
With processor set to imagor, srcset URLs
point straight at an imagor service (thumbor-compatible
URL grammar). Each candidate is built as:
{processorBaseUrl}/{signature}/{w}x{h}/smart/filters:quality({q}):format({ext})/{source}
The signature is a URL-safe base64 HMAC of the path, keyed with
processorSignKey — imagor's plain-string
IMAGOR_SECRET (run imagor with IMAGOR_SIGNER_TYPE=sha256).
processorSalt is unused; imagor's scheme has no
salt. An empty key emits unsafe URLs, which imagor only accepts with
IMAGOR_UNSAFE=1 (dev only). As with imgproxy, a reference's stored editor
crop is replayed externally, the crop rect becomes imagor's manual crop segment
({x1}x{y1}:{x2}x{y2}, replacing smart); plain files and references
without editor crop fall back to smart detection.
Unlike the edge-cached SaaS providers, imagor caches derivatives only when
result storage is enabled (FILE_RESULT_STORAGE_BASE_DIR or the S3
equivalent). Enable it or front imagor with a CDN / reverse-proxy cache,
otherwise every browser hit reprocesses the image.
Tip
For local development this repository ships
.ddev/docker-compose.imagor.yaml: imagor listens on
https://<project>.ddev.site:8083 with the secret
imaginator-dev-secret and result storage on a volume — so
processorBaseUrl is that URL and
processorSignKey the dev secret.