Rename compile_cache_dir to metadata_dir

symfony · smnandre · Aug 25, 2026 · Aug 25, 2026 · Aug 25, 2026 · Aug 26, 2026
commit d08af611ad461988587c414fa7ca649e5a94e39d
diff --git a/UPGRADE-8.2.md b/UPGRADE-8.2.md
@@ -62,7 +62,7 @@ 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.compile_cache_dir` config option. It currently
+ * 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:
@@ -71,10 +71,10 @@ FrameworkBundle
   framework:
       asset_mapper:
           # keep the current location
-           compile_cache_dir: '%kernel.project_dir%/public/assets'
+           metadata_dir: '%kernel.project_dir%/public/assets'

           # or adopt the 9.0 default now; make sure the build directory is deployed
-           compile_cache_dir: '%kernel.build_dir%/asset_mapper'
+           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,9 +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.compile_cache_dir` option to choose where `asset-map:compile` writes its metadata
+ * 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.compile_cache_dir`; it will default to `%kernel.build_dir%/asset_mapper` in 9.0
+ * 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,7 +1086,7 @@ 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('compile_cache_dir')
+                        ->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()

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

-        if (null === $compileCacheDir = $config['compile_cache_dir']) {
+        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.compile_cache_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');
+                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');
            }

-            $compileCacheDir = $publicAssetsDirectory;
+            $metadataDir = $publicAssetsDirectory;
        }

        $container->getDefinition('asset_mapper.compiled_asset_mapper_config_reader')
-            ->setArgument(0, $compileCacheDir);
+            ->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,7 +345,7 @@ public function testAssetMapperCanBeEnabled()
            'excluded_patterns' => [],
            'server' => true,
            'public_prefix' => '/assets/',
-            'compile_cache_dir' => null,
+            'metadata_dir' => null,
            'missing_import_mode' => 'warn',
            'extensions' => [],
            'importmap_path' => '%kernel.project_dir%/importmap.php',
@@ -1216,7 +1216,7 @@ protected static function getBundleDefaultConfig()
                'excluded_patterns' => [],
                'server' => true,
                'public_prefix' => '/assets/',
-                'compile_cache_dir' => null,
+                'metadata_dir' => null,
                'missing_import_mode' => 'warn',
                'extensions' => [],
                'importmap_path' => '%kernel.project_dir%/importmap.php',

diff --git a/...FrameworkBundle/Tests/DependencyInjection/Fixtures/php/asset_mapper_compile_cache_dir.php b/...FrameworkBundle/Tests/DependencyInjection/Fixtures/php/asset_mapper_compile_cache_dir.php
diff --git a/...kBundle/Tests/DependencyInjection/Fixtures/php/asset_mapper_default_compile_cache_dir.php b/...kBundle/Tests/DependencyInjection/Fixtures/php/asset_mapper_default_compile_cache_dir.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/...sset_mapper_default_compile_cache_dir.yml → ...yml/asset_mapper_default_metadata_dir.yml b/...sset_mapper_default_compile_cache_dir.yml → ...yml/asset_mapper_default_metadata_dir.yml
diff --git a/...es/yml/asset_mapper_compile_cache_dir.yml → ...ixtures/yml/asset_mapper_metadata_dir.yml b/...es/yml/asset_mapper_compile_cache_dir.yml → ...ixtures/yml/asset_mapper_metadata_dir.yml
@@ -1,5 +1,5 @@
 framework:
    asset_mapper:
        paths: ['assets/']
-        compile_cache_dir: '%kernel.build_dir%/asset_mapper'
+        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,7 +3523,7 @@ public function testAssetMapperDevServerPrefix(bool $server, ?string $expectedPr
                'asset_mapper' => [
                    'server' => $server,
                    'public_prefix' => '/assets_path/',
-                    'compile_cache_dir' => '%kernel.build_dir%/asset_mapper',
+                    'metadata_dir' => '%kernel.build_dir%/asset_mapper',
                    'paths' => ['assets/'],
                ],
            ]);
@@ -3561,9 +3561,9 @@ public function testAssetMapperImportmapEntries()
        $this->assertSame('my-polyfill', $container->getDefinition('asset_mapper.importmap.renderer')->getArgument(3));
    }

-    public function testAssetMapperCompileCacheDirIsConfigurable()
+    public function testAssetMapperMetadataDirIsConfigurable()
    {
-        $container = $this->createContainerFromFile('asset_mapper_compile_cache_dir');
+        $container = $this->createContainerFromFile('asset_mapper_metadata_dir');

        $this->assertSame(
            $container->getParameter('kernel.build_dir').'/asset_mapper',
@@ -3572,11 +3572,11 @@ public function testAssetMapperCompileCacheDirIsConfigurable()
    }

    #[IgnoreDeprecations]
-    public function testAssetMapperCompileCacheDirFallsBackToThePublicAssetsDirectory()
+    public function testAssetMapperMetadataDirFallsBackToThePublicAssetsDirectory()
    {
-        $this->expectUserDeprecationMessage('Since symfony/framework-bundle 8.2: Not setting the "framework.asset_mapper.compile_cache_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.');
+        $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_compile_cache_dir');
+        $container = $this->createContainerFromFile('asset_mapper_default_metadata_dir');

        $this->assertStringEndsWith(
            '/assets',

diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/Functional/app/BundlePaths/config.yml b/src/Symfony/Bundle/FrameworkBundle/Tests/Functional/app/BundlePaths/config.yml
@@ -6,7 +6,7 @@ framework:
    validation: true
    serializer: true
    asset_mapper:
-        compile_cache_dir: '%kernel.build_dir%/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
@@ -38,7 +38,7 @@ public function registerContainerConfiguration(LoaderInterface $loader): void
            $assetMapper = [
                'paths' => ['dir1', 'dir2', 'non_ascii', 'assets'],
                'public_prefix' => 'assets',
-                'compile_cache_dir' => '%kernel.project_dir%/public/assets',
+                'metadata_dir' => '%kernel.project_dir%/public/assets',
            ];

            if ('reachable_entries' === $this->getEnvironment()) {

diff --git a/src/Symfony/Component/AssetMapper/Tests/Fixtures/ImportMapTestAppKernel.php b/src/Symfony/Component/AssetMapper/Tests/Fixtures/ImportMapTestAppKernel.php
@@ -39,7 +39,7 @@ public function registerContainerConfiguration(LoaderInterface $loader): void
                'assets' => null,
                'asset_mapper' => [
                    'paths' => ['assets'],
-                    'compile_cache_dir' => '%kernel.project_dir%/public/assets',
+                    'metadata_dir' => '%kernel.project_dir%/public/assets',
                ],
                'test' => true,
            ]);