Add AssetMapper support

.github/workflows/phpstan.yml

@@ -26,5 +26,8 @@ jobs:
       - name: Add vips
         run: composer require rokka/imagine-vips
 
+      - name: Add asset mapper
+        run: composer require symfony/asset-mapper
+
       - name: Run PHPStan
         run: vendor/bin/phpstan analyze

.github/workflows/phpunit.yml

@@ -84,6 +84,11 @@ jobs:
           SYMFONY_DEPRECATIONS_HELPER: max[self]=0
         run: vendor/bin/simple-phpunit -v
 
+      - name: Add asset mapper
+        # asset mapper support is optional in LiipImagineBundle. asset mapper was only added in symfony 6
+        if: ${{ matrix.symfony >= '6.4' }}
+        run: composer require --no-update symfony/asset-mapper --dev
+
       - name: Install php-coveralls
         run: composer global require --no-interaction --no-progress php-coveralls/php-coveralls
 

Binary/Locator/AssetMapperLocator.php

@@ -0,0 +1,61 @@
+<?php
+
+/*
+ * This file is part of the `liip/LiipImagineBundle` project.
+ *
+ * (c) https://github.com/liip/LiipImagineBundle/graphs/contributors
+ *
+ * For the full copyright and license information, please view the LICENSE.md
+ * file that was distributed with this source code.
+ */
+
+namespace Liip\ImagineBundle\Binary\Locator;
+
+use Liip\ImagineBundle\Exception\Binary\Loader\NotLoadableException;
+use Symfony\Component\AssetMapper\AssetMapperInterface;
+
+/**
+ * Resolves asset paths using the Symfony AssetMapper component.
+ *
+ * In a development environment, AssetMapper serves assets from their source directories (typically `/assets`)
+ * without versioning. However, Twig's `asset()` helper generates public paths that include version hashes.
+ * Since these versioned files do not physically exist on disk during development, this locator is used
+ * to map the requested public versioned path back to the actual source file on the filesystem.
+ *
+ * In production, AssetMapper compiles and copies assets to the public directory with their version hashes
+ * included in the filenames. Consequently, this locator is no longer necessary as the files exist at
+ * their versioned paths.
+ */
+class AssetMapperLocator implements LocatorInterface
+{
+    public function __construct(
+        private AssetMapperInterface $assetMapper,
+    ) {
+    }
+
+    /**
+     * Locates the physical source file for a given public asset path.
+     *
+     * This method iterates through all registered assets in the AssetMapper to find a match
+     * for the provided public path (which may contain a version hash). If a match is found,
+     * it returns the absolute path to the original source file.
+     *
+     * Inspired by Symfony's AssetMapper component @see https://github.com/symfony/asset-mapper/blob/7.3/AssetMapperDevServerSubscriber.php#L179.
+     *
+     * @param string $path the public path of the asset (e.g., as generated by Twig's asset() helper)
+     *
+     * @throws NotLoadableException if the public path cannot be resolved to a source asset
+     *
+     * @return string the absolute path to the source asset file
+     */
+    public function locate(string $path): string
+    {
+        $path = '/'.mb_ltrim($path, '/');
+        foreach ($this->assetMapper->allAssets() as $assetCandidate) {
+            if ($path === $assetCandidate->publicPath) {
+                return $assetCandidate->sourcePath;
+            }
+        }
+        throw new NotLoadableException(\sprintf('Asset with public path "%s" not found.', $path));
+    }
+}

DependencyInjection/Factory/Loader/AssetMapperLoaderFactory.php

