Add support for alternatiwe image formats like webp and avif by tito10047 · Pull Request #1651 · liip/LiipImagineBundle

tito10047 · 2026-02-19T16:19:20Z

…update handling of modern image formats (WebP, AVIF).

Q	A
Branch?	2.x
Bug fix?	no
New feature?	yes
BC breaks?	no
Deprecations?	yes
Fixed tickets	#1314
License	MIT
Doc	yes

Description

This PR refactors the way modern image formats (like WebP and AVIF) are handled within the bundle. Instead of having hardcoded logic for a single format, it introduces a generic Alternative Formats system.

Key changes:

Unified Configuration: Introduced alternative_formats configuration tree.
BC Compatibility: Existing webp configuration is automatically normalized into the new structure using a beforeNormalization step in Configuration.php.
Format Negotiation: Added a FormatNegotiator service to dynamically select the best image format based on the browser's Accept header (supporting AVIF, WebP, etc.).
Abstrakcia: Refactored FilterPathContainer to support any alternative format, while marking createWebp() as deprecated.
Extensibility: New formats like AVIF can now be enabled simply by adding them to the configuration without changing the bundle's core logic.

This approach follows the discussion in issue #1314, providing a future-proof solution for modern image delivery while ensuring zero breaking changes for existing installations.

Proff of concept here: just6words.com

…update handling of modern image formats (WebP, AVIF).

…tiation with tests.

…ative` and add comprehensive tests for alternative format handling.

…otiator` initialization, and enhance support for format-specific mime types and post-processors.

…pdate related methods, and improve support for flexible format negotiation.

…native_formats`, deprecate `isWebpSupported`, and update service definitions.

coveralls · 2026-02-19T18:00:57Z

coverage: 81.099% (+1.0%) from 80.126%
when pulling 5f62a74 on tito10047:avif
into 69d2df3 on liip:2.x.

tito10047 · 2026-02-19T18:02:17Z

Hi @dbu . can you help me with cs fixer? I run cs fixer as you mentioned me last time, but nothing is fixed in me setup
docker run --rm -v /home/jozefm/phpProjects/contrib/LiipImagineBundle:/code ghcr.io/php-cs-fixer/php-cs-fixer:3.66-php8.0 fix

Thx

…agic driver can convert to avif, imagick convert to avif before postProcessor. so I add this option use_default_driver. only if this option is set to true (defaut) imagick will convert to avif. otherwise will be do it avifenc binary

tito10047 · 2026-03-07T19:23:42Z

Hi @dbu . Will you look at this PR please?

dbu · 2026-03-18T08:45:16Z

thanks for looking into this. the current approach is certainly not ideal. your refactoring makes it more flexible. but we saw that the basic idea of serving a webp under the jpg url is problematic (http caching, need to call the controller each time)

i wonder why we don't use the element for this:

<picture>
  <source srcset="photo.avif" type="image/avif" />
  <source srcset="photo.webp" type="image/webp" />
  <img src="photo.jpg" alt="photo" />
</picture>

then its up to the browser to chose the best option, and urls are clean again, allowing for proper caching and avoiding any hacks and capability sniffing in the backend.

this can be built with the imagine_filter , we could additionally provide a tool for the <source srcset entries (or the whole picture element, but that would be a bit tricky because one might need all kinds of attributes in the <img> tag.

tito10047 · 2026-03-19T09:04:19Z

Ok, But this PR is the same aproach as is already in this bundle. so nothing is changed. only some refactoring.
And we can build uppn this pr helper your suggested, helsper without controller calling

dbu

i took a closer look now. the refactoring is well done and a much better and future proof way to achieve what the webp flag does. i am still unhappy that it deepens a pattern that i think we should move away from. in that way it sends a wrong signal to users who upgrade.

at the same time I don't have much time to work on the bundle, so it might be quite a while until i can address that. therefore lets merge this.

i commented on some details. can you please also add a changelog entry to explain the deprecation and the more generic solution, but also point out that client side resolving is the preferred way for supporting webp, avif etc?

dbu · 2026-03-20T09:53:59Z

Imagine/Cache/CacheManager.php

-        $webpGenerate = false
+        $alternativeFormats = false
    ) {
+        if (\is_bool($alternativeFormats)) {


could we default the parameter to [] instead? otherwise not setting alternative formats triggers a deprecation

dbu · 2026-03-20T09:55:32Z

Imagine/Cache/CacheManager.php

        $this->dispatcher = $dispatcher;
        $this->defaultResolver = $defaultResolver ?: 'default';
-        $this->webpGenerate = $webpGenerate;
+        $this->alternativeFormats = $alternativeFormats;


i would normalize this to have the property only accept array and translate false to [] and true to ['webp]. that way the BC is constrained to the constructor and the rest of the class simpler.

dbu · 2026-03-20T10:00:32Z

Service/FilterService.php

     * @param string      $path
     * @param string      $filter
     * @param string|null $resolver
+     * @param bool        $webpSupported


Suggested change

* @param bool $webpSupported

* @param bool $webpSupported deprecated in favor of $alternativeFormatsSupported

dbu · 2026-03-20T10:00:56Z

Service/FilterService.php

     * @param string      $path
     * @param string      $filter
     * @param string|null $resolver
+     * @param bool        $webpSupported


Suggested change

* @param bool $webpSupported

* @param bool $webpSupported deprecated in favor of $alternativeFormatsSupported

dbu · 2026-03-20T10:04:05Z

.github/workflows/phpunit.yml

      - name: Run PHPUnit tests
        env:
-          SYMFONY_DEPRECATIONS_HELPER: max[self]=0
+          SYMFONY_DEPRECATIONS_HELPER: disabled=1


please don't change this setting.

dbu · 2026-03-20T10:05:38Z

Resources/config/imagine.php

            service('liip_imagine.filter.manager'),
            service('liip_imagine.cache.manager'),
-            '%liip_imagine.webp.generate%',
-            '%liip_imagine.webp.options%',


is there no risk of BC break? does the extension integrate the parameters into alternative_formats if the old parameters are set?

dbu · 2026-03-20T10:16:59Z

Resources/doc/basic-usage.rst


-Use WebP if supported
-~~~~~~~~~~~~~~~~~~~~~
+Use modern formats if supported (recommended)


i'd love to point to the client side resolving right at the start of this section, and mention that client side resolving is the preferred way of doing this.

dbu · 2026-03-20T10:17:56Z

Resources/doc/basic-usage.rst

-formats.
+For better performance, you can use the ``<picture>`` tag to resolve supported
+image formats on the client-side in the browser. This will complicate the HTML code
+and require registering multiple filters that generate images in different formats.


Suggested change

and require registering multiple filters that generate images in different formats.

and require registering multiple filters that generate images in different formats.

If you have a suggestion how a convenient setup for this would look, please open

an issue on github to discuss the topic.

tito10047 · 2026-03-23T15:26:16Z

Hi, i can preprare new PR, with idea you want. So lets freeze this PR and I will do on new one. Ok? You want say me something what os your idea closer?

But... When i will do new PR and abamdonenthis idea, there will must be BC. So what is better, accpet this with non BC or release new version with BC. I like second option.

dbu · 2026-03-23T15:51:57Z

if you can address my comments here, we can merge this pull request, then at least there is a better support for the server-side negotiation. i think there is not much work left to do, and then we have an improvement we can release.

tito10047 added 14 commits February 19, 2026 17:15

Deprecate webp configuration in favor of alternative_formats and …

e75dca3

…update handling of modern image formats (WebP, AVIF).

Add FormatNegotiator service for handling Accept header format nego…

d1451d6

…tiation with tests.

Deprecate createWebp method in favor of more flexible `createAltern…

