From ebb9d5e56c2854a3e3a04c6def7607b39dc6afd0 Mon Sep 17 00:00:00 2001 From: Pascal CESCON - Amoifr Date: Sun, 8 Nov 2026 18:38:35 +0100 Subject: [PATCH 1/3] Add the normalize_filter_set_names option and deprecate the normalization of filter set names --- CHANGELOG.md | 1 + DependencyInjection/Configuration.php | 14 +++- DependencyInjection/LiipImagineExtension.php | 68 ++++++++++++++++++- Resources/doc/configuration.rst | 31 +++++++++ .../DependencyInjection/ConfigurationTest.php | 21 ++++++ .../LiipImagineExtensionTest.php | 62 ++++++++++++++++- UPGRADE.md | 7 ++ 7 files changed, 201 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7067dc1bb..3c645d213 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ for a given releases. Unreleased, upcoming changes will be updated here periodic ## 2.19.0 (unreleased) - Add a `format_extension` resolver configuration, so the `FormatExtensionResolver` can decorate a configured resolver without declaring a service ([Amoifr](https://github.com/liip/LiipImagineBundle/pull/1675)) +- Add the `normalize_filter_set_names` option to allow `-` in filter set names, and deprecate the normalization of `-` to `_` ([Amoifr](https://github.com/liip/LiipImagineBundle/pull/XXXX)) ## [2.18.2](https://github.com/liip/LiipImagineBundle/tree/2.18.2) diff --git a/DependencyInjection/Configuration.php b/DependencyInjection/Configuration.php index 0ff85ecfa..6d2174349 100644 --- a/DependencyInjection/Configuration.php +++ b/DependencyInjection/Configuration.php @@ -33,14 +33,21 @@ class Configuration implements ConfigurationInterface */ protected $loadersFactories; + /** + * @var bool + */ + protected $normalizeFilterSetNames; + /** * @param ResolverFactoryInterface[] $resolversFactories * @param LoaderFactoryInterface[] $loadersFactories + * @param bool $normalizeFilterSetNames Whether to replace "-" by "_" in filter set names */ - public function __construct(array $resolversFactories, array $loadersFactories) + public function __construct(array $resolversFactories, array $loadersFactories, bool $normalizeFilterSetNames = true) { $this->resolversFactories = $resolversFactories; $this->loadersFactories = $loadersFactories; + $this->normalizeFilterSetNames = $normalizeFilterSetNames; } public function getConfigTreeBuilder(): TreeBuilder @@ -166,7 +173,12 @@ public function getConfigTreeBuilder(): TreeBuilder ->end() ->end() ->end() + ->booleanNode('normalize_filter_set_names') + ->defaultNull() + ->info('Whether to replace "-" by "_" in filter set names, as Symfony does for configuration keys. Not setting this option to false is deprecated: the normalization will be removed in 3.0.') + ->end() ->arrayNode('filter_sets') + ->normalizeKeys($this->normalizeFilterSetNames) ->useAttributeAsKey('name') ->prototype('array') ->fixXmlConfig('filter', 'filters') diff --git a/DependencyInjection/LiipImagineExtension.php b/DependencyInjection/LiipImagineExtension.php index 8baeda1fd..d08be703a 100644 --- a/DependencyInjection/LiipImagineExtension.php +++ b/DependencyInjection/LiipImagineExtension.php @@ -56,7 +56,11 @@ public function addLoaderFactory(LoaderFactoryInterface $loaderFactory): void public function getConfiguration(array $config, ContainerBuilder $container): ?ConfigurationInterface { - return new Configuration($this->resolversFactories, $this->loadersFactories); + return new Configuration( + $this->resolversFactories, + $this->loadersFactories, + false !== $this->getNormalizeFilterSetNames($config) + ); } /** @@ -69,6 +73,8 @@ public function load(array $configs, ContainerBuilder $container): void $configs ); + $this->triggerFilterSetNamesNormalizationDeprecation($configs); + if (interface_exists(MimeTypeGuesserInterface::class)) { $mimeTypes = new Definition(MimeTypes::class); $mimeTypes->setFactory([MimeTypes::class, 'getDefault']); @@ -160,6 +166,66 @@ public function prepend(ContainerBuilder $container): void } } + /** + * The option changes the configuration tree, so it has to be read from the raw configs. + * + * @param array $configs + */ + private function getNormalizeFilterSetNames(array $configs): ?bool + { + $normalize = null; + + foreach ($configs as $config) { + foreach (['normalize_filter_set_names', 'normalize-filter-set-names'] as $key) { + if (\is_array($config) && isset($config[$key])) { + $normalize = (bool) $config[$key]; + } + } + } + + return $normalize; + } + + /** + * @param array $configs + */ + private function triggerFilterSetNamesNormalizationDeprecation(array $configs): void + { + $normalize = $this->getNormalizeFilterSetNames($configs); + + if (false === $normalize) { + return; + } + + if (true === $normalize) { + trigger_deprecation('liip/imagine-bundle', '2.19', 'Setting the "liip_imagine.normalize_filter_set_names" config option to true is deprecated, set it to false and use the filter set names as written in the configuration. The option will be removed in 3.0.'); + + return; + } + + $renamed = []; + foreach ($configs as $config) { + foreach (['filter_sets', 'filter-sets'] as $key) { + if (!\is_array($config) || !\is_array($config[$key] ?? null)) { + continue; + } + + // same condition as Symfony\Component\Config\Definition\ArrayNode::preNormalize() + foreach (array_keys($config[$key]) as $name) { + $name = (string) $name; + $normalizedName = str_replace('-', '_', $name); + if (str_contains($name, '-') && !str_contains($name, '_') && !\array_key_exists($normalizedName, $config[$key])) { + $renamed[] = \sprintf('"%s" is used as "%s"', $name, $normalizedName); + } + } + } + } + + if ([] !== $renamed) { + trigger_deprecation('liip/imagine-bundle', '2.19', \sprintf('Filter set names are normalized: %s. 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.', implode(', ', array_unique($renamed)))); + } + } + private function createFilterSets(array $defaultFilterSets, array $filterSets): array { return array_map(static function (array $filterSet) use ($defaultFilterSets) { diff --git a/Resources/doc/configuration.rst b/Resources/doc/configuration.rst index f6e40fb01..eb57b4468 100644 --- a/Resources/doc/configuration.rst +++ b/Resources/doc/configuration.rst @@ -50,6 +50,7 @@ The default configuration for the bundle looks like this: cache: ~ data_loader: ~ post_processors: [] + normalize_filter_set_names: ~ # true, deprecated filter_sets: # Prototype @@ -117,6 +118,11 @@ There are several configuration options available: ``filter_sets``. These values will be overridden if they are specified in the each set. In case of ``filters`` and ``post_processors``, the specified values will be merged with the default ones. * ``filter_sets`` - specify the filter sets that you want to define and use. +* ``normalize_filter_set_names`` - whether ``-`` is replaced by ``_`` in the filter set names, + following the Symfony convention for configuration keys. Default value: ``true``. When this + normalization renames one of your filter sets, a deprecation is triggered unless you set the + option to ``false``: version 3 will use the filter set names as written. See + `Filter set names`_ below. Each filter set that you specify has the following options: @@ -142,6 +148,31 @@ Each filter set that you specify has the following options: Imagine (PR pending)) +Filter set names +---------------- + +By default, 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`` 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: + +.. code-block:: yaml + + liip_imagine: + normalize_filter_set_names: false + filter_sets: + my-thumbnail: + filters: + thumbnail: { size: [120, 90], mode: outbound } + +.. code-block:: twig + + + +Names that already contain a ``_``, like ``my-thumbnail_v2``, and names coming from an XML +configuration were never renamed and do not need any change. + Default image ------------- diff --git a/Tests/DependencyInjection/ConfigurationTest.php b/Tests/DependencyInjection/ConfigurationTest.php index 87cd6b1a9..e6efbc681 100644 --- a/Tests/DependencyInjection/ConfigurationTest.php +++ b/Tests/DependencyInjection/ConfigurationTest.php @@ -475,6 +475,27 @@ public function testWebpEnableGenerate(): void $this->assertTrue($config['webp']['generate']); } + public function testFilterSetNamesAreNormalizedByDefault(): void + { + $config = $this->processConfiguration(new Configuration([new WebPathResolverFactory()], [new FileSystemLoaderFactory()]), [[ + 'filter_sets' => ['my-thumb' => []], + ]]); + + $this->assertSame(['my_thumb'], array_keys($config['filter_sets'])); + $this->assertNull($config['normalize_filter_set_names']); + } + + public function testFilterSetNamesAreKeptWhenNormalizationIsDisabled(): void + { + $config = $this->processConfiguration(new Configuration([new WebPathResolverFactory()], [new FileSystemLoaderFactory()], false), [[ + 'normalize_filter_set_names' => false, + 'filter_sets' => ['my-thumb' => []], + ]]); + + $this->assertSame(['my-thumb'], array_keys($config['filter_sets'])); + $this->assertFalse($config['normalize_filter_set_names']); + } + protected function processConfiguration(ConfigurationInterface $configuration, array $configs): array { $processor = new Processor(); diff --git a/Tests/DependencyInjection/LiipImagineExtensionTest.php b/Tests/DependencyInjection/LiipImagineExtensionTest.php index 9495c32b7..cdb5b0542 100644 --- a/Tests/DependencyInjection/LiipImagineExtensionTest.php +++ b/Tests/DependencyInjection/LiipImagineExtensionTest.php @@ -17,6 +17,7 @@ use Liip\ImagineBundle\DependencyInjection\LiipImagineExtension; use Liip\ImagineBundle\Imagine\Filter\FilterManager; use Liip\ImagineBundle\Tests\AbstractTest; +use Symfony\Bridge\PhpUnit\ExpectDeprecationTrait; use Symfony\Component\DependencyInjection\ContainerBuilder; use Symfony\Component\DependencyInjection\ContainerInterface; use Symfony\Component\DependencyInjection\Definition; @@ -31,6 +32,8 @@ */ class LiipImagineExtensionTest extends AbstractTest { + use ExpectDeprecationTrait; + /** * @var ContainerBuilder */ @@ -213,6 +216,58 @@ public function testHelperIsNotRegisteredWhenTemplatingIsDisabled(): void $this->assertHasNotDefinition('liip_imagine.templating.filter_helper'); } + /** + * @group legacy + */ + public function testFilterSetNamesAreNormalizedByDefault(): void + { + $this->expectDeprecation('Since liip/imagine-bundle 2.19: 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.'); + + $this->createConfiguration([ + 'filter_sets' => [ + 'my-thumb' => null, + 'my-thumb_v2' => null, + 'small' => null, + ], + ]); + + $this->assertSame( + ['my_thumb', 'my-thumb_v2', 'small'], + array_keys($this->containerBuilder->getParameter('liip_imagine.filter_sets')) + ); + } + + public function testFilterSetNamesAreKeptWhenNormalizationIsDisabled(): void + { + $this->createConfigurations([ + ['normalize_filter_set_names' => false], + ['filter_sets' => ['my-thumb' => null, 'small' => null]], + ]); + + $this->assertSame( + ['my-thumb', 'small'], + array_keys($this->containerBuilder->getParameter('liip_imagine.filter_sets')) + ); + } + + /** + * @group legacy + */ + public function testEnablingFilterSetNamesNormalizationIsDeprecated(): void + { + $this->expectDeprecation('Since liip/imagine-bundle 2.19: Setting the "liip_imagine.normalize_filter_set_names" config option to true is deprecated, set it to false and use the filter set names as written in the configuration. The option will be removed in 3.0.'); + + $this->createConfiguration([ + 'normalize_filter_set_names' => true, + 'filter_sets' => ['my-thumb' => null], + ]); + + $this->assertSame( + ['my_thumb'], + array_keys($this->containerBuilder->getParameter('liip_imagine.filter_sets')) + ); + } + protected function createConfigurationWithDefaultsFilterSets(): void { if (!class_exists(Parser::class)) { @@ -281,12 +336,17 @@ protected function createFullConfiguration(): void } protected function createConfiguration(array $configuration): void + { + $this->createConfigurations([$configuration]); + } + + protected function createConfigurations(array $configurations): void { $this->containerBuilder = new ContainerBuilder(); $loader = new LiipImagineExtension(); $loader->addLoaderFactory(new FileSystemLoaderFactory()); $loader->addResolverFactory(new WebPathResolverFactory()); - $loader->load([$configuration], $this->containerBuilder); + $loader->load($configurations, $this->containerBuilder); $this->assertInstanceOf(ContainerBuilder::class, $this->containerBuilder); } diff --git a/UPGRADE.md b/UPGRADE.md index 25d5421a1..ef1d57051 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -6,6 +6,13 @@ application code or are otherwise particularly noteworthy. Reference our full [changelog](https://github.com/liip/LiipImagineBundle/blob/2.x/CHANGELOG.md) for a complete list of all changes for a given release. +## 2.19.0 + +- __[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. + ## 2.3.0 - 2.7.0 - __[Deprecated]__ As `doctrine/cache` has been deprecated, the `Liip\ImagineBundle\Imagine\Resolver\CacheResolver` From 2b609532b221bdcf329737e37a46537eb9c39e24 Mon Sep 17 00:00:00 2001 From: Pascal CESCON - Amoifr Date: Sun, 8 Nov 2026 18:39:18 +0100 Subject: [PATCH 2/3] Link the pull request in the changelog --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3c645d213..e04c1c95c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ for a given releases. Unreleased, upcoming changes will be updated here periodic ## 2.19.0 (unreleased) - Add a `format_extension` resolver configuration, so the `FormatExtensionResolver` can decorate a configured resolver without declaring a service ([Amoifr](https://github.com/liip/LiipImagineBundle/pull/1675)) -- Add the `normalize_filter_set_names` option to allow `-` in filter set names, and deprecate the normalization of `-` to `_` ([Amoifr](https://github.com/liip/LiipImagineBundle/pull/XXXX)) +- Add the `normalize_filter_set_names` option to allow `-` in filter set names, and deprecate the normalization of `-` to `_` ([Amoifr](https://github.com/liip/LiipImagineBundle/pull/1676)) ## [2.18.2](https://github.com/liip/LiipImagineBundle/tree/2.18.2) From 36bf0092f9da5c9658d40aa995c38224b8597773 Mon Sep 17 00:00:00 2001 From: Pascal CESCON - Amoifr Date: Sun, 15 Nov 2026 09:50:27 +0100 Subject: [PATCH 3/3] Ask for matching filter set names in the configuration and the templates --- Resources/doc/configuration.rst | 4 ++-- UPGRADE.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Resources/doc/configuration.rst b/Resources/doc/configuration.rst index eb57b4468..4624767fa 100644 --- a/Resources/doc/configuration.rst +++ b/Resources/doc/configuration.rst @@ -154,8 +154,8 @@ Filter set names By default, 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`` 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: +written, set ``normalize_filter_set_names`` to ``false``, and make sure the names in your +configuration match the names used in your templates and code literally: .. code-block:: yaml diff --git a/UPGRADE.md b/UPGRADE.md index ef1d57051..46d2f7efc 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -10,8 +10,8 @@ given release. - __[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. + new `liip_imagine.normalize_filter_set_names` option to `false` to use the filter set names as written, and make sure + the names in your configuration match the names used in your templates and code literally. ## 2.3.0 - 2.7.0