@@ -0,0 +1,49 @@
+<?php
+
+/*
+ * This file is part of the `liip/LiipImagineBundle` project.
+ *
+ * (c) https://github.com/liip/LiipImagineBundle/graphs/contributors
+ *
+ * For the full copyright and license information, please view the LICENSE.md
+ * file that was distributed with this source code.
+ */
+
+namespace Liip\ImagineBundle\DependencyInjection\Factory\Loader;
+
+use Symfony\Component\Config\Definition\Builder\ArrayNodeDefinition;
+use Symfony\Component\DependencyInjection\ChildDefinition;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\DependencyInjection\Reference;
+
+class AssetMapperLoaderFactory extends AbstractLoaderFactory
+{
+    public function create(ContainerBuilder $container, $loaderName, array $config)
+    {
+        $locatorDefinition = new ChildDefinition('liip_imagine.binary.locator.asset_mapper');
+        $locatorDefinition->replaceArgument(0, new Reference('asset_mapper'));
+
+        $definition = $this->getChildLoaderDefinition('filesystem');
+
+        if ($container->hasDefinition('liip_imagine.mime_types')) {
+            $mimeTypes = $container->getDefinition('liip_imagine.mime_types');
+            $definition->replaceArgument(0, $mimeTypes);
+            $definition->replaceArgument(1, $mimeTypes);
+        }
+        $definition->replaceArgument(2, $locatorDefinition);
+
+        return $this->setTaggedLoaderDefinition($loaderName, $definition, $container);
+    }
+
+    public function getName()
+    {
+        return 'asset_mapper';
+    }
+
+    public function addConfiguration(ArrayNodeDefinition $builder)
+    {
+        $builder
+            ->children()
+            ->end();
+    }
+}

LiipImagineBundle.php

@@ -23,6 +23,7 @@
 use Liip\ImagineBundle\DependencyInjection\Compiler\NonFunctionalFilterExceptionPass;
 use Liip\ImagineBundle\DependencyInjection\Compiler\PostProcessorsCompilerPass;
 use Liip\ImagineBundle\DependencyInjection\Compiler\ResolversCompilerPass;
+use Liip\ImagineBundle\DependencyInjection\Factory\Loader\AssetMapperLoaderFactory;
 use Liip\ImagineBundle\DependencyInjection\Factory\Loader\ChainLoaderFactory;
 use Liip\ImagineBundle\DependencyInjection\Factory\Loader\FileSystemLoaderFactory;
 use Liip\ImagineBundle\DependencyInjection\Factory\Loader\FlysystemLoaderFactory;
@@ -69,6 +70,7 @@ public function build(ContainerBuilder $container): void
         $extension->addLoaderFactory(new StreamLoaderFactory());
         $extension->addLoaderFactory(new FileSystemLoaderFactory());
         $extension->addLoaderFactory(new FlysystemLoaderFactory());
+        $extension->addLoaderFactory(new AssetMapperLoaderFactory());
         $extension->addLoaderFactory(new ChainLoaderFactory());
 
         $container->registerForAutoconfiguration(LoaderLoaderInterface::class)->addTag('liip_imagine.filter.loader');

Resources/config/imagine.php

@@ -21,6 +21,7 @@
 use Liip\ImagineBundle\Binary\Loader\FlysystemLoader;
 use Liip\ImagineBundle\Binary\Loader\FlysystemV2Loader;
 use Liip\ImagineBundle\Binary\Loader\StreamLoader;
+use Liip\ImagineBundle\Binary\Locator\AssetMapperLocator;
 use Liip\ImagineBundle\Binary\Locator\FileSystemInsecureLocator;
 use Liip\ImagineBundle\Binary\Locator\FileSystemLocator;
 use Liip\ImagineBundle\Binary\SimpleMimeTypeGuesser;
@@ -429,6 +430,13 @@
             '', // will be injected by FilesystemLoaderFactory
         ])
         ->tag('liip_imagine.binary.locator', ['shared' => false]);
+    $services->set('liip_imagine.binary.locator.asset_mapper', AssetMapperLocator::class)
+        ->share(true)
+        ->public()
+        ->args([
+            '', // will be injected by AssetMapperLoaderFactory
+        ])
+        ->tag('liip_imagine.binary.locator', ['shared' => false]);
 
     $services->set('liip_imagine.binary.locator.filesystem_insecure', FileSystemInsecureLocator::class)
         ->share(false)

Resources/doc/configuration.rst

@@ -77,7 +77,8 @@ There are several configuration options available:
 * ``cache`` - default cache resolver. Default value: ``web_path`` (which means
   the standard web_path resolver is used)
 * ``data_loader`` - name of a custom data loader. Default value: ``filesystem``
-  (which means the standard filesystem loader is used).
+  (which means the standard filesystem loader is used). Built-in loaders include:
+  ``filesystem``, ``chain``, ``flysystem``, ``stream``, and ``asset_mapper``.
 * ``twig.mode`` - Twig filter integration. ``none`` disables the twig filters, ``lazy`` enables
   Twig using the Twig runtime for lazy loading. The default value is ``legacy`` and enables the
   old Twig integration that is loaded on each request. Version 3 will drop ``legacy`` and default