6f012fa

…ative` and add comprehensive tests for alternative format handling.

Replace WebP configuration with alternative_formats, add `FormatNeg…

ba61f54

…otiator` initialization, and enhance support for format-specific mime types and post-processors.

Deprecate WebP-specific handling in favor of alternative_formats, u…

d493ff6

…pdate related methods, and improve support for flexible format negotiation.

Refactor ImagineController to support FormatNegotiator and `alter…

7f8ffb4

…native_formats`, deprecate `isWebpSupported`, and update service definitions.

fix dependencie DependecieInjection tests

d32251c

fixed some tests

0c62ca5

fixed some tests

d49844a

All test are passed :)

bd0a357

cs fixer

dae2888

revert phpunit.xml.dist

56072b4

try fix tests

75cc4a9

try fix tests

4fad8f7

tito10047 added 3 commits February 19, 2026 19:37

fix bc break

f7fd821

fix bc break

5e3e46e

add AVIF support for post-processing and caching

5909f3a

tito10047 changed the title ~~Deprecate webp configuration in favor of alternative_formats and …~~ Add support for alternatiwe image formats like webp and avif Feb 19, 2026

tito10047 added 4 commits February 19, 2026 22:02

add backguard compatibility

07e5821

remove option -o that is not supported on ubuntu

45c1b4a

replace options for supported on ubuntu

0e2f735

tito10047 marked this pull request as ready for review February 19, 2026 22:33

correct way to handle use_default_driver

5f62a74

dbu reviewed Mar 20, 2026

View reviewed changes

	* @param bool $webpSupported
	* @param bool $webpSupported deprecated in favor of $alternativeFormatsSupported

Conversation

tito10047 commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

coveralls commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tito10047 commented Feb 19, 2026

Uh oh!

tito10047 commented Mar 7, 2026

Uh oh!

dbu commented Mar 18, 2026

Uh oh!

tito10047 commented Mar 19, 2026

Uh oh!

dbu left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tito10047 commented Mar 23, 2026

Uh oh!

dbu commented Mar 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tito10047 commented Feb 19, 2026 •

edited

Loading

coveralls commented Feb 19, 2026 •

edited

Loading