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.

GromNaN · 2025-10-23T18:34:24Z

session.rst

+        return App::config([
+            'services' => [
+                // ...
+                'Symfony\Component\HttpFoundation\Session\Storage\Handler\RedisSessionHandler' => [


There is a use statement for this class:

Suggested change

'Symfony\Component\HttpFoundation\Session\Storage\Handler\RedisSessionHandler' => [

RedisSessionHandler::class => [

GromNaN · 2025-10-23T18:34:34Z

session.rst

+                        // ['prefix' => 'my_prefix', 'ttl' => 600],
+                    ],
+                ],
+                'Redis' => [


Suggested change

'Redis' => [

\Redis::class => [

GromNaN · 2025-10-23T18:36:58Z

service_container.rst

+                'services' => [
+                    '_defaults' => [
+                        'autowire' => true,      // Automatically injects dependencies in your services.
+                        'autoconfigure' => true, // Automatically registers your services as commands, event subscribers, etc.


That's the default values for App::config(), you may comment them here?

GromNaN · 2025-10-23T18:47:37Z

bundles/prepend_extension.rst


-        return static function (ContainerConfigurator $container): void {
-            $container->extension('acme_something', [
-                // ...


Either we keep these ellipses in all formats, or we remove them. Let's be consistent.

let's remove them from this example, that better matches the prepend example before this configuration block.

GromNaN · 2025-10-23T19:23:11Z

configuration/front_controllers_and_kernel.rst

-            $twig->debug('%kernel.debug%');
-        };
+        return App::config([
+            'twig' => $1,


Parameter missing here.
You could use the param function.

Suggested change

'twig' => $1,

'twig' => param('kernel.debug'),

GromNaN · 2025-10-23T19:23:52Z

configuration/micro_kernel_trait.rst

+            return App::config([
                KernelEvents::EXCEPTION => 'onKernelException',
-            ];
+            ]);


This is not a config file.

Suggested change

return App::config([

KernelEvents::EXCEPTION => 'onKernelException',

];

]);

return [

KernelEvents::EXCEPTION => 'onKernelException',

];

GromNaN · 2025-10-23T19:24:42Z

configuration/override_dir_structure.rst

-            $twig->defaultPath('%kernel.project_dir%/resources/views');
-        };
+        return App::config([
+            'twig' => $1,


Suggested change

'twig' => $1,

'twig' => '%kernel.project_dir%/resources/views',

GromNaN · 2025-10-23T19:25:21Z

configuration/secrets.rst

-            ;
-        };
+        return App::config([
+            'doctrine' => $1,


Suggested change

'doctrine' => $1,

'doctrine' => env('DATABASE_PASSWORD'),

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->getMes 67DE sage(),

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

],

];

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

doctrine/resolve_target_entity.rst

-        };
+        return App::config([
+            'doctrine' => [
+            'orm' => [


Indentation

Suggested change

'orm' => [

'orm' => [

GromNaN

I stopped at "security/".

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

reference/configuration/doctrine.rst

+            'services' => [
+                AutoCommitListener::class => [
+                    'tags' => [
+                        ['doctrine.event_listener' => ['event' => Events::onMigrationsMigrated]],


If we copy the Yaml format, it should be like this: what is correct?

Suggested change

['doctrine.event_listener' => ['event' => Events::onMigrationsMigrated]],

[

'name' => 'doctrine.event_listener',

'event' => Events::onMigrationsMigrated

],

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

reference/configuration/doctrine.rst

+        # config/packages/doctrine.yaml
        doctrine:
            dbal:
                url: '%env(DATABASE_URL)%'


To be consistent with the PHP example:

Suggested change

url: '%env(DATABASE_URL)%'

url: '%env(resolve:DATABASE_URL)%'

GromNaN · 2025-10-23T19:53:58Z

reference/configuration/framework.rst

+                'assets' => [
+                    'packages' => [
+                        'avatars' => [
+                            'base_urls' => ['http://static_cdn.example.com/avatars'],


Suggested change

'base_urls' => ['http://static_cdn.example.com/avatars'],

'base_urls' => ['https://static_cdn.example.com/avatars'],

GromNaN · 2025-10-23T19:54:16Z

reference/configuration/framework.rst

            assets:
                packages:
                    avatars:
                        base_urls: 'http://static_cdn.example.com/avatars'


Let's apply security best practices.

Suggested change

base_urls: 'https://static_cdn.example.com/avatars'

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

GromNaN · 2025-10-23T20:15:42Z

reference/configuration/framework.rst

+                        'headers' => [
+                            'X-Powered-By' => 'ACME App',
+                        ],


In the Yaml example, this is inlined.

Suggested change

'headers' => [

'X-Powered-By' => 'ACME App',

],

'headers' => ['X-Powered-By' => 'ACME App'],

Just to highlight the difference, you can discard the suggestion.

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'],

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

Open

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 8000 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

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

93757d2

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

GromNaN reviewed Oct 23, 2025

View reviewed changes 8000

GromNaN reviewed Oct 23, 2025

View reviewed changes

	'Symfony\Component\HttpFoundation\Session\Storage\Handler\RedisSessionHandler' => [
	RedisSessionHandler::class => [

	'twig' => $1,
	'twig' => '%kernel.project_dir%/resources/views',

	url: '%env(DATABASE_URL)%'
	url: '%env(resolve:DATABASE_URL)%'

	'base_urls' => ['http://static_cdn.example.com/avatars'],
	'base_urls' => ['https://static_cdn.example.com/avatars'],

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

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

Uh oh!

Conversation

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants