Replace the fluent PHP config format by the array-shape one #21511

nicolas-grekas · 2025-10-17T17:10:02Z

Related to ~~symfony/symfony#62092~~ symfony/symfony#62129 and https://symfony.com/blog/new-in-symfony-7-4-deprecated-xml-configuration

The diff itself isn't really interesting. What's interesting is comparing yaml to php arrays.

This can give a nice overview of the new format.

nicolas-grekas · 2025-10-18T16:47:09Z

PR ready.
This took me quite some time to do manually, but with some LLM help, I shouldn't have made much mistakes.

javiereguiluz · 2025-10-20T06:21:45Z

Thanks for this! We should merge this soon to aovid merge conflicts with other PRs.

However, GitHub shows errors on these 5 files, so we should fix those:

logging/channels_handlers.rst
logging/monolog_console.rst
service_container/import.rst
configuration.rst
http_client.rst

nicolas-grekas · 2025-10-22T17:09:46Z

PR updated after symfony/symfony#62129

… to assist in writing and discovering app's configuration (nicolas-grekas) This PR was squashed before being merged into the 7.4 branch. Discussion ---------- [FrameworkBundle] Auto-generate `config/reference.php` to assist in writing and discovering app's configuration | Q | A | ------------- | --- | Branch? | 7.4 | Bug fix? | no | New feature? | yes | Deprecations? | no | Doc PR | symfony/symfony-docs#21511 | License | MIT This PR reverts #61490 and #61885, and builds on #61894. These reverts explain a big chunk of the attached patch. This adds a compiler pass that generates a `config/reference.php` file. This file contains two classes that define array-shapes for app's and routing configuration. Part of these shapes are auto-generated from the list of bundles found in `config/bundles.php`. The `config/reference.php` file should be loaded by a new line in the "autoload" entry of composer.json files: `"classmap": ["config/"]` - recipe update pending. This means that the file should be committed. This is on purpose: as the name suggests, this file is also a config reference for human readers. Having to commit the changes is also a nice way to convey config improvements to the community - at least for ppl that review their commits ;). It also solves a discovery problem that happens with phpstan/etc having a hard time to find the classes currently generated for config builders in the cache directory. With this PR, `config/services.php` could start as such: ```php <?php namespace Symfony\Component\DependencyInjection\Loader\Configurator; return App::config([ 'services' => [ 'App\\' => [ 'resource' => '../src/' ], ], ]); ``` and `config/routes.php` would start as: ```php <?php namespace Symfony\Component\Routing\Loader\Configurator; return Routes::config([ 'controllers' => [ 'resource' => 'attributes', 'type' => 'tagged_services', ] ]); ``` The generated shapes use advanced features that are not fully supported by phpstan / phpstorm. But the gap should be closed soon. PS: https://symfony.com/blog/new-in-symfony-7-4-deprecated-xml-configuration will need an update. Commits ------- 22349f5 [FrameworkBundle] Auto-generate `config/reference.php` to assist in writing and discovering app's configuration

nicolas-grekas · 2025-10-23T18:10:50Z

I replaced examples that used config/package/env/ pattern to when@env. This topic would deserves closer attention after merging. I think we can stop telling so much bout the subdir pattern.

translation.rst

GromNaN · 2025-10-23T18:29:35Z

testing.rst

-        twig:
-            strict_variables: true
+        # config/packages/twig.yaml
+        when@test:


Nice update 👍🏻
Consistent with the Twig recipe.

session.rst

service_container.rst

bundles/prepend_extension.rst

configuration/front_controllers_and_kernel.rst

configuration/micro_kernel_trait.rst

configuration/override_dir_structure.rst

configuration/secrets.rst

GromNaN · 2025-10-23T19:27:46Z

controller/error_pages.rst

+            return App::config([
                'content' => 'This is my custom problem normalizer.',
                'exception'=> [
                    'message' => $exception->getMessage(),
                    'code' => $exception->getStatusCode(),
                ],
-            ];
+            ]);


Not a config file.

Suggested change

return App::config([

'content' => 'This is my custom problem normalizer.',

'exception'=> [

'message' => $exception->getMessage(),

'code' => $exception->getStatusCode(),

],

];

]);

return [

'content' => 'This is my custom problem normalizer.',

'exception'=> [

'message' => $exception->getMessage(),

'code' => $exception->getStatusCode(),

],

];

doctrine/resolve_target_entity.rst

GromNaN

I stopped at "security/".

reference/configuration/doctrine.rst

reference/configuration/framework.rst

GromNaN · 2025-10-23T19:59:51Z

reference/configuration/framework.rst

