[TASK] Ship sensible defaults for AVIF and JPEG XL, document per-backend params

Author: wazum

Classes/Command/DiagnoseCommand.php

@@ -663,25 +663,97 @@ private function checkCustomConverter(string $converterClass): array
 
     private function checkParameterParsing(SymfonyStyle $io, OutputFormat $format): void
     {
+        // Distinguish three states so the message tells the admin exactly what to do:
+        //   (1) parameters string is completely empty       → no per-mime check possible, one warning
+        //   (2) parameters set but no '::' separator        → applies to every mime type, one warning
+        //   (3) parameters set with mime entries but the    → per-mime warning for each missing entry
+        //       current mime isn't covered
+        $suggestion = $this->recommendedParametersFor($format);
+
+        if ('' === $this->configuration->getRawParameters($format)) {
+            $this->writeStatus($io, '!', \sprintf('parameters_%s is empty — recommended: %s', $format->value, $suggestion));
+            ++$this->warningCount;
+            $this->captureFirstFailure(\sprintf(
+                "parameters_%s is empty. Set it in the Extension Configuration to:\n  %s",
+                $format->value,
+                $suggestion,
+            ));
+
+            return;
+        }
+
+        $hasMimePrefix = \str_contains($this->configuration->getRawParameters($format), '::');
+        if (!$hasMimePrefix) {
+            $this->writeStatus($io, '!', \sprintf('parameters_%s has no `mime/type::` prefix — the same options apply to every supported mime type. Recommended: %s', $format->value, $suggestion));
+            ++$this->warningCount;
+            $this->captureFirstFailure(\sprintf(
+                "parameters_%s uses the legacy single-options format (no `mime/type::` prefix). It passes the same options to every supported mime. Replace with:\n  %s",
+                $format->value,
+                $suggestion,
+            ));
+
+            return;
+        }
+
         foreach (\Plan2net\Webp\Format\SourceMimeType::all() as $mimeType) {
             if (!$this->configuration->isSupportedMimeTypeFor($format, $mimeType)) {
                 continue;
             }
-            $resolved = $this->configuration->getParametersFor($format, $mimeType);
-            if (null === $resolved) {
-                $this->writeStatus($io, '!', \sprintf('parameters for %s @ %s could not be resolved — falls back to old single-options format', $format->value, $mimeType));
+            if (null === $this->configuration->getParametersFor($format, $mimeType)) {
+                $mimeSuggestion = $this->recommendedMimeEntry($format, $mimeType);
+                $this->writeStatus($io, '!', \sprintf('parameters_%s has no entry for %s — append `|%s`', $format->value, $mimeType, $mimeSuggestion));
                 ++$this->warningCount;
                 $this->captureFirstFailure(\sprintf(
-                    "Converter parameters cannot be resolved for format %s and mime type %s.\nThe parameters_%s string should look like 'image/jpeg::Q=85|image/png::Q=75'. Check the parameters_%s setting in the extension config.",
+                    'parameters_%s is missing a `%s::…` entry. Append `|%s` to the existing value so files of that mime type are converted.',
                     $format->value,
                     $mimeType,
-                    $format->value,
-                    $format->value,
+                    $mimeSuggestion,
                 ));
             }
         }
     }
 
+    /**
+     * Looks at the currently-configured converter and returns the recommended
+     * parameter string for the given output format. Defaults to the
+     * ImageMagick recipe (which is what ext_conf_template ships) so the
+     * suggestion is always concrete instead of "see README".
+     */
+    private function recommendedParametersFor(OutputFormat $format): string
+    {
+        $converterClass = $this->configuration->getConverterFor($format);
+
+        if (VipsConverter::class === $converterClass) {
+            return match ($format) {
+                OutputFormat::Webp => 'image/jpeg::Q=85 smart_subsample=true effort=4|image/png::Q=75 lossless=true effort=4|image/gif::Q=75 lossless=true mixed=true effort=4',
+                OutputFormat::Avif => 'image/jpeg::Q=60 effort=4|image/png::Q=60 effort=4|image/gif::Q=60 effort=4',
+                OutputFormat::Jxl => 'image/jpeg::Q=75 effort=7|image/png::lossless=true effort=7|image/gif::lossless=true effort=7',
+            };
+        }
+
+        // MagickConverter, ExternalConverter and any custom converter that
+        // accepts ImageMagick-style flags fall through to this branch — also
+        // matches the empty `converter_<format>` default during boot.
+        return match ($format) {
+            OutputFormat::Webp => 'image/jpeg::-quality 85 -define webp:lossless=false|image/png::-quality 75 -define webp:lossless=true|image/gif::-quality 85 -define webp:lossless=true',
+            OutputFormat::Avif => 'image/jpeg::-quality 60|image/png::-quality 75|image/gif::-quality 60',
+            OutputFormat::Jxl => 'image/jpeg::-quality 75|image/png::-quality 90|image/gif::-quality 75',
+        };
+    }
+
+    private function recommendedMimeEntry(OutputFormat $format, string $mimeType): string
+    {
+        foreach (\explode('|', $this->recommendedParametersFor($format)) as $segment) {
+            if (\str_starts_with($segment, $mimeType . '::')) {
+                return $segment;
+            }
+        }
+
+        // The recommendation table above always covers jpeg/png/gif, so this
+        // is only reached for hypothetical future mime types.
+        return $mimeType . '::-quality 75';
+    }
+
     /**
      * @param list<OutputFormat> $selectedFormats
      */

README.md

@@ -162,10 +162,12 @@ Existing installs keep generating WebP only because `formats_enabled` defaults t
 | [`hide_webp`](#hide_webp)                     | `1`                                         | Hide generated sibling files (`.webp` / `.avif` / `.jxl`) in the BE file list |
 | [`mime_types`](#mime_types)                   | `image/jpeg,image/png,image/gif`            | Source mime types convertible to `webp`                |
 | [`parameters`](#parameters)                   | See below                                   | Per-mime-type WebP converter parameters (the `webp` slot) |
+| [`parameters_avif`](#parameters_avif)         | See below                                   | Per-mime-type AVIF converter parameters                 |
+| [`parameters_jxl`](#parameters_jxl)           | See below                                   | Per-mime-type JPEG XL converter parameters              |
 | [`silent`](#silent)                           | `1`                                         | Suppress converter stdout/stderr (Linux only)          |
 | [`use_system_settings`](#use_system_settings) | `1`                                         | Reuse GFX color profile settings (MagickConverter)     |
 
-Each non-webp format adds its own `converter_<format>`, `parameters_<format>`, and `mime_types_<format>` settings in dedicated `cat=avif` / `cat=jxl` tabs of the Extension Configuration form. See [`formats_enabled`](#formats_enabled) below.
+Each non-webp format adds its own `converter_<format>`, `parameters_<format>`, and `mime_types_<format>` settings in dedicated `cat=avif` / `cat=jxl` tabs of the Extension Configuration form. See [`formats_enabled`](#formats_enabled) and the per-format `parameters_avif` / `parameters_jxl` sections below.
 
 ### `async`
 
@@ -231,17 +233,12 @@ Comma-separated list of output formats this install should produce. Each enabled
 
 Each non-webp format reads its converter and parameters from per-format keys (in their own `cat=avif` / `cat=jxl` tabs in the Extension Configuration form):
 
-- `converter_avif`, `parameters_avif`, `mime_types_avif`
-- `converter_jxl`, `parameters_jxl`, `mime_types_jxl`
+- `converter_avif`, [`parameters_avif`](#parameters_avif), `mime_types_avif`
+- `converter_jxl`, [`parameters_jxl`](#parameters_jxl), `mime_types_jxl`
 
 The legacy `converter` + `parameters` + `mime_types` keys remain the source of truth for the WebP slot.
 
-**Recommended parameter strings** for libvips:
-
-```
-parameters_avif = image/jpeg::Q=60 effort=4|image/png::Q=60 effort=4|image/gif::Q=60 effort=4
-parameters_jxl  = image/jpeg::Q=75 effort=7|image/png::lossless=true effort=7|image/gif::lossless=true effort=7
-```
+Both `parameters_avif` and `parameters_jxl` ship with ImageMagick-compatible defaults so enabling a format works out of the box on the typical TYPO3 host. Tune to your stack — recipes for libvips and external binaries are under [`parameters_avif`](#parameters_avif) and [`parameters_jxl`](#parameters_jxl) below.
 
 ### `hide_webp`
 
@@ -333,6 +330,51 @@ Options are passed straight to libvips's `webpsave` — see the [option referenc
 > [!IMPORTANT]
 > Set `ffi.enable=true` in php.ini (not `preload` — jcupitt/vips does not support FFI preloading). On PHP 8.3+ also set `zend.max_allowed_stack_size=-1`; without it the default stack limit can cause spurious conversion failures.
 
+### `parameters_avif`
+
+Same `mime/type::params|…` syntax as [`parameters`](#parameters). Default targets ImageMagick (matches the default `converter_avif`):
+
+```
+parameters_avif = image/jpeg::-quality 60|image/png::-quality 75|image/gif::-quality 60
+```
+
+| Backend             | Recommended `parameters_avif`                                                          |
+|---------------------|----------------------------------------------------------------------------------------|
+| `MagickConverter`   | `image/jpeg::-quality 60\|image/png::-quality 75\|image/gif::-quality 60`              |
+| `VipsConverter`     | `image/jpeg::Q=60 effort=4\|image/png::Q=60 effort=4\|image/gif::Q=60 effort=4`        |
+| `ExternalConverter` | `image/jpeg::/usr/bin/avifenc --min 30 --max 50 %s %s\|image/png::…\|image/gif::…`     |
+
+AVIF at quality ~60 typically matches WebP at quality ~85 in filesize, often at better SSIM. For ImageMagick, `-quality` covers the common case; advanced encoders also accept `-define heic:speed=2` (slower, better compression) on builds with the libheif AV1 delegate.
+
+References:
+
+- [libheif AV1 encoder options](https://github.com/strukturag/libheif/blob/master/aom-options.md) (used by ImageMagick when compiled with libheif)
+- [libvips `heifsave` reference](https://www.libvips.org/API/current/VipsForeignSave.html#vips-heifsave) (the libvips AVIF entry point)
+- [`avifenc`](https://github.com/AOMediaCodec/libavif#installation) command-line flags
+
+`webp:diagnose` reports per-mime-type parameter resolution; if you enable AVIF and leave entries missing, it tells you which lines to add.
+
+### `parameters_jxl`
+
+Same syntax. Default targets ImageMagick:
+
+```
+parameters_jxl = image/jpeg::-quality 75|image/png::-quality 90|image/gif::-quality 75
+```
+
+| Backend             | Recommended `parameters_jxl`                                                                       |
+|---------------------|----------------------------------------------------------------------------------------------------|
+| `MagickConverter`   | `image/jpeg::-quality 75\|image/png::-quality 90\|image/gif::-quality 75`                          |
+| `VipsConverter`     | `image/jpeg::Q=75 effort=7\|image/png::lossless=true effort=7\|image/gif::lossless=true effort=7`  |
+| `ExternalConverter` | `image/jpeg::/usr/bin/cjxl --quality 75 %s %s\|image/png::/usr/bin/cjxl --lossless_jpeg=0 %s %s\|…`|
+
+JXL preserves PNG well in modular (lossless) mode — for `image/png`, prefer a higher quality value (or `lossless=true` on libvips) than for JPEG.
+
+References:
+
+- [libjxl encoder options](https://github.com/libjxl/libjxl/blob/main/doc/man/cjxl.txt)
+- [libvips `jxlsave` reference](https://www.libvips.org/API/current/VipsForeignSave.html#vips-jxlsave)
+
 ### `silent`
 
 ```

ext_conf_template.txt

@@ -23,14 +23,14 @@ async = 0
 # cat=async; type=int+; label=Random sleep (ms) between conversions in the worker (0 = no sleep); each pause is randomized between half and 1.5x of this value
 async_throttle_ms = 0
 # cat=avif; type=options[Local ImageMagick/GraphicsMagick converter=Plan2net\Webp\Converter\MagickConverter,External converter=Plan2net\Webp\Converter\ExternalConverter,libvips (native)=Plan2net\Webp\Converter\VipsConverter]; label=AVIF conversion adapter (see documentation)
-converter_avif =
+converter_avif = Plan2net\Webp\Converter\MagickConverter
 # cat=avif; type=string; label=AVIF conversion parameters (per mime type, separated by |)
-parameters_avif =
+parameters_avif = image/jpeg::-quality 60|image/png::-quality 75|image/gif::-quality 60
 # cat=avif; type=string; label=AVIF supported mime types (comma separated)
 mime_types_avif = image/jpeg,image/png,image/gif
 # cat=jxl; type=options[Local ImageMagick/GraphicsMagick converter=Plan2net\Webp\Converter\MagickConverter,External converter=Plan2net\Webp\Converter\ExternalConverter,libvips (native)=Plan2net\Webp\Converter\VipsConverter]; label=JPEG XL conversion adapter (see documentation)
-converter_jxl =
+converter_jxl = Plan2net\Webp\Converter\MagickConverter
 # cat=jxl; type=string; label=JPEG XL conversion parameters (per mime type, separated by |)
-parameters_jxl =
+parameters_jxl = image/jpeg::-quality 75|image/png::-quality 90|image/gif::-quality 75
 # cat=jxl; type=string; label=JPEG XL supported mime types (comma separated)
 mime_types_jxl = image/jpeg,image/png,image/gif