PHP config builder is using "var/", magic and is preferred over arrays in documentation

[raitocz]

I saw that there was an already merged PR symfony/symfony#40600 which enables config builders for PHP configs.

So instead of writting arrays:

// config/packages/security.php
use App\Entity\User;

$container->loadFromExtension('security', [
    // ...

    'providers' => [
        // used to reload user from session & other features (e.g. switch_user)
        'app_user_provider' => [
            'entity' => [
                'class' => User::class,
                'property' => 'email',
            ],
        ],
    ],
]);

you can use:

// config/packages/security.php
use App\Entity\User;
use Symfony\Config\SecurityConfig;

return static function (SecurityConfig $security): void {
    // ...

    $security->provider('app_user_provider')
        ->entity()
            ->class(User::class)
            ->property('email')
    ;
};

I know that it is mentioned in https://symfony.com/doc/current/configuration.html#using-php-configbuilders as note:

In order to get ConfigBuilders autocompletion in your IDE/editor, make sure to not exclude the directory where these classes are generated (by default, in var/cache/dev/Symfony/Config/).

but I would rather prefer that there are 2 PHP configuration options mentioned trough documentation:

• PHP trough ConfigBuilder
• PHP trough Array

Reason is: I build many applications in containers and using builders means that the var directory is not warmed-up, thus IDE is missing the classes.

... and also I personally think that having some magic classes appearing in var/ directory is bad practice. But that is just my opinion to discuss.

I also found it very confusing how it works and while having most of my configs as PHP arrays I struggle in conversion from "symfony doc using builders" to "configs in arrays" as there is no actual reference.

The fact that most of the documentation when describing the config reference uses mashup of both confirms that it is not done properly:

Security - Firewalls (PHP tab using ConfigBuilder): https://symfony.com/doc/current/reference/configuration/security.html#firewalls
Security - Log out (PHP tab using Arrays): https://symfony.com/doc/current/reference/configuration/security.html#firewalls

[alexandre-daubois]

Having such difference in the doc is not a matter of this done properly or not, but just something we may have forgot to update. ConfigBuilder offers strong typing compared to arrays. Regarding your specific problem of the cache warmup, I'm sorry but I don't have a solution 😕

I'm afraid documenting both PHP ConfigBuilder and PHP array would be to much maintenance. I'll let the doc team answer to this 👍

Anyway, I'll take care of converting those array configs to ConfigBuilder one, as I think they should already by migrated

[wouterj]

I agree. We should be consistent in the docs, but we seem to have missed some examples.

But other than that, the PHP config builders are the new recommended approach if you want a PHP based config. Strong typing, autocompletion and compatibility with ecosystem tools like static analyzers or code style fixers are advantages of the config builders that we can't support in the array-based syntax.

As always, Symfony gives the flexibility to choose your preferred syntax. So you can keep using the PHP array syntax in your applications. However, it will be confusing for newcomers - the main target of the Symfony docs - to show 2 PHP syntax (when should you use either one?) and increases the maintenance costs.
If you stick to array based config, you can use the Yaml syntax as an example: PHP arrays are 99% equal to Yaml if you convert Yaml syntax to PHP syntax.

[raitocz]

@alexandre-daubois @wouterj Yes, I understand all the benefits of builders and I'm all pro, I was all excited to have them! It's the ultimate reason to write all configs in PHP instead of YAML.

But the requirement of linking the 'var/' content which is not warmed-up ready on rebuilt containers is huge drawback :/