Skip to content

Add the normalize_filter_set_names option and deprecate the normalization of filter set names - #1676

Merged
dbu merged 3 commits into
liip:2.xfrom
Amoifr:feature-1670-filter-set-names-normalization
Nov 15, 2026
Merged

dbu merged 3 commits into
liip:2.xfrom
Amoifr:feature-1670-filter-set-names-normalization

Conversation

@Amoifr

@Amoifr Amoifr commented Nov 8, 2026

Copy link
Copy Markdown
Contributor
Q A
Branch? 2.x
Bug fix? no
New feature? yes
BC breaks? no
Deprecations? yes
Fixed tickets #1670
License MIT
Doc yes

As discussed in #1670: a new normalize_filter_set_names option, true by default, so that my-thumbnail can be used as is once it is set to false.

liip_imagine:
    normalize_filter_set_names: false
    filter_sets:
        my-thumbnail: # used as "my-thumbnail", not "my_thumbnail"

The option changes the configuration tree (normalizeKeys() on filter_sets), so the extension reads it from the raw configs before processing them, and passes it to Configuration through a new optional constructor argument. The last config file that sets it wins, like for any other option.

About the deprecation, one deviation from what you suggested, easy to revert if you prefer the strict version: it is only triggered when the normalization actually renames a filter set (a name with - and no _, same condition as Symfony's ArrayNode::preNormalize()), or when the option is explicitly set to true. An application without such a name is not affected by the 3.0 change, so asking everyone to add normalize_filter_set_names: false seemed like noise. The message lists the renamed names:

Filter set names are normalized: "my-thumb" is used as "my_thumb". This normalization is deprecated and will be removed in 3.0, set the "liip_imagine.normalize_filter_set_names" config option to false and use the filter set names as written in the configuration.

While checking, I noticed that filter sets declared in XML (<filter-set name="my-thumb">) were never normalized, since the key comes from the name attribute after the key normalization. They don't trigger the deprecation, and the docs say so.

For 3.x, dropping the normalization means removing the option and the normalizeKeys() call (or keeping normalizeKeys(false)).

Tested: the new tests fail without the change, full suite green on PHP 8.5, php-cs-fixer clean. PHPStan (PHP 8.2) reports nothing on the changed files, only the vips and asset-mapper classes that the CI job installs first.

@dbu dbu left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks, good idea for the deprecation warning only when relevant in the application!

i only have a small request for the documentation, the users might want the underscores, but then they need to use underscores in their config (be it xml or yaml)

Comment thread Resources/doc/configuration.rst Outdated
configuration, so ``my-thumbnail`` has to be used as ``my_thumbnail`` in templates and in the URLs.
This normalization is deprecated, and will be removed in version 3. To use your filter set names as
written, set ``normalize_filter_set_names`` to ``false``, and replace the underscored names in your
templates and code:

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i'd say "and make sure the names in configuration and your templates/code match literal".

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, reworded along your suggestion.

Comment thread UPGRADE.md Outdated
- __[Deprecated]__ A filter set name that contains a `-` and no `_` is renamed by the Symfony configuration, so
`my-thumbnail` has to be used as `my_thumbnail`. This normalization is deprecated and will be removed in 3.0. Set the
new `liip_imagine.normalize_filter_set_names` option to `false` to use the filter set names as written, and replace
the underscored names in your templates and code.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same here

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same wording here.

Comment thread DependencyInjection/Configuration.php Resolved
@Amoifr
Amoifr force-pushed the feature-1670-filter-set-names-normalization branch from e47738a to 36bf009 Compare November 15, 2026 08:50
@dbu
dbu merged commit 6e02f92 into liip:2.x Nov 15, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants