symfony · nicolas-grekas · Oct 23, 2025 · Oct 21, 2025 · stof · Oct 22, 2025
diff --git a/UPGRADE-7.4.md b/UPGRADE-7.4.md
@@ -41,13 +41,15 @@ DependencyInjection
  * Deprecate `ExtensionInterface::getXsdValidationBasePath()` and `getNamespace()`;
    bundles that need to support older versions of Symfony can keep the methods
    but need to add the `@deprecated` annotation on them
- * Deprecate the fluent PHP format for semantic configuration, instantiate builders inline with the config array as argument and return them instead:
+ * Deprecate the fluent PHP format for semantic configuration, use `$container->extension()` or return an array instead
    ```diff
    -return function (AcmeConfig $config) {
    -    $config->color('red');
    -}
-   +return new AcmeConfig([
-   +    'color' => 'red',
+   +return App::config([
+   +    'acme' => [
+   +        'color' => 'red',
+   +    ],
    +]);
    ```
 

diff --git a/composer.json b/composer.json
@@ -197,10 +197,6 @@
             "Symfony\\Bridge\\Twig\\": "src/Symfony/Bridge/Twig/",
             "Symfony\\Bundle\\": "src/Symfony/Bundle/",
             "Symfony\\Component\\": "src/Symfony/Component/",
