feature #43701 [HttpKernel] Simplifying Bundle/Extension config definition (yceruto)

This PR was merged into the 6.1 branch.

Discussion
----------

[HttpKernel] Simplifying Bundle/Extension config definition

| Q             | A
| ------------- | ---
| Branch?       | 6.1
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Tickets       | Fix #40259, #42647, symfony/symfony#43080
| License       | MIT
| Doc PR        | -

This PR aims to simplify DI extension/configuration definitions at the Bundle level (based on @Nyholm symfony/symfony#40259 (comment))

Currently, the services and configuration definitions have to deal with some conventions:
 * Create the `DependencyInjection/` directory
 * Create the `DependencyInjection/Configuration.php` class to define the bundle config.
 * Create the `DependencyInjection/FooExtension.php` extension class and extend from `Extension`
 * In the `ExtensionInterface::load()` method to implement we have to:
    * Process the bundle configuration yourself `Configuration`, `Processor`, etc.
    * Create the specific `*FileLoader` & `FileLocator` instances to import services definition (have to deal with bundle path)
 * Prepend/append configs for other extensions requires implementing `PrependExtensionInterface`.
 *  Redefine `Bundle::$name` to change the extension alias.

Although it may not be a big problem to follow all these conventions (indeed, we have been doing it for years) it's true that there are limitations and it requires extra work to achieve them.

Note: The following improvements don't pretend to deprecate the actual convention (at least so far) but simplify it with some benefits.

---
To start using the following improvements your bundle must extend from the new abstract class `AbstractBundle` to autoconfigure all hooks and make this possible inside a bundle class.

**The first improvement** offers the possibility to configure your bundle DI extension within the bundle class itself using `loadExtension()` method and the fluent `ContainerConfigurator` helper:
```php
class FooBundle extends AbstractBundle
{
    public function loadExtension(array $config, ContainerConfigurator $container, ContainerBuilder $builder): void
    {
        $container->parameters()
            ->set('foo', $config['foo']);

        $container->import('../config/services.php');

        if ('bar' === $config['foo']) {
            $container->services()
                ->set(Parser::class);
        }
    }
}
```
This new method `loadExtension()` (a same goal that `ExtensionInterface::load()`) contains now all new benefits you currently love for service definition/import/etc. Keep in mind that this configurator still works with a temporal container, so you can't access any extension config at this point (as before). And, the `$config` argument is the bundle's `Configuration` that you usually process on `ExtensionInterface::load()` but here it's given to you already merged and processed (ready to use).

---

**The next improvement** comes when you want to prepend/append an extension config before all extensions are loaded & merged, then use the `prependExtension()` method:
```php
class FooBundle extends AbstractBundle
{
    public function prependExtension(ContainerConfigurator $container, ContainerBuilder $builder): void
    {
        // prepend
        $builder->prependExtensionConfig('framework', [
            'cache' => ['prefix_seed' => 'foo/bar'],
        ]);

        // append
        $container->extension('framework', [
            'cache' => ['prefix_seed' => 'foo/bar'],
        ])

        // append from file
        $container->import('../config/packages/cache.php');
    }
}
```
This is the improved alternative to `PrependExtensionInterface` that you normally implement on extension classes. But using this method has bonus points, you can now use the `ContainerConfigurator` to append an extension config from an external file in any format (including the new PHP fluent-config feature).

---

**Another improvement** is about `Configuration` definition. Here you can manage it directly within the bundle class using the `configuration()` method with new possibilities:
```php
class FooBundle extends AbstractBundle
{
    public function configure(DefinitionConfigurator $definition): void
    {
        // loads config definition from a file
        $definition->import('../config/definition.php');

        // loads config definition from multiple files (when it's too long you can split it)
        $definition->import('../config/definition/*.php');

        // defines config directly when it's short
        $definition->rootNode()
            ->children()
                ->scalarNode('foo')->defaultValue('bar')->end()
            ->end()
        ;
    }
}
```
You don't have to create the `TreeBuilder` instance yourself anymore and remember the proper extension alias. Instead, you will use a new `DefinitionConfigurator` with the possibility to import configuration definitions from an external PHP file, and this config file can now live outside the `src/` directory of the bundle if desired:
```php
// Acme/FooBundle/config/definition.php

use Symfony\Component\Config\Definition\Configurator\DefinitionConfigurator;

return static function (DefinitionConfigurator $definition) {
    $definition->rootNode()
        ->children()
            ->scalarNode('foo')->defaultValue('bar')->end()
        ->end()
    ;
};
```
And why not, you could also split your definition into several files if it's too long, or simply define the config directly in the method if it's short.

---

**Last but not least** you can change the extension alias by redefining a new property that now belongs to the MicroBundle class:
```php
class AcmeFooBundle extends AbstractBundle
{
    protected string $extensionAlias = 'foo'; // alias used during the extension config loading

    // ...
}
```
The default alias will be determined from your bundle name (in this case `acme_foo`), so the new way allows you to change that alias without either touching your bundle name or overriding any method.

---

Note: The same feature has been implemented in a new `AbstractExtension` class for those applications applying the bundle-less approach and want to define configuration through an extension.

Combining all these benefits I believe we gain a more simplified bundle structure while decreasing the learning curve.

Commits
-------

7e8cf5df10 Simplifying bundle extension/config definition

Author: fabpot

CHANGELOG.md

@@ -11,6 +11,7 @@ CHANGELOG
  * Allow using expressions as service factories
  * Add argument type `closure` to help passing closures to services
  * Deprecate `ReferenceSetArgumentTrait`
+ * Add `AbstractExtension` class for DI configuration/definition on a single file
 
 6.0
 ---

Extension/AbstractExtension.php

@@ -0,0 +1,65 @@
+<?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\Component\DependencyInjection\Extension;
+
+use Symfony\Component\Config\Definition\Configuration;
+use Symfony\Component\Config\Definition\ConfigurationInterface;
+use Symfony\Component\Config\Definition\Configurator\DefinitionConfigurator;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
+
+/**
+ * An Extension that provides configuration hooks.
+ *
+ * @author Yonel Ceruto <yonelceruto@gmail.com>
+ */
+abstract class AbstractExtension extends Extension implements ConfigurableExtensionInterface, PrependExtensionInterface
+{
+    use ExtensionTrait;
+
+    public function configure(DefinitionConfigurator $definition): void
+    {
+    }
+
+    public function prependExtension(ContainerConfigurator $container, ContainerBuilder $builder): void
+    {
+    }
+
+    public function loadExtension(array $config, ContainerConfigurator $container, ContainerBuilder $builder): void
+    {
+    }
+
+    public function getConfiguration(array $config, ContainerBuilder $container): ?ConfigurationInterface
+    {
+        return new Configuration($this, $container, $this->getAlias());
+    }
+
+    final public function prepend(ContainerBuilder $container): void
+    {
+        $callback = function (ContainerConfigurator $configurator) use ($container) {
+            $this->prependExtension($configurator, $container);
+        };
+
+        $this->executeConfiguratorCallback($container, $callback, $this);
+    }
+
+    final public function load(array $configs, ContainerBuilder $container): void
+    {
+        $config = $this->processConfiguration($this->getConfiguration([], $container), $configs);
+
+        $callback = function (ContainerConfigurator $configurator) use ($config, $container) {
+            $this->loadExtension($config, $configurator, $container);
+        };
+
+        $this->executeConfiguratorCallback($container, $callback, $this);
+    }
+}

Extension/ConfigurableExtensionInterface.php

@@ -0,0 +1,32 @@
+<?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\Component\DependencyInjection\Extension;
+
+use Symfony\Component\Config\Definition\ConfigurableInterface;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
+
+/**
+ * @author Yonel Ceruto <yonelceruto@gmail.com>
+ */
+interface ConfigurableExtensionInterface extends ConfigurableInterface
+{
+    /**
+     * Allow an extension to prepend the extension configurations.
+     */
+    public function prependExtension(ContainerConfigurator $container, ContainerBuilder $builder): void;
+
+    /**
+     * Loads a specific configuration.
+     */
+    public function loadExtension(array $config, ContainerConfigurator $container, ContainerBuilder $builder): void;
+}

Extension/ExtensionTrait.php

@@ -0,0 +1,69 @@
+<?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\Component\DependencyInjection\Extension;
+
+use Symfony\Component\Config\Builder\ConfigBuilderGenerator;
+use Symfony\Component\Config\FileLocator;
+use Symfony\Component\Config\Loader\DelegatingLoader;
+use Symfony\Component\Config\Loader\LoaderResolver;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\DependencyInjection\Loader\ClosureLoader;
+use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
+use Symfony\Component\DependencyInjection\Loader\DirectoryLoader;
+use Symfony\Component\DependencyInjection\Loader\GlobFileLoader;
+use Symfony\Component\DependencyInjection\Loader\IniFileLoader;
+use Symfony\Component\DependencyInjection\Loader\PhpFileLoader;
+use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
+use Symfony\Component\DependencyInjection\Loader\YamlFileLoader;
+
+/**
+ * @author Yonel Ceruto <yonelceruto@gmail.com>
+ */
+trait ExtensionTrait
+{
+    private function executeConfiguratorCallback(ContainerBuilder $container, \Closure $callback, ConfigurableExtensionInterface $subject): void
+    {
+        $env = $container->getParameter('kernel.environment');
+        $loader = $this->createContainerLoader($container, $env);
+        $file = (new \ReflectionObject($subject))->getFileName();
+        $bundleLoader = $loader->getResolver()->resolve($file);
+        if (!$bundleLoader instanceof PhpFileLoader) {
+            throw new \LogicException('Unable to create the ContainerConfigurator.');
+        }
+        $bundleLoader->setCurrentDir(\dirname($file));
+        $instanceof = &\Closure::bind(function &() { return $this->instanceof; }, $bundleLoader, $bundleLoader)();
+
+        try {
+            $callback(new ContainerConfigurator($container, $bundleLoader, $instanceof, $file, $file, $env));
+        } finally {
+            $instanceof = [];
+            $bundleLoader->registerAliasesForSinglyImplementedInterfaces();
+        }
+    }
+
+    private function createContainerLoader(ContainerBuilder $container, string $env): DelegatingLoader
+    {
+        $buildDir = $container->getParameter('kernel.build_dir');
+        $locator = new FileLocator();
+        $resolver = new LoaderResolver([
+            new XmlFileLoader($container, $locator, $env),
+            new YamlFileLoader($container, $locator, $env),
+            new IniFileLoader($container, $locator, $env),
+            new PhpFileLoader($container, $locator, $env, new ConfigBuilderGenerator($buildDir)),
+            new GlobFileLoader($container, $locator, $env),
+            new DirectoryLoader($container, $locator, $env),
+            new ClosureLoader($container, $env),
+        ]);
+
+        return new DelegatingLoader($resolver);
+    }
+}

Tests/Extension/AbstractExtensionTest.php

@@ -0,0 +1,161 @@
+<?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\Component\DependencyInjection\Tests\Extension;
+
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\Config\Definition\ConfigurableInterface;
+use Symfony\Component\Config\Definition\Configuration;
+use Symfony\Component\Config\Definition\Configurator\DefinitionConfigurator;
+use Symfony\Component\Config\Definition\Processor;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\DependencyInjection\Extension\AbstractExtension;
+use Symfony\Component\DependencyInjection\Extension\ExtensionInterface;
+use Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface;
+use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
+use Symfony\Component\DependencyInjection\ParameterBag\ParameterBag;
+
+class AbstractExtensionTest extends TestCase
+{
+    public function testConfiguration()
+    {
+        $extension = new class() extends AbstractExtension {
+            public function configure(DefinitionConfigurator $definition): void
+            {
+                // load one
+                $definition->import('../Fixtures/config/definition/foo.php');
+
+                // load multiples
+                $definition->import('../Fixtures/config/definition/multiple/*.php');
+
+                // inline
+                $definition->rootNode()
+                    ->children()
+                        ->scalarNode('ping')->defaultValue('inline')->end()
+                    ->end();
+            }
+        };
+
+        $expected = [
+            'foo' => 'one',
+            'bar' => 'multi',
+            'baz' => 'multi',
+            'ping' => 'inline',
+        ];
+
+        self::assertSame($expected, $this->processConfiguration($extension));
+    }
+
+    public function testPrependAppendExtensionConfig()
+    {
+        $extension = new class() extends AbstractExtension {
+            public function prependExtension(ContainerConfigurator $container, ContainerBuilder $builder): void
+            {
+                // append config
+                $container->extension('third', ['foo' => 'append']);
+
+                // prepend config
+                $builder->prependExtensionConfig('third', ['foo' => 'prepend']);
+            }
+        };
+
+        $container = $this->processPrependExtension($extension);
+
+        $expected = [
+            ['foo' => 'prepend'],
+            ['foo' => 'bar'],
+            ['foo' => 'append'],
+        ];
+
+        self::assertSame($expected, $container->getExtensionConfig('third'));
+    }
+
+    public function testLoadExtension()
+    {
+        $extension = new class() extends AbstractExtension {
+            public function configure(DefinitionConfigurator $definition): void
+            {
+                $definition->import('../Fixtures/config/definition/foo.php');
+            }
+
+            public function loadExtension(array $config, ContainerConfigurator $container, ContainerBuilder $builder): void
+            {
+                $container->parameters()
+                    ->set('foo_param', $config)
+                ;
+
+                $container->services()
+                    ->set('foo_service', \stdClass::class)
+                ;
+
+                $container->import('../Fixtures/config/services.php');
+            }
+
+            public function getAlias(): string
+            {
+                return 'micro';
+            }
+        };
+
+        $container = $this->processLoadExtension($extension, [['foo' => 'bar']]);
+
+        self::assertSame(['foo' => 'bar'], $container->getParameter('foo_param'));
+        self::assertTrue($container->hasDefinition('foo_service'));
+        self::assertTrue($container->hasDefinition('bar_service'));
+    }
+
+    protected function processConfiguration(ConfigurableInterface $configurable): array
+    {
+        $configuration = new Configuration($configurable, null, 'micro');
+
+        return (new Processor())->process($configuration->getConfigTreeBuilder()->buildTree(), []);
+    }
+
+    protected function processPrependExtension(PrependExtensionInterface $extension): ContainerBuilder
+    {
+        $thirdExtension = new class() extends AbstractExtension {
+            public function configure(DefinitionConfigurator $definition): void
+            {
+                $definition->import('../Fixtures/config/definition/foo.php');
+            }
+
+            public function getAlias(): string
+            {
+                return 'third';
+            }
+        };
+
+        $container = $this->createContainerBuilder();
+        $container->registerExtension($thirdExtension);
+        $container->loadFromExtension('third', ['foo' => 'bar']);
+
+        $extension->prepend($container);
+
+        return $container;
+    }
+
+    protected function processLoadExtension(ExtensionInterface $extension, array $configs): ContainerBuilder
+    {
+        $container = $this->createContainerBuilder();
+
+        $extension->load($configs, $container);
+
+        return $container;
+    }
+
+    protected function createContainerBuilder(): ContainerBuilder
+    {
+        return new ContainerBuilder(new ParameterBag([
+            'kernel.environment' => 'test',
+            'kernel.build_dir' => 'test',
+        ]));
+    }
+}

Tests/Fixtures/config/definition/foo.php

@@ -0,0 +1,11 @@
+<?php
+
+use Symfony\Component\Config\Definition\Configurator\DefinitionConfigurator;
+
+return static function (DefinitionConfigurator $definition) {
+    $definition->rootNode()
+        ->children()
+            ->scalarNode('foo')->defaultValue('one')->end()
+        ->end()
+    ;
+};

Tests/Fixtures/config/definition/multiple/bar.php

@@ -0,0 +1,11 @@
+<?php
+
+use Symfony\Component\Config\Definition\Configurator\DefinitionConfigurator;
+
+return static function (DefinitionConfigurator $definition) {
+    $definition->rootNode()
+        ->children()
+            ->scalarNode('bar')->defaultValue('multi')->end()
+        ->end()
+    ;
+};

Tests/Fixtures/config/definition/multiple/baz.php

@@ -0,0 +1,11 @@
+<?php
+
+use Symfony\Component\Config\Definition\Configurator\DefinitionConfigurator;
+
+return static function (DefinitionConfigurator $definition) {
+    $definition->rootNode()
+        ->children()
+            ->scalarNode('baz')->defaultValue('multi')->end()
+        ->end()
+    ;
+};

Tests/Fixtures/config/services.php

@@ -0,0 +1,9 @@
+<?php
+
+use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
+
+return static function (ContainerConfigurator $c) {
+    $c->services()
+        ->set('bar_service', stdClass::class)
+    ;
+};