symfony · smnandre · Aug 25, 2026 · Aug 25, 2026 · Aug 25, 2026 · Aug 26, 2026
diff --git a/UPGRADE-8.2.md b/UPGRADE-8.2.md
@@ -62,6 +62,20 @@ FrameworkBundle
 * Deprecate the `framework.ide` config option, use the `SYMFONY_IDE` env var instead
 * BrowserKit assertions are no longer verbose by default. Failed response assertions no longer include the response body unless `setBrowserKitAssertionsAsVerbose(true)` is called or `verbose: true` is passed to the assertion.
 * Deprecate the `framework.fragments.hinclude_default_template` config option and the `fragment.renderer.hinclude.global_template` parameter; use the `esi` or `inline` fragment renderer, or [Symfony UX Turbo](https://ux.symfony.com/turbo), instead
+ * Deprecate not setting the `framework.asset_mapper.metadata_dir` config option. It currently
+   defaults to the public assets directory, which publishes `manifest.json`, `importmap.json` and
+   `entrypoint.*.json` over HTTP although they are read by PHP only. It will default to
+   `%kernel.build_dir%/asset_mapper` in 9.0. Set it explicitly to silence the deprecation:
+
+   ```yaml
+   framework:
+       asset_mapper:
+           # keep the current location
+           metadata_dir: '%kernel.project_dir%/public/assets'
+
+           # or adopt the 9.0 default now; make sure the build directory is deployed
+           metadata_dir: '%kernel.build_dir%/asset_mapper'
+   ```

 HttpClient
 ----------

diff --git a/src/Symfony/Bundle/FrameworkBundle/CHANGELOG.md b/src/Symfony/Bundle/FrameworkBundle/CHANGELOG.md
@@ -18,7 +18,9 @@ CHANGELOG
 * Add `framework.messenger.reject_redelivered_messages` to allow disabling the `RejectRedeliveredMessageMiddleware`
 * Add `uri_signer.expiration` option that allows configuring the default URI signer expiration
 * Add `--dispatchers` option to `debug:event-dispatcher` command
+ * Add `framework.asset_mapper.metadata_dir` option to choose where `asset-map:compile` writes its metadata
 * Deprecate the `framework.ide` config option, use the `SYMFONY_IDE` env var instead
+ * Deprecate not setting `framework.asset_mapper.metadata_dir`; it will default to `%kernel.build_dir%/asset_mapper` in 9.0
 * Allow prefixing entries with `!` in `framework.workflows.<name>.events_to_dispatch` to permanently disable an event; e.g. `events_to_dispatch: ['!workflow.announce']` fires every event except `workflow.announce`. The GuardEvent can never be disabled; `!workflow.guard` is rejected at config compile time. Mixing allow-list and block-list entries in the same list is rejected at config compile time too.
 * Add support for the HttpClient `max_connect_duration` option to the `http_client` configuration
 * Report `.env` variables that the container never uses in `debug:container --env-vars`

diff --git a/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/Configuration.php b/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/Configuration.php
@@ -1086,6 +1086,10 @@ private function addAssetMapperSection(ArrayNodeDefinition $rootNode, callable $
                            ->info('The public path where the assets will be written to (and served from when "server" is true).')
                            ->defaultValue('/assets/')
                        ->end()
+                        ->scalarNode('metadata_dir')
+                            ->info('The directory where "asset-map:compile" writes manifest.json, importmap.json and entrypoint.*.json. These files are read by PHP only, never fetched by the browser. Defaults to the public assets directory; will default to "%kernel.build_dir%/asset_mapper" in 9.0.')
+                            ->defaultNull()
+                        ->end()
                        ->enumNode('missing_import_mode')
                            ->values(['strict', 'warn', 'ignore'])
                            ->info('Behavior if an asset cannot be found when imported from JavaScript or CSS files - e.g. "import \'./non-existent.js\'". "strict" means an exception is thrown, "warn" means a warning is logged, "ignore" means the import is left as-is.')

diff --git a/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/FrameworkExtension.php b/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/FrameworkExtension.php
@@ -1501,8 +1501,18 @@ private function registerAssetMapperConfiguration(array $config, ContainerBuilde
            ->setArgument(0, $publicDirectory)
        ;

+        if (null === $metadataDir = $config['metadata_dir']) {
+            // Only nag applications that actually map assets: with no path declared, nothing is
+            // ever compiled, so there is no metadata to place and nothing to decide.
+            if ($paths) {
+                trigger_deprecation('symfony/framework-bundle', '8.2', 'Not setting the "framework.asset_mapper.metadata_dir" configuration option is deprecated. Set it explicitly: it currently defaults to the public assets directory, and will default to "%s" in 9.0.', '%kernel.build_dir%/asset_mapper');
+            }
+
+            $metadataDir = $publicAssetsDirectory;
+        }
+
        $container->getDefinition('asset_mapper.compiled_asset_mapper_config_reader')
-            ->setArgument(0, $publicAssetsDirectory);
+            ->setArgument(0, $metadataDir);

        if (!$config['server']) {
            $container->removeDefinition('asset_mapper.dev_server_subscriber');

diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/DependencyInjection/ConfigurationTest.php b/src/Symfony/Bundle/FrameworkBundle/Tests/DependencyInjection/ConfigurationTest.php
@@ -345,6 +345,7 @@ public function testAssetMapperCanBeEnabled()
            'excluded_patterns' => [],
            'server' => true,
            'public_prefix' => '/assets/',
+            'metadata_dir' => null,
            'missing_import_mode' => 'warn',
            'extensions' => [],
            'importmap_path' => '%kernel.project_dir%/importmap.php',
@@ -1215,6 +1216,7 @@ protected static function getBundleDefaultConfig()
                'excluded_patterns' => [],
                'server' => true,
                'public_prefix' => '/assets/',
+                'metadata_dir' => null,
                'missing_import_mode' => 'warn',
                'extensions' => [],
                'importmap_path' => '%kernel.project_dir%/importmap.php',

diff --git a/...meworkBundle/Tests/DependencyInjection/Fixtures/php/asset_mapper_default_metadata_dir.php b/...meworkBundle/Tests/DependencyInjection/Fixtures/php/asset_mapper_default_metadata_dir.php
@@ -0,0 +1,17 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+$container->loadFromExtension('framework', [
+    'asset_mapper' => [
+        'paths' => ['assets/'],
+    ],
+    'assets' => false,
+]);
diff --git a/...ndle/FrameworkBundle/Tests/DependencyInjection/Fixtures/php/asset_mapper_metadata_dir.php b/...ndle/FrameworkBundle/Tests/DependencyInjection/Fixtures/php/asset_mapper_metadata_dir.php
@@ -0,0 +1,18 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+$container->loadFromExtension('framework', [
+    'asset_mapper' => [
+        'paths' => ['assets/'],
+        'metadata_dir' => '%kernel.build_dir%/asset_mapper',
+    ],
+    'assets' => false,
+]);
diff --git a/...meworkBundle/Tests/DependencyInjection/Fixtures/yml/asset_mapper_default_metadata_dir.yml b/...meworkBundle/Tests/DependencyInjection/Fixtures/yml/asset_mapper_default_metadata_dir.yml
@@ -0,0 +1,4 @@
+framework:
+    asset_mapper:
+        paths: ['assets/']
+    assets: false
diff --git a/...ndle/FrameworkBundle/Tests/DependencyInjection/Fixtures/yml/asset_mapper_metadata_dir.yml b/...ndle/FrameworkBundle/Tests/DependencyInjection/Fixtures/yml/asset_mapper_metadata_dir.yml
@@ -0,0 +1,5 @@
+framework:
+    asset_mapper:
+        paths: ['assets/']
+        metadata_dir: '%kernel.build_dir%/asset_mapper'
+    assets: false
diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/DependencyInjection/FrameworkExtensionTestCase.php b/src/Symfony/Bundle/FrameworkBundle/Tests/DependencyInjection/FrameworkExtensionTestCase.php
@@ -3523,6 +3523,7 @@ public function testAssetMapperDevServerPrefix(bool $server, ?string $expectedPr
                'asset_mapper' => [
                    'server' => $server,
                    'public_prefix' => '/assets_path/',
+                    'metadata_dir' => '%kernel.build_dir%/asset_mapper',
                    'paths' => ['assets/'],
                ],
            ]);
@@ -3560,6 +3561,29 @@ public function testAssetMapperImportmapEntries()
        $this->assertSame('my-polyfill', $container->getDefinition('asset_mapper.importmap.renderer')->getArgument(3));
    }

+    public function testAssetMapperMetadataDirIsConfigurable()
+    {
+        $container = $this->createContainerFromFile('asset_mapper_metadata_dir');
+
+        $this->assertSame(
+            $container->getParameter('kernel.build_dir').'/asset_mapper',
+            $container->getDefinition('asset_mapper.compiled_asset_mapper_config_reader')->getArgument(0),
+        );
+    }
+
+    #[IgnoreDeprecations]
+    public function testAssetMapperMetadataDirFallsBackToThePublicAssetsDirectory()
+    {
+        $this->expectUserDeprecationMessage('Since symfony/framework-bundle 8.2: Not setting the "framework.asset_mapper.metadata_dir" configuration option is deprecated. Set it explicitly: it currently defaults to the public assets directory, and will default to "%kernel.build_dir%/asset_mapper" in 9.0.');
+
+        $container = $this->createContainerFromFile('asset_mapper_default_metadata_dir');
+
+        $this->assertStringEndsWith(
+            '/assets',
+            $container->getDefinition('asset_mapper.compiled_asset_mapper_config_reader')->getArgument(0),
+        );
+    }
+
    public function testDefaultLock()
    {
        $container = $this->createContainerFromFile('lock');

diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/Functional/app/BundlePaths/config.yml b/src/Symfony/Bundle/FrameworkBundle/Tests/Functional/app/BundlePaths/config.yml
@@ -5,6 +5,8 @@ framework:
    translator: true
    validation: true
    serializer: true
+    asset_mapper:
+        metadata_dir: '%kernel.build_dir%/asset_mapper'

 twig:
    strict_variables: '%kernel.debug%'

diff --git a/src/Symfony/Component/AssetMapper/Tests/Fixtures/AssetMapperTestAppKernel.php b/src/Symfony/Component/AssetMapper/Tests/Fixtures/AssetMapperTestAppKernel.php
@@ -40,6 +40,10 @@ public function registerContainerConfiguration(LoaderInterface $loader): void
                'public_prefix' => 'assets',
            ];

+            if (Kernel::VERSION_ID >= 80200) {
+                $assetMapper['metadata_dir'] = '%kernel.project_dir%/public/assets';
+            }
+
            if ('reachable_entries' === $this->getEnvironment()) {
                $assetMapper['importmap_entries'] = 'reachable';
            }

diff --git a/src/Symfony/Component/AssetMapper/Tests/Fixtures/ImportMapTestAppKernel.php b/src/Symfony/Component/AssetMapper/Tests/Fixtures/ImportMapTestAppKernel.php
@@ -34,12 +34,16 @@ public function getProjectDir(): string
    public function registerContainerConfiguration(LoaderInterface $loader): void
    {
        $loader->load(static function (ContainerBuilder $container) {
+            $assetMapperConfig = ['paths' => ['assets']];
+
+            if (Kernel::VERSION_ID >= 80200) {
+                $assetMapperConfig['metadata_dir'] = '%kernel.project_dir%/public/assets';
+            }
+
            $container->loadFromExtension('framework', [
                'http_client' => true,
                'assets' => null,
-                'asset_mapper' => [
-                    'paths' => ['assets'],
-                ],
+                'asset_mapper' => $assetMapperConfig,
                'test' => true,
            ]);
        });