@@ -99,7 +100,8 @@ There are several configuration options available:
     * ``cache`` - default cache resolver. Default value: ``web_path`` (which means
       the standard web_path resolver is used)
     * ``data_loader`` - name of a custom data loader. Default value: ``filesystem``
-      (which means the standard filesystem loader is used).
+      (which means the standard filesystem loader is used). Built-in loaders include:
+      ``filesystem``, ``chain``, ``flysystem``, ``stream``, and ``asset_mapper``.
     * ``post_processors`` - sets post-processors to be applied on filtered image
       (see Post-Processors section in the :doc:`filters chapter <filters>` for details).
 * ``driver`` - one of the drivers: ``gd``, ``imagick``, ``gmagick``, ``vips``.

Resources/doc/data-loader/asset_mapper.rst

@@ -0,0 +1,29 @@
+
+.. _data-loaders-asset-mapper:
+
+Asset Mapper Loader (for dev)
+============================
+
+The ``AssetMapper`` data loader allows for loading images using Symfony's AssetMapper component.
+
+Configuration
+-------------
+
+To enable the Asset Mapper loader, you need to configure it in your loaders section. 
+A common use case is to use it in combination with the default filesystem loader using a chain loader, 
+especially in development environment.
+
+.. code-block:: yaml
+
+    # config/packages/liip_imagine.yaml
+    when@dev:
+        liip_imagine:
+            loaders:
+                asset_mapper:
+                    asset_mapper: ~
+                chain:
+                    chain:
+                        loaders: [ asset_mapper, default ]
+            data_loader: chain
+
+This configuration creates an ``asset_mapper`` loader and a ``chain`` loader that first tries to find the asset via AssetMapper, and then falls back to the ``default`` loader. Finally, it sets the global ``data_loader`` to use this new ``chain`` loader.

Tests/Binary/Locator/AssetMapperLocatorTest.php

@@ -0,0 +1,75 @@
+<?php
+
+/*
+ * This file is part of the `liip/LiipImagineBundle` project.
+ *
+ * (c) https://github.com/liip/LiipImagineBundle/graphs/contributors
+ *
+ * For the full copyright and license information, please view the LICENSE.md
+ * file that was distributed with this source code.
+ */
+
+namespace Liip\ImagineBundle\Tests\Binary\Locator;
+
+use Liip\ImagineBundle\Binary\Locator\AssetMapperLocator;
+use Liip\ImagineBundle\Binary\Locator\LocatorInterface;
+use Liip\ImagineBundle\Exception\Binary\Loader\NotLoadableException;
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\AssetMapper\AssetMapperInterface;
+use Symfony\Component\AssetMapper\MappedAsset;
+
+/**
+ * @covers \Liip\ImagineBundle\Binary\Locator\AssetMapperLocator
+ */
+class AssetMapperLocatorTest extends TestCase
+{
+    protected function setUp(): void
+    {
+        if (!interface_exists(AssetMapperInterface::class)) {
+            $this->markTestSkipped('symfony/asset-mapper is required for this test.');
+        }
+    }
+
+    public function testImplementsLocatorInterface(): void
+    {
+        $assetMapper = $this->createMock(AssetMapperInterface::class);
+        $this->assertInstanceOf(LocatorInterface::class, new AssetMapperLocator($assetMapper));
+    }
+
+    public function testLocateWithoutCache(): void
+    {
+        $path = 'images/logo.png';
+        $pathInfo = '/images/logo.png';
+        $sourcePath = '/path/to/logo.png';
+        $logicalPath = 'logo.png';
+
+        $asset = new MappedAsset($logicalPath, $sourcePath, $pathInfo, $pathInfo);
+
+        $assetMapper = $this->createMock(AssetMapperInterface::class);
+        $assetMapper->expects($this->once())
+            ->method('allAssets')
+            ->willReturn([$asset]);
+
+        $locator = new AssetMapperLocator($assetMapper);
+        $result = $locator->locate($path);
+
+        $this->assertSame($sourcePath, $result);
+    }
+
+    public function testThrowsIfAssetNotFound(): void
+    {
+        $path = 'images/logo.png';
+
+        $assetMapper = $this->createMock(AssetMapperInterface::class);
+        $assetMapper->expects($this->once())
+            ->method('allAssets')
+            ->willReturn([]);
+
+        $locator = new AssetMapperLocator($assetMapper);
+
+        $this->expectException(NotLoadableException::class);
+        $this->expectExceptionMessage('Asset with public path "/images/logo.png" not found.');
+
+        $locator->locate($path);
+    }
+}

