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, but any markup that writes a URL of this form will be intercepted by the ProcessingMiddleware:

/processed/<original-path>.<mode-config>.<ext>[?<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. 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

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 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.

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:

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.