8000 feature #43701 [HttpKernel] Simplifying Bundle/Extension config defin… · symfony/symfony@4e6b803 · GitHub
[go: up one dir, main page]
Skip to content

Commit 4e6b803

Browse files
fabpotfabpot
committed
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, #43080 | License | MIT | Doc PR | - This PR aims to simplify DI extension/configuration definitions at the Bundle level (based on @Nyholm #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 ------- 7e8cf5d Simplifying bundle extension/config definition
2 parents acee03f + 7e8cf5d commit 4e6b803

File tree

25 files changed

+865
-5
lines changed

25 files changed

+865
-5
lines changed

‎src/Symfony/Component/Config/CHANGELOG.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ CHANGELOG
66

77
* Allow using environment variables in `EnumNode`
88
* Add Node's information in generated Config
9+
* Add `DefinitionFileLoader` class to load a TreeBuilder definition from an external file
10+
* Add `DefinitionConfigurator` helper
911

1012
6.0
1113
---

‎src/Symfony/Component/Config/Definition/ConfigurableInterface.php

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
<?php
2+
3+
/*
4+
* This file is part of the Symfony package.
5+
*
6+
* (c) Fabien Potencier <fabien@symfony.com>
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
namespace Symfony\Component\Config\Definition;
13+
14+
use Symfony\Component\Config\Definition\Configurator\DefinitionConfigurator;
15+
16+
/**
17+
* @author Yonel Ceruto <yonelceruto@gmail.com>
18+
*/
19+
interface ConfigurableInterface
20+
{
21+
/**
22+
* Generates the configuration tree builder.
23+
*/
24+
public function configure(DefinitionConfigurator $definition): void;
25+
}

‎src/Symfony/Component/Config/Definition/Configuration.php

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
<?php
2+
3+
/*
4+
* This file is part of the Symfony package.
5+
*
6+
* (c) Fabien Potencier <fabien@symfony.com>
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
namespace Symfony\Component\Config\Definition;
13+
14+
use Symfony\Component\Config\Definition\Builder\TreeBuilder;
15+
use Symfony\Component\Config\Definition\Configurator\DefinitionConfigurator;
16+
use Symfony\Component\Config\Definition\Loader\DefinitionFileLoader;
17+
use Symfony\Component\Config\FileLocator;
18+
use Symfony\Component\DependencyInjection\ContainerBuilder;
19+
20+
/**
21+
* @author Yonel Ceruto <yonelceruto@gmail.com>
22+
*
23+
* @final
24+
*/
25+
class Configuration implements ConfigurationInterface
26+
{
27+
public function __construct(
28+
private ConfigurableInterface $subject,
29+
private ?ContainerBuilder $container,
30+
private string $alias,
31+
) {
32+
}
33+
34+
public function getConfigTreeBuilder(): TreeBuilder
35+
{
36+
$treeBuilder = new TreeBuilder($this->alias);
37+
$file = (new \ReflectionObject($this->subject))->getFileName();
38+
$loader = new DefinitionFileLoader($treeBuilder, new FileLocator(\dirname($file)), $this->container);
39+
$configurator = new DefinitionConfigurator($treeBuilder, $loader, $file, $file);
40+
41+
$this->subject->configure($configurator);
42+
43+
return $treeBuilder;
44+
}
45+
}

‎src/Symfony/Component/Config/Definition/Configurator/DefinitionConfigurator.php

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
<?php
2+
3+
/*
4+
* This file is part of the Symfony package.
5+
*
6+
* (c) Fabien Potencier <fabien@symfony.com>
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
namespace Symfony\Component\Config\Definition\Configurator;
13+
14+
use Symfony\Component\Config\Definition\Builder\ArrayNodeDefinition;
15+
use Symfony\Component\Config\Definition\Builder\NodeDefinition;
16+
use Symfony\Component\Config\Definition\Builder\TreeBuilder;
17+
use Symfony\Component\Config\Definition\Loader\DefinitionFileLoader;
18+
19+
/**
20+
* @author Yonel Ceruto <yonelceruto@gmail.com>
21+
*/
22+
class DefinitionConfigurator
23+
{
24+
public function __construct(
25+
private TreeBuilder $treeBuilder,
26+
private DefinitionFileLoader $loader,
27+
private string $path,
28+
private string $file,
29+
) {
30+
}
31+
32+
public function import(string $resource, string $type = null, bool $ignoreErrors = false): void
33+
{
34+
$this->loader->setCurrentDir(\dirname($this->path));
35+
$this->loader->import($resource, $type, $ignoreErrors, $this->file);
36+
}
37+
38+
public function rootNode(): NodeDefinition|ArrayNodeDefinition
39+
{
40+
return $this->treeBuilder->getRootNode();
41+
}
42+
43+
public function setPathSeparator(string $separator): void
44+
{
45+
$this->treeBuilder->setPathSeparator($separator);
46+
}
47+
}

