Configuration 

SourceSetViewHelper 

The SourceSetViewHelper generates responsive <img> tags with srcset attributes.

{namespace nr=Netresearch\NrImageOptimize\ViewHelpers}

<nr:sourceSet path="{f:uri.image(image: image)}"
              width="1200"
              height="800"
              alt="{image.properties.alternative}"
              sizes="(max-width: 768px) 100vw, 50vw"
              responsiveSrcset="1"
/>

Source set configuration 

Define source sets per media breakpoint via the set attribute:

<nr:sourceSet
    path="{f:uri.image(
        image: image,
        width: '960',
        height: '690',
        cropVariant: 'default'
    )}"
    set="{
        480:{width: 160, height: 90},
        800:{width: 400, height: 300}
    }"
/>

Render modes 

cover

Default. Resizes images to fully cover the provided width and height.

fit

Resizes images so they fit within the provided width and height.

<nr:sourceSet
    path="{f:uri.image(
        image: image,
        width: '960',
        height: '690',
        cropVariant: 'default'
    )}"
    width="960"
    height="690"
    mode="fit"
/>

Lazy loading 

Both modes support lazy loading via the native loading="lazy" attribute. When using JS-based lazy loading (class="lazyload"), the data-srcset attribute is added automatically.

Backward compatibility 

By default responsiveSrcset is false, preserving the existing 2x density-based srcset behavior. All existing templates continue to work without modifications.

Variant URL format 

Processed variants are served from a dedicated URL path. The ViewHelper generates these URLs automatically. Any URL of this form is intercepted by the ProcessingMiddleware, but a variant that is not on disk yet is only created for a signed URL (see Signed variant URLs):

/processed/<original-path>.<mode-config>.<ext>?sig=<signature>[&<query>]

<original-path>

Public path of the source image, including the /fileadmin/ (or other storage) prefix. Path traversal sequences (..) are rejected at URL-parsing time.

<mode-config>

Concatenation of one or more of:

w<n>

Target width in pixels.

h<n>

Target height in pixels.

q<n>

Quality (1--100).

m<n>

Processing mode (0 = cover, 1 = scale/fit).

<ext>

Source image extension: jpg, jpeg, png, gif, webp, avif, bmp, tif or tiff (any case). Other extensions are answered with HTTP 400. The processor decides at response time whether to serve the original, the .webp sidecar, or the .avif sidecar, based on which of these files exist on disk (see Variant negotiation).

/processed/fileadmin/photos/hero.w1200h800m0q85.jpg?sig=3f2c...

Signed variant URLs 

Creating a variant costs CPU time, memory and disk space, so the processor creates one only when the URL carries a signature issued by the installation itself:

