WebP-Konvertierung in TYPO3 13 zentral aktivieren

Eric Harrer

In der TYPO3 Masterclass vom 14. April 2025 habe ich die Frage gestellt, wie sich die Konvertierung von Bildern nach WebP in TYPO3 zentral und template-unabhängig steuern lässt. Direkt im Anschluss habe ich ein wenig dazu recherchiert und dabei den Event Listener BeforeFileProcessingEventListener gefunden, der sich gut eignet, um die Bildkonfiguration vor dem Processing zu manipulieren. Daraufhin habe ich eine erste Lösung ausgearbeitet, die auf diesem Listener basiert.

Der gewünschte Dateityp wird dabei automatisch festgelegt – vollständig gekapselt, kompatibel mit TYPO3 13 und ohne Änderungen an bestehenden Templates.

Hinweis: Dieser Event Listener setzt lediglich den Fallback-Dateityp für unterstützte Rastergrafikformate auf WebP, sofern keine andere Datei-Endung explizit angegeben wurde. Das Verhalten entspricht dabei dem, als würde man das Attribut fileExtension="webp" überall in den Fluid-Templates setzen.

Man muss für das jeweilige Projekt selbst abwägen, ob die ausschließliche Nutzung von WebP ausreichend ist – insbesondere, da einige ältere Browser das Format unter Umständen noch nicht unterstützen. Eine Übersicht zur Browserunterstützung findet sich unter caniuse.com.

✅ Vorteile der Lösung

Kein Eingriff in Fluid-Templates erforderlich
WebP wird nur gesetzt, wenn keine andere Endung vorgegeben wurde
Kompatibel mit File und FileReference
Optionales Logging möglich – siehe TYPO3-Doku zur FileWriter-Konfiguration

📋 Voraussetzungen

TYPO3 v13 oder neuer
webp muss in $GLOBALS['TYPO3_CONF_VARS']['GFX']['imagefile_ext'] enthalten sein
Die zugrunde liegende Grafikbibliothek (z. B. ImageMagick) muss WebP unterstützen

Event Listener zur WebP-Erzwingung

Pfad: EXT:sitepackage/Classes/Event/Listener/BeforeFileProcessingEventListener.php

<?php

declare(strict_types=1);

namespace VendorName\Sitepackage\Event\Listener;

use TYPO3\CMS\Core\Attribute\AsEventListener;
use TYPO3\CMS\Core\Resource\Event\BeforeFileProcessingEvent;
use TYPO3\CMS\Core\Resource\File;
use TYPO3\CMS\Core\Resource\FileInterface;
use TYPO3\CMS\Core\Resource\FileReference;
use TYPO3\CMS\Core\Resource\ProcessedFile;

/**
 * Forces WebP output for supported image types during file processing,
 * unless a specific output format is already configured.
 *
 * Note: For the best performance, the fileExtension should be set explicitly
 * wherever image processing is triggered. This listener ensures fallback
 * behavior and may cause additional processing on first use or cache rebuild.
 */
#[AsEventListener(
    identifier: 'sitepackage/before-file-processing',
)]
final readonly class BeforeFileProcessingEventListener
{
    /**
     * MIME types suitable for WebP conversion.
     *
     * Keys are used for fast lookup via isset().
     *
     * @var array<string, bool>
     */
    private const array SUPPORTED_MIME_TYPES = [
        'image/jpeg' => true,
        'image/png' => true,
        'image/gif' => true,
        'image/bmp' => true,
        'image/tiff' => true,
    ];

    /**
     * Applies WebP conversion if no fileExtension is configured.
     */
    public function __invoke(BeforeFileProcessingEvent $event): void
    {
        $configuration = $event->getConfiguration();

        if (!empty($configuration['fileExtension'])) {
            return;
        }

        $fileInterface = $event->getFile();
        if (!$this->isWebpConvertible($fileInterface)) {
            return;
        }

        $file = $this->resolveFile($fileInterface);
        $configuration['fileExtension'] = 'webp';

        $newProcessedFile = new ProcessedFile(
            $file,
            $event->getTaskType(),
            $configuration
        );
        $event->setProcessedFile($newProcessedFile);
    }

    /**
     * Checks if the file MIME type allows WebP conversion.
     */
    private function isWebpConvertible(FileInterface $file): bool
    {
        return isset(self::SUPPORTED_MIME_TYPES[$file->getMimeType()]);
    }

    /**
     * Returns the original file from a reference or the file itself.
     * Ensures the return type is always a File.
     */
    private function resolveFile(FileInterface $file): File
    {
        if ($file instanceof FileReference) {
            return $file->getOriginalFile();
        }

        assert($file instanceof File);
        return $file;
    }
}

Wolfgang Wagner

Danke für's teilen dieser Lösung! Cool, dass du da tatsächlich was gefunden hast. 🙂

plued2

Hi. Erstmal vielen Dank für die Lösung.
Bei folgendem Szenario funktioniert allerdings das Rendering via f:image ViewHelper nicht. Und zwar, wenn man als "src" bereits das ProcessedFile übergibt.

Also in diesem Fall (wenn man kein FileObject und nur die ID hat; f:uri.image gibt direkt die processed webp Src zurück):
<f:image src="{f:uri.image(src: icon)}" />

Das funktioniert dann aber:
<img src="{f:uri.image(src: icon)}" />

Eric Harrer

plued2 danke dir für die Rückmeldung. Das Problem liegt hier nicht im Event Listener sondern in deinem Anwendungsfall. Die doppelte Verarbeitung eines Bildes ergibt keinen Sinn und wirft i.d.R. auch ohne meinen Event Listener einen Fehler.

Ich kann grundsätzlich zwar bestätigen, dass die Zeile

