README.md

Enforce WebP Conversion for Raster Images

This event listener enforces WebP output during file processing when no specific file extension is configured. It serves as a fallback mechanism to promote consistent use of modern image formats like WebP across the system.

Purpose

The listener ensures that WebP conversion is applied automatically for supported raster formats whenever:

• No fileExtension is explicitly configured,
• File processing is triggered via TYPO3's File Abstraction Layer (FAL),
• The file’s MIME type qualifies for WebP conversion.

It helps improve consistency and frontend performance, especially in projects where explicit configuration of output formats is not reliably enforced in all contexts.

Behavior

The listener responds to BeforeFileProcessingEvent and modifies the processing configuration by injecting fileExtension = webp. It applies only when no fileExtension is already set and the MIME type is supported. The result is a newly generated ProcessedFile using the WebP format, which TYPO3 will cache and reuse.

Browser Support Consideration

This approach assumes that WebP is supported by the client browser. While modern browsers handle WebP reliably, older or niche browsers may not. This fallback mechanism unconditionally enforces WebP output for qualifying files.

Recommendation: Use this listener only after reviewing your target audience and usage statistics. If significant portions of your users rely on legacy browsers without WebP support, consider implementing alternative strategies such as using <picture> or srcset to provide multiple formats, allowing the browser to select the best supported option.

Performance Considerations

Processed files are stored and reused by TYPO3 based on their configuration hash. This means:

• The listener may cause initial processing load for files where no WebP version exists yet.
• In normal operation, once processed, WebP versions are cached like any other processed file.
• On large installations or after full cache invalidation, the system may experience short-term overhead.

Recommendation: If possible, set fileExtension="webp" explicitly in templates or rendering logic to reduce unnecessary processing. This listener is designed as a fallback, not a primary image format strategy.

Limitations

The listener is only effective when file processing is invoked via the File Abstraction Layer (FAL). It has no effect if:

• Files are referenced using hardcoded public URLs,
• Image output is controlled entirely outside TYPO3’s file processing mechanism,
• The source is not a raster image or does not match a supported MIME type.

TYPO3 Compatibility

This listener requires TYPO3 version 13.0 or higher, as it relies on PHP attribute-based event registration via #[AsEventListener] and built-in support for WebP image processing.

Usage

Place the listener at the following location in your extension:

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

Make sure to adjust the PHP namespace in the file according to your vendor name and package name. TYPO3 will automatically register the listener via the #[AsEventListener] attribute. No additional configuration is required.

Extensibility

This implementation is intentionally minimal. It can be extended to:

• Restrict processing to specific storage IDs, folders, or sites,
• Support alternative formats like AVIF,
• Integrate environment- or site-specific behavior via custom configuration.

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;
    }
}