[Icons] Icon aliases

src/Icons/CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## 2.20.0
+
+-   Add `aliases` configuration option to define icon alternative names.
+
 ## 2.19.0
 
 -   Add `ignore_not_found` option to silence error during rendering if the 

src/Icons/config/services.php

@@ -56,6 +56,8 @@
         ->set('.ux_icons.icon_renderer', IconRenderer::class)
             ->args([
                 service('.ux_icons.icon_registry'),
+                abstract_arg('default_icon_attributes'),
+                abstract_arg('icon_aliases'),
             ])
 
         ->alias('Symfony\UX\Icons\IconRendererInterface', '.ux_icons.icon_renderer')

src/Icons/doc/index.rst

@@ -336,6 +336,30 @@ Now, all icons will have the ``fill`` attribute set to ``currentColor`` by defau
     # renders "user-profile.svg" with fill="red"
     {{ ux_icon('user-profile', {fill: 'red'}) }}
 
+Icon Aliases
+~~~~~~~~~~~~
+
+You can define aliases for icons in your configuration, which is helpful if 
+you want to use a different or shorter name for an icon in your templates:
+
+.. code-block:: yaml
+
+    # config/packages/ux_icons.yaml
+    ux_icons:
+
+        aliases:
+            dots: 'clarity:ellipsis-horizontal-line'
+
+Now, you can use the ``dots`` alias in your templates:
+
+.. code-block:: twig
+
+    {{ ux_icon('dots') }}
+
+    {# same as #}
+
+    {{ ux_icon('clarity:ellipsis-horizontal-line') }}
+
 Errors
 ------
 
@@ -517,6 +541,11 @@ Full Configuration
         default_icon_attributes:
             # Default:
             fill: currentColor
+
+        # Icon aliases (alias => icon name).
+        aliases:
+            # Exemple:
+            dots: 'clarity:ellipsis-horizontal-line'    
 
         # Configuration for the "on demand" icons powered by Iconify.design.
         iconify:

src/Icons/src/DependencyInjection/UXIconsExtension.php

@@ -43,6 +43,14 @@ public function getConfigTreeBuilder(): TreeBuilder
                     ->info('Default attributes to add to all icons.')
                     ->defaultValue(['fill' => 'currentColor'])
                 ->end()
+                ->arrayNode('aliases')
+                    ->info('Icon aliases (alias => icon name).')
+                    ->example(['dots' => 'clarity:ellipsis-horizontal-line'])
+                    ->normalizeKeys(false)
+                    ->scalarPrototype()
+                        ->cannotBeEmpty()
+                    ->end()
+                ->end()
                 ->arrayNode('iconify')
                     ->info('Configuration for the "on demand" icons powered by Iconify.design.')
                     ->{interface_exists(HttpClientInterface::class) ? 'canBeDisabled' : 'canBeEnabled'}()
@@ -98,6 +106,7 @@ protected function loadInternal(array $mergedConfig, ContainerBuilder $container
 
         $container->getDefinition('.ux_icons.icon_renderer')
             ->setArgument(1, $mergedConfig['default_icon_attributes'])
+            ->setArgument(2, $mergedConfig['aliases'])
         ;
 
         $container->getDefinition('.ux_icons.twig_icon_runtime')

src/Icons/src/IconRenderer.php

@@ -21,6 +21,7 @@ final class IconRenderer implements IconRendererInterface
     public function __construct(
         private readonly IconRegistryInterface $registry,
         private readonly array $defaultIconAttributes = [],
+        private readonly ?array $iconAliases = [],
     ) {
     }
 
@@ -35,6 +36,8 @@ public function __construct(
      */
     public function renderIcon(string $name, array $attributes = []): string
     {
+        $name = $this->iconAliases[$name] ?? $name;
+
         $icon = $this->registry->get($name)
             ->withAttributes($this->defaultIconAttributes)
             ->withAttributes($attributes);

src/Icons/tests/Unit/IconRendererTest.php

@@ -230,6 +230,25 @@ public static function provideAriaHiddenCases(): iterable
         ];
     }
 
+    public function testRenderIconWithAliases(): void
+    {
+        $registry = $this->createRegistry([
+            'foo' => '<path d="M0 FOO"/>',
+            'bar' => '<path d="M0 BAR"/>',
+            'baz' => '<path d="M0 BAZ"/>',
+        ]);
+        $iconRenderer = new IconRenderer($registry, [], ['foo' => 'bar']);
+
+        $svg = $iconRenderer->renderIcon('bar');
+        $this->assertSame('<svg aria-hidden="true"><path d="M0 BAR"/></svg>', $svg);
+
+        $svg = $iconRenderer->renderIcon('foo');
+        $this->assertSame('<svg aria-hidden="true"><path d="M0 BAR"/></svg>', $svg);
+
+        $svg = $iconRenderer->renderIcon('baz');
+        $this->assertSame('<svg aria-hidden="true"><path d="M0 BAZ"/></svg>', $svg);
+    }
+
     private function createRegistry(array $icons): IconRegistryInterface
     {
         $registryIcons = [];