<f:image src="{f:uri.image(src: icon)}" />

ohne den Event Listener funktioniert und mit dem Event Listener nicht mehr.

Grund dafür ist allerdings, dass du keinerlei zusätzliche Angaben in f:uri.image gemacht hast, die eine Verarbeitung des Bildes erforderlich machen. Aus diesem Grund wird der originale Bildpfad direkt weitergereicht und der umgebende f:image ViewHelper kann damit weiter arbeiten. Das ändert allerdings nichts an der Tatsache, dass das Problem bereits in der unnötigen Verschachtelung der beiden ViewHelper besteht.

Sobald wir nämlich das Test-Szenario ohne den Event Listener ein bisschen anpassen, laufen wir in den gleichen Fehler, den wir erhalten, wenn wir mit dem Event Listener arbeiten:

<f:image src="{f:uri.image(src: icon, width: '321')}" />

Die Angabe einer Zielbreite - sofern sie nicht der Breite des ursprünglichen Bildes entspricht - bewirkt nun, dass das Bild bereits per f:uri.image neu berechnet wird. Das daraus resultierende ProcessedFile-Objekt wirft dann auch ganz ohne meinen Event Listener einen Fehler in f:image. Der einzige Unterschied, den wir mit dem Event Listener haben, besteht also darin, dass dieser auch ohne zusätzliche Angaben die Bildverarbeitung anstößt. Schließlich hat er die WebP-Konvertierung zum Ziel.

Und was ist jetzt die Lösung?

Schreibe einfach folgendes:

<f:image src="{icon}" />

Die Vorab-Verarbeitung durch f:uri.image ist nicht notwendig, da f:image intern genau den gleichen Verarbeitungsprozess anstößt. Auf diese Weise reduzierst du das Fehler-Risiko - unabhängig davon, ob du meinen Event Listener benutzt.

Die Schreibweise:

<img src="{f:uri.image(src: icon)}" />

funktioniert zwar auch aber ich würde davon abraten. Bei dieser Schreibweise verlierst du alle sinnvollen Attribute im img-Tag, die TYPO3 sonst noch für die Bild-Ausgabe standardmäßig vorsieht.

Teddytrombone

Danke für die Lösung. Wir haben damit allerdings das Problem, dass im Backend in der Filelist die Vorschaubilder teilweise nicht angezeigt werden. Vermutlich wenn die Vorschaubilder noch nicht generiert wurden. Der Request an typo3/image/process?token=xxxx liefert dann einen 404-Fehler. Sobald der EventListener entfernt wird bzw. im __invoke ein return vor dem $event->setProcessedFile gemacht wird, funktioniert es wieder.
Hat das evtl. schon jemand beobachtet und hat eine Lösung?

Teddytrombone

Teddytrombone Sorry, ist hinfällig, natürlich war das ein anderer, projektspezifischer Code, der das Problem verursacht.

Bitwellr

Schöner Ansatz, vielen Dank für die Inspiration.
Dieser Code erzeugt jedoch Mehrfacheinträge in sys_file_processedfile.
Dies liegt daran das in TYPO3\CMS\Core\Resource\Service\FileProcessingService vor dem BeforeFileProcessingEvent geprüft wird, ob es bereits eine ProcessedFile gibt, da die config aber im BeforeFileProcessingEvent erweitert wird, sind diese nie bekannt.
Daher muss seperat nochmals in BeforeFileProcessingEvent eine Prüfung erfolgen.

Vielleicht gibt es noch einen schönen Ansatz dies zu verhindern, da nun 2x geprüft wird?

Eric Harrer

Bitwellr soweit ich mich erinnere, war die doppelte Verarbeitung notwendiges Übel, um mit dem Core Code kompatibel zu bleiben. Ich schau mir das aber noch mal an, ob es irgendeine Möglichkeit gibt.

Bitwellr

Ich habe mich an FileProcessingService orientiert und nutze findOneByOriginalFileAndTaskTypeAndConfiguration, um zu prüfen, ob die Datei mit der config schon einmal verarbeitet wurde, wenn nicht liefert die Methode bereits ein ProcessedFile Object. Dadurch wird verhindert das neue DB Einträge geschrieben werden (Nicht nur doppelt sondern bei jedem Aufruf)

` public function __invoke(BeforeFileProcessingEvent $event): void
{
$configuration = $event->getConfiguration();

    if (!empty($configuration['fileExtension'])) {
        return;
    }

    $fileInterface = $event->getFile();
    if (!$this->isWebpConvertible($fileInterface)) {
        return;
    }

    $originalFile = $this->resolveFile($fileInterface);
    $configuration['fileExtension'] = 'webp';

    // Check if a WebP version already exists in the database
    // This is crucial because the FileProcessingService already called
    // findOneByOriginalFileAndTaskTypeAndConfiguration() with the OLD configuration (without fileExtension)
    // We need to check again with the NEW WebP configuration to avoid duplicates
    $webpProcessedFile = $this->processedFileRepository->findOneByOriginalFileAndTaskTypeAndConfiguration(
        $originalFile,
        $event->getTaskType(),
        $configuration
    );

    // Replace the ProcessedFile in the event
    // If it exists in DB, it will be reused. If not, a new one will be created.
    $event->setProcessedFile($webpProcessedFile);
}`

Unterstütze das Forum

Hilf mit, den Community Hub für TYPO3 werbefrei zu halten und die Betriebskosten zu decken. Werde Official Community Hub Supporter für nur 5 Euro im Monat (zzgl. USt) und erhalte ein exklusives Supporter-Badge. Jeder Beitrag zählt!

Jetzt Supporter werden

Impressum - Datenschutz - Kontakt - Netiquette - RSS