For editors 

A backend aspect-ratio field per content element lets editors pick the framing once per breakpoint and get uniform, consistent images across every image of that content element, with no ragged grids from mismatched upload dimensions. Crop and focus area are honored, so the chosen subject stays in frame at every size.

For developers 

Drop one <i:image> and get sharp, perfectly-sized images on every device. No hand-tuned sizes, no breakpoint lists, no layout shift (CLS). The width ladder bounds processing to a fixed set of sizes, so you serve fewer, smaller bytes and score better Core Web Vitals (LCP/CLS) out of the box. Processing is pluggable: classic sync on first request, async via a signed middleware endpoint (default), or an external processor such as imgproxy.

Requirements 

• PHP 8.3+ (tested on 8.3 / 8.4 / 8.5)
• TYPO3 13.4 LTS or 14.3 LTS
• A working image processor (GraphicsMagick or ImageMagick, configured through TYPO3's standard GFX settings) for local processing; alternatively an external processor (e.g. imgproxy)
• A non-empty encryptionKey (standard on every TYPO3 install)

How it works 

The width ladder. Instead of generating a derivative for every width a layout could ever request, Imaginator works from a fixed, configurable list of rung widths. The default ladder ( 320,420,560,740,980,1300,1720,2000,2560,3200,3840) covers everything from small phones to 4K (UHD) displays out of the box. Every rung becomes one srcset candidate; its height follows from the aspect ratio. Rungs larger than the source image (or maxDimension) are capped and deduplicated, so a small source never gets upscaled. Because any requested width is quantized up to the nearest rung, at most one ladder of derivatives ever exists per image and ratio, no matter how many different layout widths the site renders it at.

The <i:image> ViewHelper optionally takes either a single aspect ratio or a per-breakpoint ratio map and turns it into the markup. A single ratio renders an <img> with the full ladder; a map renders a <picture> with one <source> per breakpoint, each its own ladder — true art direction with no hand-written media queries. Editors set that map per content element in the aspect-ratio field, and the chosen crop & focus area is honoured server-side, so the subject stays in frame at every size.

Pluggable processing. The URLs in srcset come from a processor; the render layer is identical whoever produces the pixels. You choose where the work happens:

• Async (the default): a cold derivative is processed on first request via a signed endpoint, then served as a static file; the render itself stays cheap and processing is spread over real traffic.
• Sync: derivatives are materialized at render time and written straight into srcset as static files (no PHP hop per image, higher cold-render cost).
• External (e.g. imgproxy): srcset points straight at the provider, so the webserver never touches pixels. The lightest load on your TYPO3 server.

Bounded and safe. Every requested width is quantized up to a fixed ladder rung. That bounds the set of processed files, and on the signed async endpoint means only rung sizes ever verify, so an attacker cannot request arbitrary dimensions.

Why sizes="auto" is the new cool way 

A responsive <img srcset="…"> only picks the right candidate if it also knows how wide it will be laid out. Traditionally that meant hand-writing a sizes attribute — a list of media-query/width pairs that re-describes your CSS layout in the markup:

<img srcset="img-320.jpg 320w, img-640.jpg 640w, img-1280.jpg 1280w"
     sizes="(min-width: 1200px) 760px, (min-width: 768px) 50vw, 100vw"
     alt="…">

That is brittle. The numbers are a guess, they have to be repeated for every image, and the moment the CSS changes — a new grid, a wider container, a sidebar that collapses — the sizes list is silently wrong and the browser downloads the wrong size (usually too big). It is exactly the kind of per-image configuration Imaginator exists to remove.

sizes="auto" flips this around. The browser already knows the final laid-out width of the image from your CSS — so it just uses it, picking the matching srcset candidate with no hand-written numbers at all:

<img srcset="img-320.jpg 320w, … img-3840.jpg 3840w"
     sizes="auto" loading="lazy" width="3840" height="2160" alt="…">

This is why it pairs perfectly with the width ladder: Imaginator emits the candidates and lets the browser — which is the only party that actually knows the rendered width — choose. No layout duplication, no drift when the design changes, correct on every viewport and container. Because the value is resolved during the browser's preload scan, the right image is fetched in the first round-trip.

Quick start 

A committed DDEV config provides a clickable sandbox. After a fresh clone:

ddev start             # web (nginx-fpm, PHP 8.3), MariaDB, imgproxy
ddev setup             # composer install into .Build/
ddev demo              # clickable demo at https://imaginator.ddev.site/

Backend login on every instance: admin / Password.1.

Tests & coding standards 

Run everything through DDEV before opening a pull request if possible:

ddev test all          # PHPUnit unit + functional
ddev lint              # PHPStan (level 8) + php-cs-fixer (dry-run)
ddev cgl-fix           # auto-fix coding-style violations

Development follows Test Driven Development: write a failing test, verify it fails, add the implementation and verify it passes. Use Conventional Commits for messages (feat:, fix:, docs:, …), branch off main and open the pull request against main.

Installation with Composer 

composer require schliesser/imaginator

Installation from TER 

In a non-Composer (legacy) installation, fetch the extension from the TYPO3 Extension Repository through Admin Tools > Extensions in the backend, then activate it there.

Signing key 

The signing secret is derived automatically from $GLOBALS['TYPO3_CONF_VARS']['SYS']['encryptionKey'], which is set on every standard TYPO3 install. No configuration is needed.

Versioning 

This project uses semantic versioning, which means that

• bugfix updates (e.g. 1.0.0 => 1.0.1) just include small bugfixes or security-relevant stuff without breaking changes,
• minor updates (e.g. 1.0.0 => 1.1.0) include new features and smaller tasks without breaking changes, and
• major updates (e.g. 1.0.0 => 2.0.0) contain breaking changes, which can be refactorings, features or bugfixes.

Settings 

Signing 

The signing secret is derived from the global encryptionKey. When the encryption key changes, flush the frontend caches. Re-rendered HTML then carries URLs signed with the new key.

Editor focus area 

By default imaginator activates a focus area on the default crop variant of every file reference: a movable box an editor draws to mark the part of the image that must never be cropped away. When a rendered aspect ratio differs from the source, the crop is centered on that box (falling back to the crop-area center when none is set). See Crop & Focus Area.

Core offers no focus area out of the box, and declaring a crop variant replaces core's implicit one, so imaginator re-supplies the stock variant (free crop plus the standard 16:9/3:2/4:3/1:1 ratios) and appends the focus area. An existing crop variant default configured by another extension or your site is left untouched.

Activation is a default-on feature toggle, not an Extension Configuration setting (it is read while the TCA is built). Disable it instance-wide in config/system/settings.php:

$GLOBALS['TYPO3_CONF_VARS']['SYS']['features']['imaginator.focusArea'] = false;

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-Control: public, max-age=31536000, immutable.

The signing secret is derived automatically from the global encryptionKey; 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.

ddev add-on get barbieswimcrew/ddev-imgproxy
ddev restart

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.

The placeholder (LQIP) 

The placeholder is not rendered as an inline style="" attribute (those cannot carry a CSP nonce). The <img> only gets a CSS class; the actual rule is registered through TYPO3's AssetCollector and emitted as a nonced <style> element. Identical placeholders are deduplicated to a single rule.

Depending on the chosen lqip option:

thumbhash (default)

The blurred preview is a data: background image, so allow img-src data: (TYPO3's default frontend CSP already does).

dominant-color

A plain background color. Needs nothing beyond the nonced/hashed <style>

none

No placeholder, no extra directive.

The sizes="auto" polyfill 

Whenever a processed image renders, Imaginator registers the sizes="auto" polyfill through the AssetCollector. It is a same-origin script file, nonce-tagged so a strict policy accepts it (TYPO3 v14 via csp, v13 via useNonce).

So a strict CSP needs to allow the nonced script under script-src, TYPO3's default frontend CSP nonces scripts automatically, so nothing extra is required. If you maintain a custom policy, make sure script-src permits same-origin nonced scripts (e.g. script-src 'self' 'nonce-…').

Pages without any <i:image> register no script at all.

Binding the field 

The raw column can be passed straight into the ViewHelper; no DataProcessor is needed:

<i:image image="{ref}" aspectRatio="{ce.data.aspect_ratio}"
         alt="{ce.data.header}"/>

The ViewHelper decodes the JSON map and resolves it to per-breakpoint <source> tiers using the configured breakpoints.

Content Blocks 

When EXT:content_blocks is installed, the same field is available as a field type so block authors can declare it in YAML:

- identifier: aspect_ratio
  type: AspectRatio
  allowedRatios: '16:9,21:9'   # optional; defaults to the full set

allowedRatios is a comma-separated list of the ratios offered in the editor. Omit it to expose the full default set.

Arguments 

width and height are always emitted from the largest rung, so there is zero layout shift.

Fixed-height tiers 

A tier value of "600px" (or "600") pins the height instead of deriving it from a ratio. Width still climbs the ladder, so a full-bleed hero keeps a constant CSS height across viewports while the served crop only gets wider and flatter, but never needlessly taller, from tablet to 4K.

The px value is a CSS height. To stay sharp on high-DPR screens the tier is emitted as several <source>s gated by min-resolution: 1× serves the given height, 2× serves twice it, 3× three times up to fixedHeightDprCap (default 3). A low-DPR screen matches no min-resolution source and gets the cheap 1× height; a retina screen matches a gated source and stays crisp. Height is chosen by the device pixel ratio, width by the layout. So the served pixels match the need with no waste. Heights are never scaled beyond the source image's own height.

Pair a fixed-height image with CSS such as width:100%; height:600px; object-fit:cover; any surplus served height is re-cropped by object-fit.

Priority / LCP images 

Set priority="1" on the above-the-fold (LCP) image. Imaginator then:

• drops loading="lazy" and adds fetchpriority="high" on the <img>;
• renders an explicit sizes="100vw" instead of sizes="auto";
• adds a <link rel="preload" as="image" imagesrcset="…" imagesizes="100vw" fetchpriority="high"> to the <head>, so the request is discoverable in the initial document.

This satisfies Lighthouse's LCP request is discoverable, not lazily loaded and fetchpriority should be applied audits.

New CDN provider: a URL builder is enough 

For an external provider (CDN / image service) you rarely need a full processor — the non-grammar work (source-URL resolution, editor-crop replay, offloaded semantics) is already written once in ExternalImageProcessor. Implement only the provider's URL grammar:

use Schliesser\Imaginator\Attribute\AsImaginatorProcessor;
use Schliesser\Imaginator\Dto\ExternalConfig;
use Schliesser\Imaginator\Dto\ImageVariant;
use Schliesser\Imaginator\Dto\Rectangle;
use Schliesser\Imaginator\UrlBuilder\UrlBuilderInterface;

#[AsImaginatorProcessor('my-cdn')]
final readonly class MyCdnUrlBuilder implements UrlBuilderInterface
{
    public function __construct(private ExternalConfig $config) {}

    public function build(ImageVariant $variant, string $sourceUrl, ?Rectangle $crop = null): string
    {
        return sprintf(
            '%s/%dx%d/%s',
            rtrim($this->config->baseUrl, '/'),
            $variant->width,
            $variant->height,
            $sourceUrl,
        );
    }
}

The compiler pass wraps the builder in a configured ExternalImageProcessor automatically. Convention: the builder takes ExternalConfig as its sole constructor argument — it carries the unified processorBaseUrl / processorSignKey / processorSalt settings; ignore the fields your provider has no equivalent for (imagor ignores salt). Keep the builder pure (no I/O), so it stays golden-file testable.

Provider-specific extras (e.g. a Cloudflare account hash) arrive in ExternalConfig::$options; read them in the builder via $this->config->option('accountHash') or $this->config->requireOption('accountHash') — the latter throws a descriptive exception naming the exact configuration path, so a misconfiguration fails loudly instead of emitting broken URLs.

Where the options live depends on who ships the builder. Extension Configuration is namespaced per extension, so a builder shipped in your own extension declares its extension key on the attribute and keeps the options in its own namespace — its own ext_conf_template.txt, its own backend form:

#[AsImaginatorProcessor('my-cdn', extensionKey: 'my_cdn')]
final readonly class MyCdnUrlBuilder implements UrlBuilderInterface { /* … */ }

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['my_cdn'] = [
    'accountHash' => 'abc123',
];

Without extensionKey the options come from imaginator's own processorOptions map (used by the built-in providers; it has no backend UI):

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['imaginator']['processorOptions'] = [
    'accountHash' => 'abc123',
];

The full interface 

When URL grammar is not enough (local processing, exotic materialization), implement the processor interface itself — same attribute:

interface ImageProcessorInterface
{
    /** Render-time: URL that belongs in srcset for this variant. */
    public function buildUrl(ImageVariant $variant): string;

    /** True when pixels happen elsewhere (external CDN/service); local processing is skipped. */
    public function isOffloaded(): bool;

    /** Local processors only: produce/return the processed binary. */
    public function materialize(ImageVariant $variant): ProcessedImage;
}

• Return true from isOffloaded() for an external service (CDN / provider). buildUrl() then maps the variant onto the provider's URL grammar and materialize() is never called (the webserver never touches pixels).
• Return false for a local processor; materialize() produces the derivative through TYPO3's ImageService.

Register it 

One attribute covers both shapes — the implemented interface decides:

#[AsImaginatorProcessor('my-cdn')]
final class MyProcessor implements ImageProcessorInterface { /* … */ }

• ImageProcessorInterface → the service itself is registered under the key.
• UrlBuilderInterface → a configured ExternalImageProcessor wrapping the builder is registered under the key.
• Neither or both → the container compile fails with a descriptive exception; duplicate and empty keys fail too (nothing silently last-wins).

Manual tagging remains a supported alternative — e.g. for multi-key aliasing or when your service needs its own factory. Tag it with imaginator.image_processor and a key; the registry is a lazy service locator indexed by that key:

Vendor\MyExt\Imaging\MyCdnProcessor:
  tags:
    - { name: 'imaginator.image_processor', key: 'my-cdn' }

Escalation ladder: attribute on a URL builder (zero configuration code) → builder + options (extensionKey for your own namespace, or imaginator's processorOptions) → manual yaml named service with your own factory → full ImageProcessorInterface class (same attribute).

Select it with the processor setting:

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['imaginator']['processor'] = 'my-cdn';

No database migration 

The aspect-ratio field is the unprefixed aspect_ratio column, the same column pictureino used, so existing editor data is preserved as-is. There is no schema change and no data migration to run.

Template changes 

Replace the pictureino ViewHelper call with <i:image>. The per-breakpoint {alias: ratio} map keys resolve to the configured breakpoints, matching pictureino's behaviour:

<html xmlns:i="http://typo3.org/ns/Schliesser/Imaginator/ViewHelpers"
      data-namespace-typo3-fluid="true">

    <i:image image="{data.image}"
             aspectRatio="{data.aspect_ratio}"
             alt="{data.header}"/>
</html>

After swapping templates, review the configuration. The ladder, format and processor defaults differ from pictureino's.