[Icons] allow configuring multiple local directories and optionally prefixing them

src/Icons/doc/index.rst

@@ -27,10 +27,42 @@ No icons are provided by this package but there are several ways to include and
 Local SVG Icons
 ~~~~~~~~~~~~~~~
 
-Add your svg icons to the ``assets/icons/`` directory and commit them.
+Add your svg icons to the configured local icon directory (``assets/icons/`` by default) and commit them.
 The name of the file is used as the _name_ of the icon (``name.svg`` will be named ``name``).
 If located in a subdirectory, the _name_ will be ``sub-dir:name``.
 
+Multiple Directories
+^^^^^^^^^^^^^^^^^^^^
+
+You can configure multiple directories to search for icons. The first directory to contain the
+icon will be used.
+
+.. code-block:: yaml
+
+    ux_icons:
+        icon_dir:
+            - %kernel.project_dir%/assets/icons
+            - %kernel.project_dir%/vendor/your-vendor/your-bundle/assets/icons
+
+.. tip::
+
+    You can suffix the path with ``@<alias>`` to use a prefix. For example, let's say you
+    have the ``fortawesome/font-awesome`` composer package installed and you want to use
+    the ``fa`` prefix:
+
+    .. code-block:: yaml
+
+        ux_icons:
+            icon_dir:
+                # ...
+                - %kernel.project_dir%/vendor/fortawesome/font-awesome/svgs@fa
+
+    Now, you can use the ``fa:icon-name`` syntax to render icons from the FontAwesome set:
+
+    .. code-block:: html+twig
+
+        {{ ux_icon('fa:solid:adjust', {class: 'w-4 h-4'}) }} <!-- renders "vendor/fortawesome/font-awesome/svgs/solid/adjust.svg" -->
+
 Icons On-Demand
 ~~~~~~~~~~~~~~~
 
@@ -130,8 +162,14 @@ Full Default Configuration
 .. code-block:: yaml
 
     ux_icons:
-        # The local directory where icons are stored.
-        icon_dir: '%kernel.project_dir%/assets/icons'
+        # The local directory('s) where icons are stored.
+        # Order matters as the first directory to contain the icon will be used.
+        # The first directory will be used to store imported icons.
+        # Suffix with "@<alias>" to use a prefix.
+        icon_dir:
+
+            # Default:
+            - %kernel.project_dir%/assets/icons
 
         # Default attributes to add to all icons.
         default_icon_attributes:

src/Icons/src/DependencyInjection/UXIconsExtension.php

@@ -34,9 +34,36 @@ public function getConfigTreeBuilder(): TreeBuilder
 
         $rootNode
             ->children()
-                ->scalarNode('icon_dir')
-                    ->info('The local directory where icons are stored.')
-                    ->defaultValue('%kernel.project_dir%/assets/icons')
+                ->arrayNode('icon_dir')
+                    ->beforeNormalization()
+                        ->ifString()
+                        ->then(static fn ($v) => [$v])
+                    ->end()
+                    ->beforeNormalization()
+                        ->always(function (array $values) {
+                            $ret = [];
+
+                            foreach ($values as $value) {
+                                if (2 === \count($parts = explode('@', $value, 2))) {
+                                    $ret[$parts[1]] = $parts[0];
+
+                                    continue;
+                                }
+
+                                $ret[] = $value;
+                            }
+
+                            return $ret;
+                        })
+                    ->end()
+                    ->info(<<<EOF
+                        The local directory('s) where icons are stored.
+                        Order matters as the first directory to contain the icon will be used.
+                        The first directory will be used to store imported icons.
+                        Suffix with "@<alias>" to use a prefix.
+                        EOF)
+                    ->scalarPrototype()->end()
+                    ->defaultValue(['%kernel.project_dir%/assets/icons'])
                 ->end()
                 ->variableNode('default_icon_attributes')
                     ->info('Default attributes to add to all icons.')

src/Icons/src/Registry/LocalSvgIconRegistry.php

@@ -23,22 +23,32 @@
  */
 final class LocalSvgIconRegistry implements IconRegistryInterface
 {
-    public function __construct(private string $iconDir)
+    /**
+     * @param string[] $iconDirs
+     */
+    public function __construct(private array $iconDirs)
     {
     }
 
     public function get(string $name): Icon
     {
-        if (!file_exists($filename = sprintf('%s/%s.svg', $this->iconDir, str_replace(':', '/', $name)))) {
-            throw new IconNotFoundException(sprintf('The icon "%s" (%s) does not exist.', $name, $filename));
+        foreach ($this->iconDirs as $key => $dir) {
+            if (!is_numeric($key) && str_starts_with($name, $key.':')) {
+                $name = substr($name, \strlen($key) + 1);
+            }
+
+            if (file_exists($filename = sprintf('%s/%s.svg', $dir, str_replace(':', '/', $name)))) {
+                return Icon::fromFile($filename);
+            }
         }
 
-        return Icon::fromFile($filename);
+        throw new IconNotFoundException(sprintf('The svg file for icon "%s" does not exist.', $name));
     }
 
     public function add(string $name, string $svg): void
     {
-        $filename = sprintf('%s/%s.svg', $this->iconDir, $name);
+        $dir = $this->iconDirs[array_key_first($this->iconDirs)] ?? throw new \LogicException('No local icon directory configured.');
+        $filename = sprintf('%s/%s.svg', $dir, $name);
 
         (new Filesystem())->dumpFile($filename, $svg);
     }

src/Icons/tests/Fixtures/TestKernel.php

@@ -49,7 +49,11 @@ protected function configureContainer(ContainerConfigurator $c): void
         ]);
 
         $c->extension('ux_icons', [
-            'icon_dir' => '%kernel.project_dir%/tests/Fixtures/icons',
+            'icon_dir' => [
+                '%kernel.project_dir%/tests/Fixtures/icons',
+                '%kernel.project_dir%/tests/Fixtures/icons2',
+                '%kernel.project_dir%/tests/Fixtures/icons3@fa',
+            ],
         ]);
 
         $c->services()->set('logger', NullLogger::class);

src/Icons/tests/Fixtures/templates/template2.html.twig

@@ -1,3 +1,5 @@
 {{ ux_icon('something:invalid') }}
 {{ ux_icon('invalid') }}
 {{ ux_icon('iconamoon:invalid') }}
+{{ ux_icon('arrow') }}
+{{ ux_icon('fa:solid:thing') }}

src/Icons/tests/Integration/Command/WarmCacheCommandTest.php

@@ -29,6 +29,8 @@ public function testCanWarmCache(): void
             ->assertOutputContains('Warmed icon user.')
             ->assertOutputContains('Warmed icon sub:check.')
             ->assertOutputContains('Warmed icon iconamoon:3d-duotone.')
+            ->assertOutputContains('Warmed icon arrow.')
+            ->assertOutputContains('Warmed icon fa:solid:thing.')
             ->assertOutputContains('Icon cache warmed.')
         ;
     }

src/Icons/tests/Unit/Registry/LocalSvgIconRegistryTest.php

@@ -84,6 +84,6 @@ public static function invalidSvgProvider(): iterable
 
     private function registry(): LocalSvgIconRegistry
     {
-        return new LocalSvgIconRegistry(__DIR__.'/../../Fixtures/svg');
+        return new LocalSvgIconRegistry([__DIR__.'/../../Fixtures/svg']);
     }
 }