• sig is an HMAC (SHA-1, via TYPO3's HashService) of the URL-decoded variant path -- source path, mode config and extension -- keyed with $GLOBALS['TYPO3_CONF_VARS']['SYS']['encryptionKey'] plus a secret specific to this extension.
• The sourceSet ViewHelper signs every URL it renders.
• A URL without a valid signature is answered with HTTP 403 unless the variant is already on disk; existing variants are served without a signature.
• A URL with the skipWebP / skipAvif flags is signed over the path and those flags. A flag added to or removed from a signed URL invalidates the signature (HTTP 403 unless the variant is on disk). Otherwise anyone could request a variant first with a flag and so strip its sidecar for every visitor. A URL without flags is signed over the path alone, as before.

Consequences for existing installations:

• Pages rendered before the update carry unsigned URLs. Flush the page cache after updating, so variants that do not exist yet can be created.
• Since 2.7.0 the skip flags are signed. A URL with skipWebP or skipAvif signed by an earlier version -- built with getResourcePath() or signed by hand -- is answered with HTTP 403 until it is signed again. Flush the page cache after updating if such URLs exist, and pass the flags to sign() where you sign URLs yourself.
• URLs written by hand in templates or content need a signature. Build them in PHP with SourceSetViewHelper::getResourcePath() or sign the path with the Netresearch\NrImageOptimize\Service\VariantUrlSigner service (sign(string $variantPath, bool $skipWebP, bool $skipAvif), with the URL-decoded path and the flags the URL carries).
• Changing the encryptionKey invalidates all signatures; flush the page cache afterwards.
• Without an encryptionKey no signature is issued or accepted.

Variant negotiation 

When the processor generates a variant, it writes the original file to disk and additionally produces a .webp and an .avif sidecar (same base name), unless the format is turned off (see WebP/AVIF generation).

The processor does not inspect the Accept request header. On each request it serves the first non-empty file it finds on disk, in this order: the .avif sidecar, the .webp sidecar, the original format.

Two query parameters let callers opt out of sidecar generation for individual URLs:

skipWebP=1

Do not produce a WebP variant for this URL.

skipAvif=1

Do not produce an AVIF variant for this URL.

The sourceSet ViewHelper adds these flags to every URL it renders when its skipWebP or skipAvif argument is set.

The flags only control generation. The query string is not part of the variant file name, so a URL with a skip flag shares its files with the same URL without it: a sidecar already written for that variant is served either way, and a variant first created with a skip flag gets no such sidecar later until the processed images are cleared (see Clear processed images).

These flags are useful when specific consumers (for example e-mail clients or legacy RSS renderers) cannot handle modern formats.

WebP/AVIF output quality 

The primary variant's quality is controlled per-request via the q<n> URL segment (see Variant URL format). The .webp and .avif sidecars previously reused that same numeric quality, but AVIF's quality scale is steeper than WebP's or JPEG's -- at matching numbers an AVIF file comes out larger than the WebP sidecar, defeating the point of serving AVIF at all.

Two extension configuration settings control sidecar quality independently of the primary variant:

qualityWebp (default 75)

Output quality for the generated WebP variant. At 100 the WebP variant is encoded lossless and typically comes out several times larger than the primary JPEG variant.

qualityAvif (default 60)

Output quality for the generated AVIF variant. The lower default keeps AVIF variants genuinely smaller than WebP while staying visually comparable.

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_image_optimize']['qualityWebp'] = 75;
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_image_optimize']['qualityAvif'] = 60;

The settings can also be edited via the backend: Admin Tools > Settings > Extension Configuration > nr_image_optimize.

WebP/AVIF generation 

By default the processor writes a .webp and an .avif file next to every processed variant. Two switches turn either format off for the whole installation, for example to save storage when one sidecar format is enough:

generateWebp (default 1)

Write a .webp sidecar for each processed variant.

generateAvif (default 1)

Write an .avif sidecar for each processed variant.

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_image_optimize']['generateWebp'] = false;
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_image_optimize']['generateAvif'] = true;

The per-URL skipWebP and skipAvif query parameters (see Variant negotiation) still apply on top: a format is generated only if its switch is on and the URL does not skip it.

Cache headers 

Processed variant URLs are effectively content-addressed -- any change to dimensions, quality, or format produces a different URL. The processor therefore responds with an immutable, long-lived cache header:

Cache-Control: public, max-age=31536000, immutable

This value is a compile-time constant and not user-configurable.

Image driver selection 

Intervention Image is instantiated through \Netresearch\NrImageOptimize\Service\ImageManagerFactory, which selects the best available driver at runtime:

1. Imagick when the imagick PHP extension is loaded (preferred -- supports AVIF natively if the underlying ImageMagick build does).
2. GD when imagick is unavailable and the gd extension is loaded.

If neither extension is present, the factory throws a RuntimeException with a descriptive message. Use the backend maintenance module to verify driver availability on your host.

Middleware registration 

Configuration/RequestMiddlewares.php registers the ProcessingMiddleware on the frontend pipeline before typo3/cms-frontend/site. This ordering is required so the middleware can intercept /processed/ URLs before TYPO3's frontend routing claims them. The registration has no user-configurable options.

Processor limits 

The processor enforces the following bounds when parsing a URL:

Signature

A variant that is not on disk yet is created only for a signed URL (see Signed variant URLs).

Image types

Only the extensions listed in Variant URL format are accepted, and only source files whose content is a JPEG, PNG, GIF, WebP, AVIF, BMP or TIFF image are decoded. Anything else is answered with HTTP 400.

MAX_DIMENSION

Width and height are clamped to 1--8192 pixels to prevent denial-of-service via excessive memory allocation.

MIN_QUALITY / MAX_QUALITY

Quality is clamped to 1--100.

LOCK_MAX_RETRIES

Up to 10 attempts (at 100 ms intervals) to acquire the per-variant processing lock before returning HTTP 503. Prevents duplicate work when multiple clients hit the same uncached variant simultaneously.

Trusted storage symlinks 

The processor validates that both the source image and the target variant resolve (via realpath()) to a location inside an allowed root -- the public webroot, or a Local FAL storage's own base path -- before reading or writing anything. This rejects requests for images reached through a symlink that escapes those roots (for example a symlink accidentally or maliciously pointing at /etc).

Some deployments relocate TYPO3 core's own _processed_ image cache -- a subdirectory inside a FAL storage's own directory, e.g. fileadmin/_processed_ -- onto local/ephemeral storage, to keep frequently-rewritten derivative images off shared/NFS storage. That leaves only a symlink behind inside the storage, which the FAL-storage basePath lookup above does not see (it only resolves the storage's own base path, never looks inside it), so variant requests for such images are rejected even though the original file is legitimately part of the deployed application.

The additionalTrustedStorageSymlinks extension configuration setting closes this gap on an explicit, per-instance, opt-in basis: a comma-separated list of directory names that, when found as a symlink directly inside a Local FAL storage's base path, are resolved and added to the allow-list too.

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_image_optimize']['additionalTrustedStorageSymlinks'] = '_processed_';

The setting can also be edited via the backend: Admin Tools > Settings > Extension Configuration > nr_image_optimize.

Additional trusted roots 

Some deployments need to serve variants of images that live under an absolute filesystem path that is neither the public webroot, a Local FAL storage's own base path, nor one of the hardcoded TYPO3-internal locations (var/, symlinked processed/uploads, or extension-published _assets/<hash> directories) -- for example a custom mount managed outside of FAL.

The additionalTrustedRoots extension configuration setting closes this gap on an explicit, per-instance, opt-in basis: a comma-separated list of absolute filesystem paths that are realpath-resolved and added to the allow-list directly.

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_image_optimize']['additionalTrustedRoots'] = '/mnt/custom-assets';

The setting can also be edited via the backend: Admin Tools > Settings > Extension Configuration > nr_image_optimize.