Introduce PluginConfigurator (#477)

ruudk · web-flow · commit 451c06506a0c · 2024-11-24T10:48:55.000+01:00
* Store references in plugins array

* Introduce PluginConfigurator

This allows for configuring plugins via the normal config.

When you have a plugin that does not require config, the old behavior is the easiest.

But when you do want custom config per client, it will be cumbersome to create separate services
and reference them everywhere.

It would be easier to have the same type of configuration as the built-in clients.

That's now possible with the PluginConfigurator.

Define the plugins as follows:
```yaml
'plugins' =&gt; [
    [
        'configurator' =&gt; [
            'id' =&gt; CustomPluginConfigurator::class,
            'config' =&gt; [
                'name' =&gt; 'foo',
            ]
        ],
    ],
],
```

The `CustomPluginConfigurator` looks like this:
```php
final class CustomPluginConfigurator implements PluginConfigurator
{
    public static function getConfigTreeBuilder() : TreeBuilder
    {
        $treeBuilder = new TreeBuilder('custom_plugin');
        $rootNode = $treeBuilder-&gt;getRootNode();

        $rootNode
            -&gt;children()
                -&gt;scalarNode('name')
                    -&gt;isRequired()
                    -&gt;cannotBeEmpty()
                -&gt;end()
            -&gt;end();

        return $treeBuilder;
    }

    public function create(array $config) : CustomPlugin
    {
        return new CustomPlugin($config['name']);
    }
}
```

On compile time, the config will be evaluated. It will create the service definition
by calling the `create` method with the given config.

On runtime you will have the CustomPlugin instantiated with the custom config.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,10 @@ The change log describes what is "Added", "Removed", "Changed" or "Fixed" betwee
 
 # Version 2
 
+# 2.1.0
+
+- Added [PluginConfigurator](https://docs.php-http.org/en/latest/integrations/symfony-bundle.html#configure-a-custom-plugin)
+
 # 2.0.0 - 2024-09-16
 
 - Increased min PHP version to 8.1
diff --git a/src/DependencyInjection/Configuration.php b/src/DependencyInjection/Configuration.php
@@ -275,6 +275,22 @@ private function createClientPluginNode(): ArrayNodeDefinition
                         ->end()
                     ->end()
                 ->end()
+                ->arrayNode('configurator')
+                    ->canBeEnabled()
+                    ->info('Configure a plugin with a configurator')
+                    ->children()
+                        ->scalarNode('id')
+                            ->info('Service id of a plugin configurator')
+                            ->isRequired()
+                            ->cannotBeEmpty()
+                        ->end()
+                        ->arrayNode('config')
+                            ->normalizeKeys(false)
+                            ->prototype('variable')
+                            ->end()
+                        ->end()
+                    ->end()
+                ->end()
                 ->arrayNode('add_host')
                     ->canBeEnabled()
                     ->addDefaultsIfNotSet()
diff --git a/src/DependencyInjection/HttplugExtension.php b/src/DependencyInjection/HttplugExtension.php
@@ -16,6 +16,7 @@
 use Http\Client\HttpAsyncClient;
 use Http\Client\Plugin\Vcr\RecordPlugin;
 use Http\Client\Plugin\Vcr\ReplayPlugin;
+use Http\HttplugBundle\PluginConfigurator;
 use Http\Message\Authentication\BasicAuth;
 use Http\Message\Authentication\Bearer;
 use Http\Message\Authentication\Header;
@@ -427,17 +428,41 @@ private function configureClient(ContainerBuilder $container, string $clientName
 
             switch ($pluginName) {
                 case 'reference':
-                    $plugins[] = $pluginConfig['id'];
+                    $plugins[] = new Reference($pluginConfig['id']);
+                    break;
+                case 'configurator':
+                    if (!is_a($pluginConfig['id'], PluginConfigurator::class, true)) {
+                        throw new \LogicException(sprintf('The plugin "%s" is not a valid PluginConfigurator.', $pluginConfig['id']));
+                    }
+
+                    $config = $pluginConfig['id']::getConfigTreeBuilder()->buildTree()->finalize($pluginConfig['config']);
+
+                    $definition = new Definition(null, [$config]);
+                    $definition->setFactory([new Reference($pluginConfig['id']), 'create']);
+
+                    $plugins[] = $definition;
                     break;
                 case 'authentication':
-                    $plugins = array_merge($plugins, $this->configureAuthentication($container, $pluginConfig, $serviceId.'.authentication'));
+                    $plugins = array_merge(
+                        $plugins,
+                        array_map(
+                            fn ($id) => new Reference($id),
+                            $this->configureAuthentication($container, $pluginConfig, $serviceId.'.authentication')
+                        )
+                    );
                     break;
                 case 'vcr':
                     $this->useVcrPlugin = true;
-                    $plugins = array_merge($plugins, $this->configureVcrPlugin($container, $pluginConfig, $serviceId.'.vcr'));
+                    $plugins = array_merge(
+                        $plugins,
+                        array_map(
+                            fn ($id) => new Reference($id),
+                            $this->configureVcrPlugin($container, $pluginConfig, $serviceId.'.vcr'),
+                        ),
+                    );
                     break;
                 default:
-                    $plugins[] = $this->configurePlugin($container, $serviceId, $pluginName, $pluginConfig);
+                    $plugins[] = new Reference($this->configurePlugin($container, $serviceId, $pluginName, $pluginConfig));
             }
         }
 
@@ -456,12 +481,7 @@ private function configureClient(ContainerBuilder $container, string $clientName
             ->register($serviceId, PluginClient::class)
             ->setFactory([new Reference(PluginClientFactory::class), 'createClient'])
             ->addArgument(new Reference($serviceId.'.client'))
-            ->addArgument(
-                array_map(
-                    fn ($id) => new Reference($id),
-                    $plugins
-                )
-            )
+            ->addArgument($plugins)
             ->addArgument([
                 'client_name' => $clientName,
             ])
diff --git a/src/PluginConfigurator.php b/src/PluginConfigurator.php
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Http\HttplugBundle;
+
+use Http\Client\Common\Plugin;
+use Symfony\Component\Config\Definition\Builder\TreeBuilder;
+
+interface PluginConfigurator
+{
+    public static function getConfigTreeBuilder(): TreeBuilder;
+
+    /**
+     * Creates the plugin with the given config.
+     *
+     * @param array<mixed> $config
+     */
+    public function create(array $config): Plugin;
+}
diff --git a/tests/Resources/CustomPlugin.php b/tests/Resources/CustomPlugin.php
@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Http\HttplugBundle\Tests\Resources;
+
+use Http\Client\Common\Plugin;
+use Http\Promise\Promise;
+use Psr\Http\Message\RequestInterface;
+
+final class CustomPlugin implements Plugin
+{
+    private string $name;
+
+    public function __construct(string $name)
+    {
+        $this->name = $name;
+    }
+
+    public function handleRequest(RequestInterface $request, callable $next, callable $first): Promise
+    {
+        return $next($request);
+    }
+}
diff --git a/tests/Resources/CustomPluginConfigurator.php b/tests/Resources/CustomPluginConfigurator.php
@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Http\HttplugBundle\Tests\Resources;
+
+use Http\HttplugBundle\PluginConfigurator;
+use Symfony\Component\Config\Definition\Builder\TreeBuilder;
+
+final class CustomPluginConfigurator implements PluginConfigurator
+{
+    public static function getConfigTreeBuilder(): TreeBuilder
+    {
+        $treeBuilder = new TreeBuilder('custom_plugin');
+        $rootNode = $treeBuilder->getRootNode();
+
+        $rootNode
+            ->children()
+                ->scalarNode('name')
+                    ->isRequired()
+                    ->cannotBeEmpty()
+                ->end()
+            ->end();
+
+        return $treeBuilder;
+    }
+
+    public function create(array $config): CustomPlugin
+    {
+        return new CustomPlugin($config['name']);
+    }
+}
diff --git a/tests/Resources/Fixtures/config/full.php b/tests/Resources/Fixtures/config/full.php
@@ -2,6 +2,8 @@
 
 declare(strict_types=1);
 
+use Http\HttplugBundle\Tests\Resources\CustomPluginConfigurator;
+
 $container->loadFromExtension('httplug', [
     'default_client_autowiring' => false,
     'main_alias' => [
@@ -27,6 +29,14 @@
             'http_methods_client' => true,
             'plugins' => [
                 'httplug.plugin.redirect',
+                [
+                    'configurator' => [
+                        'id' => CustomPluginConfigurator::class,
+                        'config' => [
+                            'name' => 'foo',
+                        ],
+                    ],
+                ],
                 [
                     'add_host' => [
                         'host' => 'http://localhost',
diff --git a/tests/Resources/Fixtures/config/full.xml b/tests/Resources/Fixtures/config/full.xml
@@ -22,6 +22,13 @@
         </classes>
         <client name="test" factory="httplug.factory.guzzle7" http-methods-client="true">
             <plugin>httplug.plugin.redirect</plugin>
+            <plugin>
+                <configurator id="Http\HttplugBundle\Tests\Resources\CustomPluginConfigurator">
+                    <config>
+                        <name>foo</name>
+                    </config>
+                </configurator>
+            </plugin>
             <plugin>
                 <add-host host="http://localhost"/>
             </plugin>
diff --git a/tests/Resources/Fixtures/config/full.yml b/tests/Resources/Fixtures/config/full.yml
@@ -21,6 +21,11 @@ httplug:
             http_methods_client: true
             plugins:
                 - 'httplug.plugin.redirect'
+                -
+                    configurator:
+                        id: Http\HttplugBundle\Tests\Resources\CustomPluginConfigurator
+                        config:
+                            name: foo
                 -
                     add_host:
                         host: http://localhost
diff --git a/tests/Unit/DependencyInjection/ConfigurationTest.php b/tests/Unit/DependencyInjection/ConfigurationTest.php
@@ -7,6 +7,7 @@
 use Http\Adapter\Guzzle7\Client;
 use Http\HttplugBundle\DependencyInjection\Configuration;
 use Http\HttplugBundle\DependencyInjection\HttplugExtension;
+use Http\HttplugBundle\Tests\Resources\CustomPluginConfigurator;
 use Matthias\SymfonyDependencyInjectionTest\PhpUnit\AbstractExtensionConfigurationTestCase;
 use Nyholm\Psr7\Factory\Psr17Factory;
 use Symfony\Component\Config\Definition\ConfigurationInterface;
@@ -155,6 +156,15 @@ public function testSupportsAllConfigFormats(): void
                                 'id' => 'httplug.plugin.redirect',
                             ],
                         ],
+                        [
+                            'configurator' => [
+                                'enabled' => true,
+                                'id' => CustomPluginConfigurator::class,
+                                'config' => [
+                                    'name' => 'foo',
+                                ],
+                            ],
+                        ],
                         [
                             'add_host' => [
                                 'enabled' => true,
diff --git a/tests/Unit/DependencyInjection/HttplugExtensionTest.php b/tests/Unit/DependencyInjection/HttplugExtensionTest.php
@@ -7,8 +7,10 @@
 use Http\Adapter\Guzzle7\Client;
 use Http\Client\Plugin\Vcr\Recorder\InMemoryRecorder;
 use Http\HttplugBundle\DependencyInjection\HttplugExtension;
+use Http\HttplugBundle\Tests\Resources\CustomPluginConfigurator;
 use Matthias\SymfonyDependencyInjectionTest\PhpUnit\AbstractExtensionTestCase;
 use Psr\Http\Client\ClientInterface;
+use Symfony\Component\DependencyInjection\Definition;
 use Symfony\Component\DependencyInjection\Reference;
 
 /**
@@ -203,6 +205,40 @@ public function testClientPlugins(): void
         $this->assertContainerBuilderHasService('httplug.client.mock');
     }
 
+    public function testPluginConfiguratorConfig(): void
+    {
+        $config = [
+            'clients' => [
+                'acme' => [
+                    'factory' => 'httplug.factory.curl',
+                    'plugins' => [
+                        [
+                            'configurator' => [
+                                'id' => CustomPluginConfigurator::class,
+                                'config' => [
+                                    'name' => 'foo',
+                                ],
+                            ],
+                        ],
+                    ],
+                ],
+            ],
+        ];
+
+        $this->load($config);
+
+        $definition = new Definition(null, [
+            ['name' => 'foo'],
+        ]);
+        $definition->setFactory([CustomPluginConfigurator::class, 'create']);
+
+        $this->assertContainerBuilderHasService('httplug.client.acme');
+        $this->assertContainerBuilderHasServiceDefinitionWithArgument('httplug.client.acme', 1, [
+            $definition,
+        ]);
+        $this->assertContainerBuilderHasService('httplug.client.mock');
+    }
+
     public function testNoProfilingWhenNotInDebugMode(): void
     {
         $this->setParameter('kernel.debug', false);
