feature #49302 [HttpClient] Add UriTemplateHttpClient (fancyweb)

This PR was merged into the 6.3 branch.

Discussion
----------

[HttpClient] Add `UriTemplateHttpClient`

| Q             | A
| ------------- | ---
| Branch?       | 6.3
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Tickets       | -
| License       | MIT
| Doc PR        | -

This PR adds `UriTemplateHttpClient` to ease using URI templates (see https://www.rfc-editor.org/rfc/rfc6570) with `symfony/http-client`.

The goal is not to reimplement the RFC 6570 but to provide a better DX. A vendor has to be installed to expand the urls and we do not impose which one.

The simple usage is:
```php
(new UriTemplateHttpClient())
    ->request('GET', 'https//ccc.tld/{resource}{?page}', [
        'vars' => [
            'resource' => 'users',
            'page' => 3,
         ],
    ]);
    // the requested url is https//ccc.tld/users?page=3
```

In a full framework context, all HTTP clients are decorated by `UriTemplateHttpClient`. The support is transparent and enabled globally.
It's possible to configure a custom expander by redefining the `http_client.uri_template_expander` alias.

Commits
-------

803a54e51e [HttpClient] Add UriTemplateHttpClient

Author: nicolas-grekas

DependencyInjection/Configuration.php

@@ -1655,6 +1655,11 @@ private function addHttpClientSection(ArrayNodeDefinition $rootNode, callable $e
                                     ->normalizeKeys(false)
                                     ->variablePrototype()->end()
                                 ->end()
+                                ->arrayNode('vars')
+                                    ->info('Associative array: the default vars used to expand the templated URI.')
+                                    ->normalizeKeys(false)
+                                    ->variablePrototype()->end()
+                                ->end()
                                 ->integerNode('max_redirects')
                                     ->info('The maximum number of redirects to follow.')
                                 ->end()

DependencyInjection/FrameworkExtension.php

@@ -80,6 +80,7 @@
 use Symfony\Component\HttpClient\Retry\GenericRetryStrategy;
 use Symfony\Component\HttpClient\RetryableHttpClient;
 use Symfony\Component\HttpClient\ScopingHttpClient;
+use Symfony\Component\HttpClient\UriTemplateHttpClient;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpKernel\Attribute\AsController;
 use Symfony\Component\HttpKernel\CacheClearer\CacheClearerInterface;
@@ -2339,6 +2340,8 @@ private function registerHttpClientConfiguration(array $config, ContainerBuilder
         $options = $config['default_options'] ?? [];
         $retryOptions = $options['retry_failed'] ?? ['enabled' => false];
         unset($options['retry_failed']);
+        $defaultUriTemplateVars = $options['vars'] ?? [];
+        unset($options['vars']);
         $container->getDefinition('http_client')->setArguments([$options, $config['max_host_connections'] ?? 6]);
 
         if (!$hasPsr18 = ContainerBuilder::willBeAvailable('psr/http-client', ClientInterface::class, ['symfony/framework-bundle', 'symfony/http-client'])) {
@@ -2350,11 +2353,31 @@ private function registerHttpClientConfiguration(array $config, ContainerBuilder
             $container->removeDefinition(HttpClient::class);
         }
 
-        if ($this->readConfigEnabled('http_client.retry_failed', $container, $retryOptions)) {
+        if ($hasRetryFailed = $this->readConfigEnabled('http_client.retry_failed', $container, $retryOptions)) {
             $this->registerRetryableHttpClient($retryOptions, 'http_client', $container);
         }
 
-        $httpClientId = ($retryOptions['enabled'] ?? false) ? 'http_client.retryable.inner' : ($this->isInitializedConfigEnabled('profiler') ? '.debug.http_client.inner' : 'http_client');
+        if ($hasUriTemplate = class_exists(UriTemplateHttpClient::class)) {
+            if (ContainerBuilder::willBeAvailable('guzzlehttp/uri-template', \GuzzleHttp\UriTemplate\UriTemplate::class, [])) {
+                $container->setAlias('http_client.uri_template_expander', 'http_client.uri_template_expander.guzzle');
+            } elseif (ContainerBuilder::willBeAvailable('rize/uri-template', \Rize\UriTemplate::class, [])) {
+                $container->setAlias('http_client.uri_template_expander', 'http_client.uri_template_expander.rize');
+            }
+
+            $container
+                ->getDefinition('http_client.uri_template')
+                ->setArgument(2, $defaultUriTemplateVars);
+        } elseif ($defaultUriTemplateVars) {
+            throw new LogicException('Support for URI template requires symfony/http-client 6.3 or higher, try upgrading.');
+        }
+
+        $httpClientId = match (true) {
+            $hasUriTemplate => 'http_client.uri_template.inner',
+            $hasRetryFailed => 'http_client.retryable.inner',
+            $this->isInitializedConfigEnabled('profiler') => '.debug.http_client.inner',
+            default => 'http_client',
+        };
+
         foreach ($config['scoped_clients'] as $name => $scopeConfig) {
             if ('http_client' === $name) {
                 throw new InvalidArgumentException(sprintf('Invalid scope name: "%s" is reserved.', $name));
@@ -2385,6 +2408,17 @@ private function registerHttpClientConfiguration(array $config, ContainerBuilder
                 $this->registerRetryableHttpClient($retryOptions, $name, $container);
             }
 
+            if ($hasUriTemplate) {
+                $container
+                    ->register($name.'.uri_template', UriTemplateHttpClient::class)
+                    ->setDecoratedService($name, null, 7) // Between TraceableHttpClient (5) and RetryableHttpClient (10)
+                    ->setArguments([
+                        new Reference('.inner'),
+                        new Reference('http_client.uri_template_expander', ContainerInterface::NULL_ON_INVALID_REFERENCE),
+                        $defaultUriTemplateVars,
+                    ]);
+            }
+
             $container->registerAliasForArgument($name, HttpClientInterface::class);
 
             if ($hasPsr18) {

Resources/config/http_client.php

@@ -18,6 +18,7 @@
 use Symfony\Component\HttpClient\HttplugClient;
 use Symfony\Component\HttpClient\Psr18Client;
 use Symfony\Component\HttpClient\Retry\GenericRetryStrategy;
+use Symfony\Component\HttpClient\UriTemplateHttpClient;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
 
 return static function (ContainerConfigurator $container) {
@@ -60,5 +61,25 @@
                 abstract_arg('max delay ms'),
                 abstract_arg('jitter'),
             ])
+
+        ->set('http_client.uri_template', UriTemplateHttpClient::class)
+            ->decorate('http_client', null, 7) // Between TraceableHttpClient (5) and RetryableHttpClient (10)
+            ->args([
+                service('.inner'),
+                service('http_client.uri_template_expander')->nullOnInvalid(),
+                abstract_arg('default vars'),
+            ])
+
+        ->set('http_client.uri_template_expander.guzzle', \Closure::class)
+            ->factory([\Closure::class, 'fromCallable'])
+            ->args([
+                [\GuzzleHttp\UriTemplate\UriTemplate::class, 'expand'],
+            ])
+
+        ->set('http_client.uri_template_expander.rize', \Closure::class)
+            ->factory([\Closure::class, 'fromCallable'])
+            ->args([
+                [inline_service(\Rize\UriTemplate::class), 'expand'],
+            ])
     ;
 };

Tests/DependencyInjection/FrameworkExtensionTestCase.php

@@ -55,6 +55,7 @@
 use Symfony\Component\HttpClient\MockHttpClient;
 use Symfony\Component\HttpClient\RetryableHttpClient;
 use Symfony\Component\HttpClient\ScopingHttpClient;
+use Symfony\Component\HttpClient\UriTemplateHttpClient;
 use Symfony\Component\HttpKernel\DependencyInjection\LoggerPass;
 use Symfony\Component\HttpKernel\Fragment\FragmentUriGeneratorInterface;
 use Symfony\Component\Messenger\Transport\TransportFactory;
@@ -2003,15 +2004,15 @@ public function testHttpClientMockResponseFactory()
     {
         $container = $this->createContainerFromFile('http_client_mock_response_factory');
 
-        $definition = $container->getDefinition('http_client.mock_client');
+        $definition = $container->getDefinition(($uriTemplateHttpClientExists = class_exists(UriTemplateHttpClient::class)) ? 'http_client.uri_template.inner.mock_client' : 'http_client.mock_client');
 
         $this->assertSame(MockHttpClient::class, $definition->getClass());
         $this->assertCount(1, $definition->getArguments());
 
         $argument = $definition->getArgument(0);
 
         $this->assertInstanceOf(Reference::class, $argument);
-        $this->assertSame('http_client', current($definition->getDecoratedService()));
+        $this->assertSame($uriTemplateHttpClientExists ? 'http_client.uri_template.inner' : 'http_client', current($definition->getDecoratedService()));
         $this->assertSame('my_response_factory', (string) $argument);
     }