Tests/DependencyInjection/Factory/Loader/AssetMapperLoaderFactoryTest.php

@@ -0,0 +1,59 @@
+<?php
+
+/*
+ * This file is part of the `liip/LiipImagineBundle` project.
+ *
+ * (c) https://github.com/liip/LiipImagineBundle/graphs/contributors
+ *
+ * For the full copyright and license information, please view the LICENSE.md
+ * file that was distributed with this source code.
+ */
+
+namespace Liip\ImagineBundle\Tests\DependencyInjection\Factory\Loader;
+
+use Liip\ImagineBundle\DependencyInjection\Factory\Loader\AssetMapperLoaderFactory;
+use Liip\ImagineBundle\DependencyInjection\Factory\Loader\LoaderFactoryInterface;
+use Liip\ImagineBundle\Tests\DependencyInjection\Factory\FactoryTestCase;
+use Symfony\Component\AssetMapper\AssetMapperInterface;
+use Symfony\Component\DependencyInjection\ChildDefinition;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+
+/**
+ * @covers \Liip\ImagineBundle\DependencyInjection\Factory\Loader\AssetMapperLoaderFactory<extended>
+ */
+class AssetMapperLoaderFactoryTest extends FactoryTestCase
+{
+    protected function setUp(): void
+    {
+        if (!interface_exists(AssetMapperInterface::class)) {
+            $this->markTestSkipped('symfony/asset-mapper is required for this test.');
+        }
+    }
+
+    public function testImplementsLoaderFactoryInterface(): void
+    {
+        $this->assertInstanceOf(LoaderFactoryInterface::class, new AssetMapperLoaderFactory());
+    }
+
+    public function testReturnsExpectedName(): void
+    {
+        $this->assertSame('asset_mapper', (new AssetMapperLoaderFactory())->getName());
+    }
+
+    public function testCreateLoaderDefinition(): void
+    {
+        $container = new ContainerBuilder();
+
+        $loader = new AssetMapperLoaderFactory();
+        $loader->create($container, 'the_loader_name', [
+        ]);
+
+        $this->assertTrue($container->hasDefinition('liip_imagine.binary.loader.the_loader_name'));
+
+        /** @var ChildDefinition $loaderDefinition */
+        $loaderDefinition = $container->getDefinition('liip_imagine.binary.loader.the_loader_name');
+
+        $this->assertInstanceOfChildDefinition($loaderDefinition);
+        $this->assertSame('liip_imagine.binary.loader.prototype.filesystem', $loaderDefinition->getParent());
+    }
+}

Tests/LiipImagineBundleTest.php

@@ -20,6 +20,7 @@
 use Liip\ImagineBundle\DependencyInjection\Compiler\NonFunctionalFilterExceptionPass;
 use Liip\ImagineBundle\DependencyInjection\Compiler\PostProcessorsCompilerPass;
 use Liip\ImagineBundle\DependencyInjection\Compiler\ResolversCompilerPass;
+use Liip\ImagineBundle\DependencyInjection\Factory\Loader\AssetMapperLoaderFactory;
 use Liip\ImagineBundle\DependencyInjection\Factory\Loader\ChainLoaderFactory;
 use Liip\ImagineBundle\DependencyInjection\Factory\Loader\FileSystemLoaderFactory;
 use Liip\ImagineBundle\DependencyInjection\Factory\Loader\FlysystemLoaderFactory;
@@ -150,6 +151,7 @@ public function testAddLoaders(): void
             StreamLoaderFactory::class,
             FileSystemLoaderFactory::class,
             FlysystemLoaderFactory::class,
+            AssetMapperLoaderFactory::class,
             ChainLoaderFactory::class,
         ], $loaders);
     }