-            "Symfony\\Config\\": [
-                "src/Symfony/Component/DependencyInjection/Loader/Config/",
-                "src/Symfony/Component/Routing/Loader/Config/"
-            ],
             "Symfony\\Runtime\\Symfony\\Component\\": "src/Symfony/Component/Runtime/Internal/"
         },
         "files": [

diff --git a/src/Symfony/Bundle/FrameworkBundle/CHANGELOG.md b/src/Symfony/Bundle/FrameworkBundle/CHANGELOG.md
@@ -4,6 +4,7 @@ CHANGELOG
 7.4
 ---
 
+ * Auto-generate `config/reference.php` to assist in writing and discovering app's configuration
  * Auto-register routes from attributes found on controller services
  * Add `ControllerHelper`; the helpers from AbstractController as a standalone service
  * Allow using their name without added suffix when using `#[Target]` for custom services

diff --git a/...ymfony/Bundle/FrameworkBundle/DependencyInjection/Compiler/PhpConfigReferenceDumpPass.php b/...ymfony/Bundle/FrameworkBundle/DependencyInjection/Compiler/PhpConfigReferenceDumpPass.php
@@ -0,0 +1,192 @@
+<?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.
+ */
+
+namespace Symfony\Bundle\FrameworkBundle\DependencyInjection\Compiler;
+
+use Symfony\Component\Config\Definition\ArrayShapeGenerator;
+use Symfony\Component\Config\Definition\ConfigurationInterface;
+use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\DependencyInjection\Extension\ConfigurationExtensionInterface;
+use Symfony\Component\DependencyInjection\Extension\ExtensionInterface;
+use Symfony\Component\DependencyInjection\Loader\Configurator\AppReference;
+use Symfony\Component\Routing\Loader\Configurator\RoutesReference;
+
+/**
+ * @internal
+ */
+class PhpConfigReferenceDumpPass implements CompilerPassInterface
+{
+    private const REFERENCE_TEMPLATE = <<<'PHP'
+        <?php
+
+        // This file is auto-generated and is for apps only. Bundles SHOULD NOT rely on its content.
+
+        namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
+        {APP_TYPES}
+        final class App extends AppReference
+        {
+            {APP_PARAM}
+            public static function config(array $config): array
+            {
+                return parent::config($config);
+            }
+        }
+
+        namespace Symfony\Component\Routing\Loader\Configurator;
+
+        {ROUTES_TYPES}
+        final class Routes extends RoutesReference
+        {
+            {ROUTES_PARAM}
+            public static function config(array $config): array
+            {
+                return parent::config($config);
+            }
+        }
+
+        PHP;
+
+    private const WHEN_ENV_APP_TEMPLATE = <<<'PHPDOC'
+
+             *     "when@{ENV}"?: array{
+             *         imports?: ImportsConfig,
+             *         parameters?: ParametersConfig,
+             *         services?: ServicesConfig,{SHAPE}
+             *     },
+        PHPDOC;
+
+    private const ROUTES_TYPES_TEMPLATE = <<<'PHPDOC'
+
+         * @psalm-type RoutesConfig = array{{SHAPE}
+         *     ...<string, RouteConfig|ImportConfig|AliasConfig>
+         * }
+         */
+        PHPDOC;
+
+    private const WHEN_ENV_ROUTES_TEMPLATE = <<<'PHPDOC'
+
+         *     "when@{ENV}"?: array<string, RouteConfig|ImportConfig|AliasConfig>,
+        PHPDOC;
+
+    public function __construct(
+        private string $referenceFile,
+        private array $bundlesDefinition,
+    ) {
+    }
+
+    public function process(ContainerBuilder $container): void
+    {
+        $knownEnvs = $container->hasParameter('.container.known_envs') ? $container->getParameter('.container.known_envs') : [$container->getParameter('kernel.environment')];
+        $knownEnvs = array_unique($knownEnvs);
+        sort($knownEnvs);
+        $extensionsPerEnv = [];
+        $appTypes = '';
+
+        $anyEnvExtensions = [];
+        foreach ($this->bundlesDefinition as $bundle => $envs) {
+            if (!$extension = (new $bundle())->getContainerExtension()) {
+                continue;
+            }
+            if (!$configuration = $this->getConfiguration($extension, $container)) {
+                continue;
+            }
+            $anyEnvExtensions[$bundle] = $extension;
+            $type = $this->camelCase($extension->getAlias()).'Config';
+            $appTypes .= \sprintf("\n * @psalm-type %s = %s", $type, ArrayShapeGenerator::generate($configuration->getConfigTreeBuilder()->buildTree()));
+
+            foreach ($knownEnvs as $env) {
+                if ($envs[$env] ?? $envs['all'] ?? false) {
+                    $extensionsPerEnv[$env][] = $extension;
+                } else {
+                    unset($anyEnvExtensions[$bundle]);
+                }
+            }
+        }
+        krsort($extensionsPerEnv);
+
+        $r = new \ReflectionClass(AppReference::class);
+
+        if (false === $i = strpos($phpdoc = $r->getDocComment(), "\n */")) {
+            throw new \LogicException(\sprintf('Cannot insert config shape in "%s".', AppReference::class));
+        }
+        $appTypes = substr_replace($phpdoc, $appTypes, $i, 0);
+
+        if (false === $i = strpos($phpdoc = $r->getMethod('config')->getDocComment(), "\n     *     ...<string, ExtensionType|array{")) {
+            throw new \LogicException(\sprintf('Cannot insert config shape in "%s".', AppReference::class));
+        }
+        $appParam = substr_replace($phpdoc, $this->getShapeForExtensions($anyEnvExtensions, $container), $i, 0);
+        $i += \strlen($appParam) - \strlen($phpdoc);
+
+        foreach ($extensionsPerEnv as $env => $extensions) {
+            $appParam = substr_replace($appParam, strtr(self::WHEN_ENV_APP_TEMPLATE, [
+                '{ENV}' => $env,
+                '{SHAPE}' => $this->getShapeForExtensions($extensions, $container, '    '),
+            ]), $i, 0);
+        }
+
+        $r = new \ReflectionClass(RoutesReference::class);
+
+        if (false === $i = strpos($phpdoc = $r->getDocComment(), "\n * @psalm-type RoutesConfig = ")) {
+            throw new \LogicException(\sprintf('Cannot insert config shape in "%s".', RoutesReference::class));
+        }
+        $routesTypes = '';
+        foreach ($knownEnvs as $env) {
+            $routesTypes .= strtr(self::WHEN_ENV_ROUTES_TEMPLATE, ['{ENV}' => $env]);
+        }
+        if ('' !== $routesTypes) {
+            $routesTypes = strtr(self::ROUTES_TYPES_TEMPLATE, ['{SHAPE}' => $routesTypes]);
+            $routesTypes = substr_replace($phpdoc, $routesTypes, $i);
+        }
+
+        $configReference = strtr(self::REFERENCE_TEMPLATE, [
+            '{APP_TYPES}' => $appTypes,
+            '{APP_PARAM}' => $appParam,
+            '{ROUTES_TYPES}' => $routesTypes,
+            '{ROUTES_PARAM}' => $r->getMethod('config')->getDocComment(),
+        ]);
+
+        $dir = \dirname($this->referenceFile);
+        if (is_dir($dir) && is_writable($dir) && (!is_file($this->referenceFile) || file_get_contents($this->referenceFile) !== $configReference)) {
+            file_put_contents($this->referenceFile, $configReference);
+        }
+    }
+
+    private function camelCase(string $input): string
+    {
+        $output = ucfirst(str_replace(' ', '', ucwords(str_replace('_', ' ', $input))));
+
+        return preg_replace('#\W#', '', $output);
+    }
+
+    private function getConfiguration(ExtensionInterface $extension, ContainerBuilder $container): ?ConfigurationInterface
+    {
+        return match (true) {
+            $extension instanceof ConfigurationInterface => $extension,
+            $extension instanceof ConfigurationExtensionInterface => $extension->getConfiguration([], $container),
+            default => null,
+        };
+    }
+
+    private function getShapeForExtensions(array $extensions, ContainerBuilder $container, string $indent = ''): string
+    {
+        $shape = '';
+        foreach ($extensions as $extension) {
+            if ($this->getConfiguration($extension, $container)) {
+                $type = $this->camelCase($extension->getAlias()).'Config';
+                $shape .= \sprintf("\n     *     %s%s?: %s,", $indent, $extension->getAlias(), $type);
+            }
+        }
+
+        return $shape;
+    }
+}
diff --git a/src/Symfony/Bundle/FrameworkBundle/FrameworkBundle.php b/src/Symfony/Bundle/FrameworkBundle/FrameworkBundle.php
@@ -16,6 +16,7 @@
 use Symfony\Bundle\FrameworkBundle\DependencyInjection\Compiler\AssetsContextPass;
 use Symfony\Bundle\FrameworkBundle\DependencyInjection\Compiler\ContainerBuilderDebugDumpPass;
 use Symfony\Bundle\FrameworkBundle\DependencyInjection\Compiler\ErrorLoggerCompilerPass;
+use Symfony\Bundle\FrameworkBundle\DependencyInjection\Compiler\PhpConfigReferenceDumpPass;
 use Symfony\Bundle\FrameworkBundle\DependencyInjection\Compiler\ProfilerPass;
 use Symfony\Bundle\FrameworkBundle\DependencyInjection\Compiler\RemoveUnusedSessionMarshallingHandlerPass;
 use Symfony\Bundle\FrameworkBundle\DependencyInjection\Compiler\TestServiceContainerRealRefPass;
@@ -148,7 +149,10 @@ public function build(ContainerBuilder $container): void
             ]);
         }
 