‎src/Symfony/Component/Config/Definition/Loader/DefinitionFileLoader.php

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
<?php
2+
3+
/*
4+
* This file is part of the Symfony package.
5+
*
6+
* (c) Fabien Potencier <fabien@symfony.com>
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
namespace Symfony\Component\Config\Definition\Loader;
13+
14+
use Symfony\Component\Config\Definition\Builder\TreeBuilder;
15+
use Symfony\Component\Config\Definition\Configurator\DefinitionConfigurator;
16+
use Symfony\Component\Config\FileLocatorInterface;
17+
use Symfony\Component\Config\Loader\FileLoader;
18+
use Symfony\Component\DependencyInjection\ContainerBuilder;
19+
20+
/**
21+
* DefinitionFileLoader loads config definitions from a PHP file.
22+
*
23+
* The PHP file is required.
24+
*
25+
* @author Yonel Ceruto <yonelceruto@gmail.com>
26+
*/
27+
class DefinitionFileLoader extends FileLoader
28+
{
29+
public function __construct(
30+
private TreeBuilder $treeBuilder,
31+
FileLocatorInterface $locator,
32+
private ?ContainerBuilder $container = null,
33+
) {
34+
parent::__construct($locator);
35+
}
36+
37+
/**
38+
* {@inheritdoc}
39+
*/
40+
public function load(mixed $resource, string $type = null): mixed
41+
{
42+
// the loader variable is exposed to the included file below
43+
$loader = $this;
44+
45+
$path = $this->locator->locate($resource);
46+
$this->setCurrentDir(\dirname($path));
47+
$this->container?->fileExists($path);
48+
49+
// the closure forbids access to the private scope in the included file
50+
$load = \Closure::bind(static function ($file) use ($loader) {
51+
return include $file;
52+
}, null, ProtectedDefinitionFileLoader::class);
53+
54+
$callback = $load($path);
55+
56+
if (\is_object($callback) && \is_callable($callback)) {
57+
$this->executeCallback($callback, new DefinitionConfigurator($this->treeBuilder, $this, $path, $resource), $path);
58+
}
59+
60+
return null;
61+
}
62+
63+
/**
64+
* {@inheritdoc}
65+
*/
66+
public function supports(mixed $resource, string $type = null): bool
67+
{
68+
if (!\is_string($resource)) {
69+
return false;
70+
}
71+
72+
if (null === $type && 'php' === pathinfo($resource, \PATHINFO_EXTENSION)) {
73+
return true;
74+
}
75+
76+
return 'php' === $type;
77+
}
78+
79+
private function executeCallback(callable $callback, DefinitionConfigurator $configurator, string $path): void
80+
{
81+
$callback = $callback(...);
82+
83+
$arguments = [];
84+
$r = new \ReflectionFunction($callback);
85+
86+
foreach ($r->getParameters() as $parameter) {
87+
$reflectionType = $parameter->getType();
88+
89+
if (!$reflectionType instanceof \ReflectionNamedType) {
90+
throw new \InvalidArgumentException(sprintf('Could not resolve argument "$%s" for "%s". You must typehint it (for example with "%s").', $parameter->getName(), $path, DefinitionConfigurator::class));
91+
}
92+
93+
$arguments[] = match ($reflectionType->getName()) {
94+
DefinitionConfigurator::class => $configurator,
95+
TreeBuilder::class => $this->treeBuilder,
96+
FileLoader::class, self::class => $this,
97+
};
98+
}
99+
100+
$callback(...$arguments);
101+
}
102+
}
103+
104+
/**
105+
* @internal
106+
*/
107+
final class ProtectedDefinitionFileLoader extends DefinitionFileLoader
108+
{
109+
}

