feature #62092 [Config][DependencyInjection] Deprecate the fluent PHP format for semantic configuration (nicolas-grekas)

This PR was merged into the 7.4 branch.

Discussion
----------

[Config][DependencyInjection] Deprecate the fluent PHP format for semantic configuration

| Q             | A
| ------------- | ---
| Branch?       | 7.4
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Issues        | -
| License       | MIT

This PR deprecates the fluent PHP format for semantic configuration introduced in Symfony 5.4 by `@Nyholm` (see #40600).

It aims to replace it with the new array-based PHP config format (see #61490).

The fluent PHP config format was a great experiment:
- It helped us improve the Config component and the code generation of fluent config builders.
- It confirmed the community’s interest in PHP-based configuration.
- And it showed us its limits.

Those limits are structural. Writing fluent config is difficult and full of edge cases. Its rigidity comes from having to match one canonical interpretation of the semantic config tree. Automatic code generation can’t capture the custom logic that before-normalizers introduce, yet those normalizers are essential for flexibility and backward compatibility. This rigidity makes fluent config fragile. How do we deal with this fragility as config tree authors? At the moment, we don't care. Maybe this format is too niche for you to have experienced this issue, but we cannot guarantee that simple upgrades won't break your fluent PHP config.

The new array-based PHP format builds directly on the same code used for loading YAML configs.
That means:
- trivial conversion between YAML and PHP arrays,
- identical flexibility and behavior,
- and support for auto-completion and static analysis through generated array shapes.

The generated array shapes are rigid too, but that rigidity is non-breaking: even if your config no longer matches the canonical shape, your app keeps working. Static analyzers might warn you: that’s an invitation to update, not a failure.

I'm submitting this PR a bit l late for 7.4 but I think it's important to merge now. Deprecating the fluent PHP config format will:
- prevent new code from relying on a fragile approach,
- make room in the documentation for the array-based format,
- and consolidate Symfony’s configuration story around a robust PHP-based format.

Fluent PHP for semantic config served us well but it's time to retire it.

   ```diff
   -return function (AcmeConfig $config) {
   -    $config->color('red');
   -}
   +return new AcmeConfig([
   +    'color' => 'red',
   +]);
   ```

PS: there's another fluent config format for services and routes (see #23834 and #24180). This other format is handwritten. It doesn't have the issues listed above and it is *not* deprecated. It's actually the recommended way *for bundles* to declare their config (instead of XML, see #60568).

Commits
-------

332b4ac [Config][DependencyInjection] Deprecate the fluent PHP format for semantic configuration

Author: nicolas-grekas

UPGRADE-7.4.md

@@ -23,6 +23,7 @@ Config
 
  * Deprecate accessing the internal scope of the loader in PHP config files, use only its public API instead
  * Deprecate setting a default value to a node that is required, and vice versa
+ * Deprecate generating fluent methods in config builders
 
 Console
 -------
@@ -40,6 +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:
+   ```diff
+   -return function (AcmeConfig $config) {
+   -    $config->color('red');
+   -}
+   +return new AcmeConfig([
+   +    'color' => 'red',
+   +]);
+   ```
 
 DoctrineBridge
 --------------

src/Symfony/Component/Config/Builder/ClassBuilder.php

@@ -38,6 +38,7 @@ public function __construct(
         private string $namespace,
         string $name,
         private NodeInterface $node,
+        public readonly bool $isRoot = false,
     ) {
         $this->name = ucfirst($this->camelCase($name)).'Config';
     }
@@ -73,7 +74,7 @@ public function build(): string
             $use .= \sprintf('use %s;', $statement)."\n";
         }
 
-        $implements = [] === $this->implements ? '' : 'implements '.implode(', ', $this->implements);
+        $implements = $this->implements ? 'implements '.implode(', ', $this->implements) : '';
         $body = '';
         foreach ($this->properties as $property) {
             $body .= '    '.$property->getContent()."\n";

src/Symfony/Component/Config/Builder/ConfigBuilderGenerator.php

@@ -51,7 +51,7 @@ public function build(ConfigurationInterface $configuration): \Closure
         $this->classes = [];
 
         $rootNode = $configuration->getConfigTreeBuilder()->buildTree();
-        $rootClass = new ClassBuilder('Symfony\\Config', $rootNode->getName(), $rootNode);
+        $rootClass = new ClassBuilder('Symfony\\Config', $rootNode->getName(), $rootNode, true);
 
         $path = $this->getFullPath($rootClass);
         if (!is_file($path)) {
@@ -68,7 +68,7 @@ public function NAME(): string
             $this->writeClasses();
         }
 
-        return function () use ($path, $rootClass) {
+        return static function () use ($path, $rootClass) {
             require_once $path;
             $className = $rootClass->getFqcn();
 
@@ -94,6 +94,9 @@ private function writeClasses(): void
             if ($class->getProperties()) {
                 $class->addProperty('_usedProperties', null, '[]');
             }
+            if ($class->isRoot) {
+                $class->addProperty('_hasDeprecatedCalls', null, 'false');
+            }
             $this->buildSetExtraKey($class);
 
             file_put_contents($this->getFullPath($class), $class->build());
@@ -134,10 +137,13 @@ private function handleArrayNode(ArrayNode $node, ClassBuilder $class, string $n
         if ($acceptScalar) {
             $comment = \sprintf(" * @template TValue of %s\n * @param TValue \$value\n%s", $paramType, $comment);
             $comment .= \sprintf(' * @return %s|$this'."\n", $childClass->getFqcn());
-            $comment .= \sprintf(' * @psalm-return (TValue is array ? %s : static)'."\n ", $childClass->getFqcn());
+            $comment .= \sprintf(' * @psalm-return (TValue is array ? %s : static)'."\n", $childClass->getFqcn());
+        }
+        if ($class->isRoot) {
+            $comment .= " * @deprecated since Symfony 7.4\n";
         }
         if ('' !== $comment) {
-            $comment = "/**\n$comment*/\n";
+            $comment = "/**\n$comment */\n";
         }
 
         $property = $class->addProperty(
@@ -146,7 +152,7 @@ private function handleArrayNode(ArrayNode $node, ClassBuilder $class, string $n
         );
         $body = $acceptScalar ? '
 COMMENTpublic function NAME(PARAM_TYPE $value = []): CLASS|static
-{
+{DEPRECATED_BODY
     if (!\is_array($value)) {
         $this->_usedProperties[\'PROPERTY\'] = true;
         $this->PROPERTY = $value;
@@ -164,7 +170,7 @@ private function handleArrayNode(ArrayNode $node, ClassBuilder $class, string $n
     return $this->PROPERTY;
 }' : '
 COMMENTpublic function NAME(array $value = []): CLASS
-{
+{DEPRECATED_BODY
     if (null === $this->PROPERTY) {
         $this->_usedProperties[\'PROPERTY\'] = true;
         $this->PROPERTY = new CLASS($value);
@@ -176,6 +182,7 @@ private function handleArrayNode(ArrayNode $node, ClassBuilder $class, string $n
 }';
         $class->addUse(InvalidConfigurationException::class);
         $class->addMethod($node->getName(), $body, [
+            'DEPRECATED_BODY' => $class->isRoot ? "\n    \$this->_hasDeprecatedCalls = true;" : '',
             'COMMENT' => $comment,
             'PROPERTY' => $property->getName(),
             'CLASS' => $childClass->getFqcn(),
@@ -195,15 +202,17 @@ private function handleVariableNode(VariableNode $node, ClassBuilder $class): vo
 /**
 COMMENT *
  * @return $this
- */
+ *DEPRECATED_ANNOTATION/
 public function NAME(mixed $valueDEFAULT): static
-{
+{DEPRECATED_BODY
     $this->_usedProperties[\'PROPERTY\'] = true;
     $this->PROPERTY = $value;
 
     return $this;
 }';
         $class->addMethod($node->getName(), $body, [
+            'DEPRECATED_BODY' => $class->isRoot ? "\n    \$this->_hasDeprecatedCalls = true;" : '',
+            'DEPRECATED_ANNOTATION' => $class->isRoot ? " @deprecated since Symfony 7.4\n *" : '',
             'PROPERTY' => $property->getName(),
             'COMMENT' => $comment,
             'DEFAULT' => $node->hasDefaultValue() ? ' = '.var_export($node->getDefaultValue(), true) : '',
@@ -232,16 +241,18 @@ private function handlePrototypedArrayNode(PrototypedArrayNode $node, ClassBuild
  * @param ParamConfigurator|list<ParamConfigurator|PROTOTYPE_TYPE>EXTRA_TYPE $value
  *
  * @return $this
- */
+ *DEPRECATED_ANNOTATION/
 public function NAME(PARAM_TYPE $value): static
-{
+{DEPRECATED_BODY
     $this->_usedProperties[\'PROPERTY\'] = true;
     $this->PROPERTY = $value;
 
     return $this;
 }';
 
                 $class->addMethod($node->getName(), $body, [
+                    'DEPRECATED_BODY' => $class->isRoot ? "\n    \$this->_hasDeprecatedCalls = true;" : '',
+                    'DEPRECATED_ANNOTATION' => $class->isRoot ? " @deprecated since Symfony 7.4\n *" : '',
                     'PROPERTY' => $property->getName(),
                     'PROTOTYPE_TYPE' => implode('|', $prototypeParameterTypes),
                     'EXTRA_TYPE' => $nodeTypesWithoutArray ? '|'.implode('|', $nodeTypesWithoutArray) : '',
@@ -251,16 +262,18 @@ public function NAME(PARAM_TYPE $value): static
                 $body = '
 /**
  * @return $this
- */
+ *DEPRECATED_ANNOTATION/
 public function NAME(string $VAR, TYPE $VALUE): static
-{
+{DEPRECATED_BODY
     $this->_usedProperties[\'PROPERTY\'] = true;
     $this->PROPERTY[$VAR] = $VALUE;
 
     return $this;
 }';
 
                 $class->addMethod($methodName, $body, [
+                    'DEPRECATED_BODY' => $class->isRoot ? "\n    \$this->_hasDeprecatedCalls = true;" : '',
+                    'DEPRECATED_ANNOTATION' => $class->isRoot ? " @deprecated since Symfony 7.4\n *" : '',
                     'PROPERTY' => $property->getName(),
                     'TYPE' => ['mixed'] !== $prototypeParameterTypes ? 'ParamConfigurator|'.implode('|', $prototypeParameterTypes) : 'mixed',
                     'VAR' => '' === $key ? 'key' : $key,
@@ -290,16 +303,19 @@ public function NAME(string $VAR, TYPE $VALUE): static
         if ($acceptScalar) {
             $comment = \sprintf(" * @template TValue of %s\n * @param TValue \$value\n%s", $paramType, $comment);
             $comment .= \sprintf(' * @return %s|$this'."\n", $childClass->getFqcn());
-            $comment .= \sprintf(' * @psalm-return (TValue is array ? %s : static)'."\n ", $childClass->getFqcn());
+            $comment .= \sprintf(' * @psalm-return (TValue is array ? %s : static)'."\n", $childClass->getFqcn());
+        }
+        if ($class->isRoot) {
+            $comment .= " * @deprecated since Symfony 7.4\n";
         }
         if ('' !== $comment) {
-            $comment = "/**\n$comment*/\n";
+            $comment = "/**\n$comment */\n";
         }
 
         if ($noKey) {
             $body = $acceptScalar ? '
 COMMENTpublic function NAME(PARAM_TYPE $value = []): CLASS|static
-{
+{DEPRECATED_BODY
     $this->_usedProperties[\'PROPERTY\'] = true;
     if (!\is_array($value)) {
         $this->PROPERTY[] = $value;
@@ -310,12 +326,13 @@ public function NAME(string $VAR, TYPE $VALUE): static
     return $this->PROPERTY[] = new CLASS($value);
 }' : '
 COMMENTpublic function NAME(array $value = []): CLASS
-{
+{DEPRECATED_BODY
     $this->_usedProperties[\'PROPERTY\'] = true;
 
     return $this->PROPERTY[] = new CLASS($value);
 }';
             $class->addMethod($methodName, $body, [
+                'DEPRECATED_BODY' => $class->isRoot ? "\n    \$this->_hasDeprecatedCalls = true;" : '',
                 'COMMENT' => $comment,
                 'PROPERTY' => $property->getName(),
                 'CLASS' => $childClass->getFqcn(),
@@ -324,7 +341,7 @@ public function NAME(string $VAR, TYPE $VALUE): static
         } else {
             $body = $acceptScalar ? '
 COMMENTpublic function NAME(string $VAR, PARAM_TYPE $VALUE = []): CLASS|static
-{
+{DEPRECATED_BODY
     if (!\is_array($VALUE)) {
         $this->_usedProperties[\'PROPERTY\'] = true;
         $this->PROPERTY[$VAR] = $VALUE;
@@ -342,7 +359,7 @@ public function NAME(string $VAR, TYPE $VALUE): static
     return $this->PROPERTY[$VAR];
 }' : '
 COMMENTpublic function NAME(string $VAR, array $VALUE = []): CLASS
-{
+{DEPRECATED_BODY
     if (!isset($this->PROPERTY[$VAR])) {
         $this->_usedProperties[\'PROPERTY\'] = true;
         $this->PROPERTY[$VAR] = new CLASS($VALUE);
@@ -354,7 +371,9 @@ public function NAME(string $VAR, TYPE $VALUE): static
 }';
             $class->addUse(InvalidConfigurationException::class);
             $class->addMethod($methodName, str_replace('$value', '$VAR', $body), [
-                'COMMENT' => $comment, 'PROPERTY' => $property->getName(),
+                'DEPRECATED_BODY' => $class->isRoot ? "\n    \$this->_hasDeprecatedCalls = true;" : '',
+                'COMMENT' => $comment,
+                'PROPERTY' => $property->getName(),
                 'CLASS' => $childClass->getFqcn(),
                 'VAR' => '' === $key ? 'key' : $key,
                 'VALUE' => 'value' === $key ? 'data' : 'value',
@@ -374,16 +393,21 @@ private function handleScalarNode(ScalarNode $node, ClassBuilder $class): void
         $body = '
 /**
 COMMENT * @return $this
- */
+ *DEPRECATED_ANNOTATION/
 public function NAME($value): static
-{
+{DEPRECATED_BODY
     $this->_usedProperties[\'PROPERTY\'] = true;
     $this->PROPERTY = $value;
 
     return $this;
 }';
 
-        $class->addMethod($node->getName(), $body, ['PROPERTY' => $property->getName(), 'COMMENT' => $comment]);
+        $class->addMethod($node->getName(), $body, [
+            'DEPRECATED_BODY' => $class->isRoot ? "\n    \$this->_hasDeprecatedCalls = true;" : '',
+            'DEPRECATED_ANNOTATION' => $class->isRoot ? " @deprecated since Symfony 7.4\n *" : '',
+            'PROPERTY' => $property->getName(),
+            'COMMENT' => $comment,
+        ]);
     }
 
     private function getParameterTypes(NodeInterface $node): array
@@ -509,6 +533,13 @@ private function buildToArray(ClassBuilder $class): void
 
         $extraKeys = $class->shouldAllowExtraKeys() ? ' + $this->_extraKeys' : '';
 
+        if ($class->isRoot) {
+            $body .= "
+    if (\$this->_hasDeprecatedCalls) {
+        trigger_deprecation('symfony/config', '7.4', 'Calling any fluent method on \"%s\" is deprecated; pass the configuration to the constructor instead.', \$this::class);
+    }";
+        }
+
         $class->addMethod('toArray', '
 public function NAME(): array
 {
@@ -583,13 +614,16 @@ private function buildSetExtraKey(ClassBuilder $class): void
  * @param ParamConfigurator|mixed $value
  *
  * @return $this
- */
+ *DEPRECATED_ANNOTATION/
 public function NAME(string $key, mixed $value): static
-{
+{DEPRECATED_BODY
     $this->_extraKeys[$key] = $value;
 
     return $this;
-}');
+}', [
+            'DEPRECATED_BODY' => $class->isRoot ? "\n    \$this->_hasDeprecatedCalls = true;" : '',
+            'DEPRECATED_ANNOTATION' => $class->isRoot ? " @deprecated since Symfony 7.4\n *" : '',
+        ]);
     }
 
     private function getSubNamespace(ClassBuilder $rootClass): string

src/Symfony/Component/Config/CHANGELOG.md

@@ -11,6 +11,7 @@ CHANGELOG
  * Add array-shapes to generated config builders
  * Deprecate accessing the internal scope of the loader in PHP config files, use only its public API instead
  * Deprecate setting a default value to a node that is required, and vice versa
+ * Deprecate generating fluent methods in config builders
 
 7.3
 ---

src/Symfony/Component/Config/Tests/Builder/Fixtures/AddToList.config.php

@@ -11,27 +11,35 @@
 
 use Symfony\Config\AddToListConfig;
 
-return static function (AddToListConfig $config) {
-    $config->translator()->fallbacks(['sv', 'fr', 'es']);
-    $config->translator()->source('\\Acme\\Foo', 'yellow');
-    $config->translator()->source('\\Acme\\Bar', 'green');
-
-    $config->messenger([
+return new AddToListConfig([
+    'translator' => [
+        'fallbacks' => ['sv', 'fr', 'es'],
+        'sources' => [
+            '\\Acme\\Foo' => 'yellow',
+            '\\Acme\\Bar' => 'green',
+        ],
+    ],
+    'messenger' => [
         'routing' => [
             'Foo\\MyArrayMessage' => [
                 'senders' => ['workqueue'],
             ],
+            'Foo\\Message' => [
+                'senders' => ['workqueue'],
+            ],
+            'Foo\\DoubleMessage' => [
+                'senders' => ['sync', 'workqueue'],
+            ],
         ],
-    ]);
-    $config->messenger()
-        ->routing('Foo\\Message')->senders(['workqueue']);
-    $config->messenger()
-        ->routing('Foo\\DoubleMessage')->senders(['sync', 'workqueue']);
-
-    $config->messenger()->receiving()
-        ->color('blue')
-        ->priority(10);
-    $config->messenger()->receiving()
-        ->color('red')
-        ->priority(5);
-};
+        'receiving' => [
+            [
+                'color' => 'blue',
+                'priority' => 10,
+            ],
+            [
+                'color' => 'red',
+                'priority' => 5,
+            ],
+        ],
+    ],
+]);

src/Symfony/Component/Config/Tests/Builder/Fixtures/AddToList.legacy.php

@@ -0,0 +1,37 @@
+<?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.
+ */
+
+use Symfony\Config\AddToListConfig;
+
+return static function (AddToListConfig $config) {
+    $config->translator()->fallbacks(['sv', 'fr', 'es']);
+    $config->translator()->source('\\Acme\\Foo', 'yellow');
+    $config->translator()->source('\\Acme\\Bar', 'green');
+
+    $config->messenger([
+        'routing' => [
+            'Foo\\MyArrayMessage' => [
+                'senders' => ['workqueue'],
+            ],
+        ],
+    ]);
+    $config->messenger()
+        ->routing('Foo\\Message')->senders(['workqueue']);
+    $config->messenger()
+        ->routing('Foo\\DoubleMessage')->senders(['sync', 'workqueue']);
+
+    $config->messenger()->receiving()
+        ->color('blue')
+        ->priority(10);
+    $config->messenger()->receiving()
+        ->color('red')
+        ->priority(5);
+};