+                'cache' => [
+                    'pools' => [
+                        'cache.mycache' => [
+                            'adapter' => 'cache.adapter.redis',


This is a service id, but we could update the config to accept a Reference: symfony/symfony#62142

Not convinced we should diverge from what's possible in yaml.

reference/configuration/framework.rst

GromNaN · 2025-10-23T20:25:56Z

reference/dic_tags.rst

+            'services' => [
+                AvatarPackage::class => [
+                    'tags' => [
+                        ['assets.package' => ['package' => 'avatars']],


Both syntaxes work. which one should be documented?

Suggested change

['assets.package' => ['package' => 'avatars']],

['name' => 'assets.package', 'package' => 'avatars'],

I documented only the first in the shape for two reasons:

array{name: string, ...<string, mixed>} isn't supported so this would break the type

only the first allows attributes with key name.

nicolas-grekas · 2025-10-24T11:05:01Z

Thanks @GromNaN, comments addressed.

javiereguiluz · 2025-10-27T14:56:00Z

Just asking: the "code blocks" check is reporting many issues (https://github.com/symfony/symfony-docs/actions/runs/18777842138/job/53576516241?pr=21511) but I don't know if they are legit or just false positives because the review tooling is not ready to review this new format properly?

nicolas-grekas requested a review from xabbuh as a code owner October 17, 2025 17:10

carsonbot added the Status: Needs Review label Oct 17, 2025

carsonbot added this to the 8.0 milestone Oct 17, 2025

carsonbot changed the title ~~Replace the fluent PHP config format by the array-shape one~~ Replace the fluent PHP config format by the array-shape one Oct 17, 2025

nicolas-grekas mentioned this pull request Oct 17, 2025

[Config][DependencyInjection] Deprecate the fluent PHP format for semantic configuration symfony/symfony#62092

Merged

nicolas-grekas force-pushed the php-array branch 4 times, most recently from dc1e644 to 730f41f Compare October 18, 2025 16:44

nicolas-grekas force-pushed the php-array branch 2 times, most recently from 097460b to 776698b Compare October 19, 2025 16:46

nicolas-grekas force-pushed the php-array branch 2 times, most recently from 5372241 to 106f154 Compare October 20, 2025 07:09

nicolas-grekas mentioned this pull request Oct 20, 2025

[Config][DependencyInjection] Deprecate the fluent PHP format for seman… #21515

Closed

nicolas-grekas force-pushed the php-array branch from 106f154 to f86a9b6 Compare October 22, 2025 17:08

nicolas-grekas mentioned this pull request Oct 22, 2025

[FrameworkBundle] Auto-generate config/reference.php to assist in writing and discovering app's configuration symfony/symfony#62129

Merged

nicolas-grekas force-pushed the php-array branch from f86a9b6 to 9fd693b Compare October 23, 2025 10:26

nicolas-grekas force-pushed the php-array branch 2 times, most recently from 2ae8fe4 to a042e8c Compare October 23, 2025 18:07

GromNaN reviewed Oct 23, 2025

View reviewed changes

translation.rst Show resolved Hide resolved

translation.rst Show resolved Hide resolved

nicolas-grekas force-pushed the php-array branch from a042e8c to 93757d2 Compare October 23, 2025 18:44

GromNaN reviewed Oct 23, 2025

View reviewed changes

Replace the fluent PHP config format by the array-shape one

aadb453

nicolas-grekas force-pushed the php-array branch from 93757d2 to aadb453 Compare October 24, 2025 11:04

	['assets.package' => ['package' => 'avatars']],
	['name' => 'assets.package', 'package' => 'avatars'],

Uh oh!

Uh oh!

Replace the fluent PHP config format by the array-shape one #21511

Are you sure you want to change the base?

Replace the fluent PHP config format by the array-shape one #21511

Conversation

nicolas-grekas commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nicolas-grekas commented Oct 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

javiereguiluz commented Oct 20, 2025

Uh oh!

nicolas-grekas commented Oct 22, 2025

Uh oh!

nicolas-grekas commented Oct 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

GromNaN Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

GromNaN Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

GromNaN left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

GromNaN Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

nicolas-grekas Oct 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

GromNaN Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

nicolas-grekas Oct 24, 2025

Choose a reason for hiding this comment

Uh oh!

nicolas-grekas commented Oct 24, 2025

Uh oh!

javiereguiluz commented Oct 27, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

nicolas-grekas commented Oct 17, 2025 •

edited

Loading

nicolas-grekas commented Oct 18, 2025 •

edited

Loading

nicolas-grekas commented Oct 23, 2025 •

edited

Loading

nicolas-grekas Oct 24, 2025 •

edited

Loading