‎src/Symfony/Component/Config/Tests/Definition/Loader/DefinitionFileLoaderTest.php

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
<?php
2+
3+
/*
4+
* This file is part of the Symfony package.
5+
*
6+
* (c) Fabien Potencier <fabien@symfony.com>
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
namespace Symfony\Component\Config\Tests\Definition\Loader;
13+
14+
use PHPUnit\Framework\TestCase;
15+
use Symfony\Component\Config\Definition\BaseNode;
16+
use Symfony\Component\Config\Definition\Builder\TreeBuilder;
17+
use Symfony\Component\Config\Definition\Loader\DefinitionFileLoader;
18+
use Symfony\Component\Config\FileLocator;
19+
20+
class DefinitionFileLoaderTest extends TestCase
21+
{
22+
public function testSupports()
23+
{
24+
$loader = new DefinitionFileLoader(new TreeBuilder('test'), new FileLocator());
25+
26+
$this->assertTrue($loader->supports('foo.php'), '->supports() returns true if the resource is loadable');
27+
$this->assertFalse($loader->supports('foo.foo'), '->supports() returns false if the resource is not loadable');
28+
$this->assertTrue($loader->supports('with_wrong_ext.yml', 'php'), '->supports() returns true if the resource with forced type is loadable');
29+
}
30+
31+
public function testLoad()
32+
{
33+
$loader = new DefinitionFileLoader($treeBuilder = new TreeBuilder('test'), new FileLocator());
34+
$loader->load(__DIR__.'/../../Fixtures/Loader/node_simple.php');
35+
36+
$children = $treeBuilder->buildTree()->getChildren();
37+
38+
$this->assertArrayHasKey('foo', $children);
39+
$this->assertInstanceOf(BaseNode::class, $children['foo']);
40+
$this->assertSame('test.foo', $children['foo']->getPath(), '->load() loads a PHP file resource');
41+
}
42+
}

‎src/Symfony/Component/Config/Tests/Fixtures/Loader/node_simple.php

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
<?php
2+
3+
use Symfony\Component\Config\Definition\Builder\TreeBuilder;
4+
5+
return static function (TreeBuilder $treeBuilder) {
6+
$treeBuilder->getRootNode()
7+
->children()
8+
->scalarNode('foo')->end()
9+
->end();
10+
};

‎src/Symfony/Component/DependencyInjection/CHANGELOG.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ CHANGELOG
1111
* Allow using expressions as service factories
1212
* Add argument type `closure` to help passing closures to services
1313
* Deprecate `ReferenceSetArgumentTrait`
14+
* Add `AbstractExtension` class for DI configuration/definition on a single file
1415

1516
6.0
1617
---

‎src/Symfony/Component/DependencyInjection/Extension/AbstractExtension.php

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
<?php
2+
3+
/*
4+
* This file is part of the Symfony package.
5+
*
6+
* (c) Fabien Potencier <fabien@symfony.com>
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
namespace Symfony\Component\DependencyInjection\Extension;
13+
14+
use Symfony\Component\Config\Definition\Configuration;
15+
use Symfony\Component\Config\Definition\ConfigurationInterface;
16+
use Symfony\Component\Config\Definition\Configurator\DefinitionConfigurator;
17+
use Symfony\Component\DependencyInjection\ContainerBuilder;
18+
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
19+
20+
/**
21+
* An Extension that provides configuration hooks.
22+
*
23+
* @author Yonel Ceruto <yonelceruto@gmail.com>
24+
*/
25+
abstract class AbstractExtension extends Extension implements ConfigurableExtensionInterface, PrependExtensionInterface
26+
{
27+
use ExtensionTrait;
28+
29+
public function configure(DefinitionConfigurator $definition): void
30+
{
31+
}
32+
33+
public function prependExtension(ContainerConfigurator $container, ContainerBuilder $builder): void
34+
{
35+
}
36+
37+
public function loadExtension(array $config, ContainerConfigurator $container, ContainerBuilder $builder): void
38+
{
39+
}
40+
41+
public function getConfiguration(array $config, ContainerBuilder $container): ?ConfigurationInterface
42+
{
43+
return new Configuration($this, $container, $this->getAlias());
44+
}
45+
46+
final public function prepend(ContainerBuilder $container): void
47+
{
48+
$callback = function (ContainerConfigurator $configurator) use ($container) {
49+
$this->prependExtension($configurator, $container);
50+
};
51+
52+
$this->executeConfiguratorCallback($container, $callback, $this);
53+
}
54+
55+
final public function load(array $configs, ContainerBuilder $container): void
56+
{
57+
$config = $this->processConfiguration($this->getConfiguration([], $container), $configs);
58+
59+
$callback = function (ContainerConfigurator $configurator) use ($config, $container) {
60+
$this->loadExtension($config, $configurator, $container);
61+
};
62+
63+
$this->executeConfiguratorCallback($container, $callback, $this);
64+
}
65+
}

‎src/Symfony/Component/DependencyInjection/Extension/ConfigurableExtensionInterface.php

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
<?php
2+
3+
/*
4+
* This file is part of the Symfony package.
5+
*
6+
* (c) Fabien Potencier <fabien@symfony.com>
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
namespace Symfony\Component\DependencyInjection\Extension;
13+
14+
use Symfony\Component\Config\Definition\ConfigurableInterface;
15+
use Symfony\Component\DependencyInjection\ContainerBuilder;
16+
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
17+
18+
/**
19+
* @author Yonel Ceruto <yonelceruto@gmail.com>
20+
*/
21+
interface ConfigurableExtensionInterface extends ConfigurableInterface
22+
{
23+
/**
24+
* Allow an extension to prepend the extension configurations.
25+
*/
26+
public function prependExtension(ContainerConfigurator $container, ContainerBuilder $builder): void;
27+
28+
/**
29+
* Loads a specific configuration.
30+
*/
31+
public function loadExtension(array $config, ContainerConfigurator $container, ContainerBuilder $builder): void;
32+
}

0 commit comments

Comments
 (0)
0