-        $container->addCompilerPass(new AssetsContextPass(), PassConfig::TYPE_BEFORE_OPTIMIZATION);
+        if ($container->hasParameter('.kernel.config_dir') && $container->hasParameter('.kernel.bundles_definition')) {
+            $container->addCompilerPass(new PhpConfigReferenceDumpPass($container->getParameter('.kernel.config_dir').'/reference.php', $container->getParameter('.kernel.bundles_definition')));
+        }
+        $container->addCompilerPass(new AssetsContextPass());
         $container->addCompilerPass(new LoggerPass(), PassConfig::TYPE_BEFORE_OPTIMIZATION, -32);
         $container->addCompilerPass(new RegisterControllerArgumentLocatorsPass());
         $container->addCompilerPass(new RemoveEmptyControllerArgumentLocatorsPass(), PassConfig::TYPE_BEFORE_REMOVING);

diff --git a/src/Symfony/Bundle/FrameworkBundle/Kernel/MicroKernelTrait.php b/src/Symfony/Bundle/FrameworkBundle/Kernel/MicroKernelTrait.php
@@ -230,4 +230,27 @@ public function loadRoutes(LoaderInterface $loader): RouteCollection
 
         return $collection;
     }
+
+    /**
+     * Returns the kernel parameters.
+     *
+     * @return array<string, array|bool|string|int|float|\UnitEnum|null>
+     */
+    protected function getKernelParameters(): array
+    {
+        $parameters = parent::getKernelParameters();
+        $bundlesPath = $this->getBundlesPath();
+        $bundlesDefinition = !is_file($bundlesPath) ? [FrameworkBundle::class => ['all' => true]] : require $bundlesPath;
+        $knownEnvs = [$this->environment => true];
+
+        foreach ($bundlesDefinition as $envs) {
+            $knownEnvs += $envs;
+        }
+        unset($knownEnvs['all']);
+        $parameters['.container.known_envs'] = array_keys($knownEnvs);
+        $parameters['.kernel.config_dir'] = $this->getConfigDir();
+        $parameters['.kernel.bundles_definition'] = $bundlesDefinition;
+
+        return $parameters;
+    }
 }