feature #59576 [HttpClient] Make CachingHttpClient compatible with RFC 9111 (Lctrs)

nicolas-grekas · nicolas-grekas · commit 9c413a356ccb · 2025-09-29T09:12:49.000+02:00
This PR was squashed before being merged into the 7.4 branch. Discussion ---------- [HttpClient] Make `CachingHttpClient` compatible with RFC 9111 | Q | A | ------------- | --- | Branch? | 7.3 | Bug fix? | no | New feature? | yes | Deprecations? | yes | Issues | Fix #36858 Fix #49937 Fix #41843 Fix #61588 | License | MIT This PR brings [RFC9111](https://www.rfc-editor.org/rfc/rfc9111.html) support to `CachingHttpClient` by leveraging `symfony/cache`. It provides caching for `GET` and `HEAD` requests, and cache invalidation for `POST`, `PUT`, `DELETE`, `PATCH`. The implementation is **asynchronous**, so the response **must be consumed** (e.g., via getContent() or streaming) for caching to occur. ### Basic usage ```php // Create the base HTTP client $baseClient = HttpClient::create(); // Create a cache backend (e.g., Filesystem cache) $cache = new FilesystemAdapter(); // Instantiate the CachingHttpClient $client = new CachingHttpClient( client: $baseClient, cache: $cache, defaultOptions: [], // Optional default options sharedCache: true, // Use a shared cache (default) maxTtl: 86400 // Maximum cache TTL in seconds (optional) ); // Make a request $response = $client->request('GET', 'https://api.example.com/data'); // Get the response content $content = $response->getContent(); ``` ### Constructor parameters - `$client`: The underlying HTTP client. - `$cache`: A cache backend implementing `TagAwareCacheInterface`. - `$defaultOptions`: An optional array of default request options. - `$sharedCache`: `true` to indicate the cache is [shared](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Caching#shared_cache), `false` for [private](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Caching#private_caches). Defaults to true. - `$maxTtl`: Optional maximum time-to-live (in seconds) for cached responses. If set, server-provided TTLs are capped to this value. ### Omissions from RFC9111 - The following cache-control directives are not supported and thus ignored : `stale-while-revalidate`, `min-fresh`, `max-stale`, and `only-if-cached`. In the case of `stale-while-revalidate`, a stale response will always be revalidated. - Range requests and partial content (206 status, Range/Content-Range headers) are not supported; requests with Range headers bypass caching. ### Integration with FrameworkBundle ```yaml framework: http_client: caching: cache_pool: my_taggable_pool shared: true max_ttl: 86400 scoped_clients: caching_client: base_uri: 'https://symfony.com' caching: cache_pool: my_taggable_pool ``` It is also **highly recommended** to configure a retry strategy to automatically retry the request in case of cache inconsistency. Commits ------- a62b547 [HttpClient] Make `CachingHttpClient` compatible with RFC 9111
diff --git a/UPGRADE-7.4.md b/UPGRADE-7.4.md
@@ -57,6 +57,7 @@ HttpClient
 ----------
 
  * Deprecate using amphp/http-client < 5
+ * Deprecate passing an instance of `StoreInterface` as `$cache` argument to `CachingHttpClient` constructor
 
 HttpFoundation
 --------------
diff --git a/src/Symfony/Bundle/FrameworkBundle/CHANGELOG.md b/src/Symfony/Bundle/FrameworkBundle/CHANGELOG.md
@@ -12,6 +12,7 @@ CHANGELOG
  * Add `framework.type_info.aliases` option
  * Add `KernelBrowser::getSession()`
  * Add support for configuring workflow places with glob patterns matching consts/backed enums
+ * Add support for configuring the `CachingHttpClient`
 
 7.3
 ---
diff --git a/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/Configuration.php b/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/Configuration.php
@@ -1995,6 +1995,7 @@ private function addHttpClientSection(ArrayNodeDefinition $rootNode, callable $e
                                     ->defaultNull()
                                     ->info('Rate limiter name to use for throttling requests.')
                                 ->end()
+                                ->append($this->createHttpClientCachingSection())
                                 ->append($this->createHttpClientRetrySection())
                             ->end()
                         ->end()
@@ -2140,6 +2141,7 @@ private function addHttpClientSection(ArrayNodeDefinition $rootNode, callable $e
                                         ->defaultNull()
                                         ->info('Rate limiter name to use for throttling requests.')
                                     ->end()
+                                    ->append($this->createHttpClientCachingSection())
                                     ->append($this->createHttpClientRetrySection())
                                 ->end()
                             ->end()
@@ -2150,6 +2152,33 @@ private function addHttpClientSection(ArrayNodeDefinition $rootNode, callable $e
         ;
     }
 
+    private function createHttpClientCachingSection(): ArrayNodeDefinition
+    {
+        $root = new NodeBuilder();
+
+        return $root
+            ->arrayNode('caching')
+                ->info('Caching configuration.')
+                ->canBeEnabled()
+                ->addDefaultsIfNotSet()
+                ->children()
+                    ->stringNode('cache_pool')
+                        ->info('The taggable cache pool to use for storing the responses.')
+                        ->defaultValue('cache.http_client')
+                        ->cannotBeEmpty()
+                    ->end()
+                    ->booleanNode('shared')
+                        ->info('Indicates whether the cache is shared (public) or private.')
+                        ->defaultTrue()
+                    ->end()
+                    ->integerNode('max_ttl')
+                        ->info('The maximum TTL (in seconds) allowed for cached responses. Null means no cap.')
+                        ->defaultNull()
+                        ->min(0)
+                    ->end()
+                ->end();
+    }
+
     private function createHttpClientRetrySection(): ArrayNodeDefinition
     {
         $root = new NodeBuilder();
diff --git a/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/FrameworkExtension.php b/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/FrameworkExtension.php
@@ -93,6 +93,8 @@
 use Symfony\Component\HtmlSanitizer\HtmlSanitizer;
 use Symfony\Component\HtmlSanitizer\HtmlSanitizerConfig;
 use Symfony\Component\HtmlSanitizer\HtmlSanitizerInterface;
+use Symfony\Component\HttpClient\CachingHttpClient;
+use Symfony\Component\HttpClient\Exception\ChunkCacheItemNotFoundException;
 use Symfony\Component\HttpClient\Messenger\PingWebhookMessageHandler;
 use Symfony\Component\HttpClient\MockHttpClient;
 use Symfony\Component\HttpClient\Retry\GenericRetryStrategy;
@@ -2770,6 +2772,8 @@ private function registerHttpClientConfiguration(array $config, ContainerBuilder
         $loader->load('http_client.php');
 
         $options = $config['default_options'] ?? [];
+        $cachingOptions = $options['caching'] ?? ['enabled' => false];
+        unset($options['caching']);
         $rateLimiter = $options['rate_limiter'] ?? null;
         unset($options['rate_limiter']);
         $retryOptions = $options['retry_failed'] ?? ['enabled' => false];
@@ -2793,6 +2797,10 @@ private function registerHttpClientConfiguration(array $config, ContainerBuilder
             $container->removeAlias(HttpClient::class);
         }
 
+        if ($this->readConfigEnabled('http_client.caching', $container, $cachingOptions)) {
+            $this->registerCachingHttpClient($cachingOptions, $options, 'http_client', $container);
+        }
+
         if (null !== $rateLimiter) {
             $this->registerThrottlingHttpClient($rateLimiter, 'http_client', $container);
         }
@@ -2818,6 +2826,8 @@ private function registerHttpClientConfiguration(array $config, ContainerBuilder
 
             $scope = $scopeConfig['scope'] ?? null;
             unset($scopeConfig['scope']);
+            $cachingOptions = $scopeConfig['caching'] ?? ['enabled' => false];
+            unset($scopeConfig['caching']);
             $rateLimiter = $scopeConfig['rate_limiter'] ?? null;
             unset($scopeConfig['rate_limiter']);
             $retryOptions = $scopeConfig['retry_failed'] ?? ['enabled' => false];
@@ -2841,6 +2851,10 @@ private function registerHttpClientConfiguration(array $config, ContainerBuilder
                 ;
             }
 
+            if ($this->readConfigEnabled('http_client.scoped_clients.'.$name.'.caching', $container, $cachingOptions)) {
+                $this->registerCachingHttpClient($cachingOptions, $scopeConfig, $name, $container);
+            }
+
             if (null !== $rateLimiter) {
                 $this->registerThrottlingHttpClient($rateLimiter, $name, $container);
             }
@@ -2882,6 +2896,24 @@ private function registerHttpClientConfiguration(array $config, ContainerBuilder
         }
     }
 
+    private function registerCachingHttpClient(array $options, array $defaultOptions, string $name, ContainerBuilder $container): void
+    {
+        if (!class_exists(ChunkCacheItemNotFoundException::class)) {
+            throw new LogicException('Caching cannot be enabled as version 7.3+ of the HttpClient component is required.');
+        }
+
+        $container
+            ->register($name.'.caching', CachingHttpClient::class)
+            ->setDecoratedService($name, null, 13) // between RetryableHttpClient (10) and ThrottlingHttpClient (15)
+            ->setArguments([
+                new Reference($name.'.caching.inner'),
+                new Reference($options['cache_pool']),
+                $defaultOptions,
+                $options['shared'],
+                $options['max_ttl'],
+            ]);
+    }
+
     private function registerThrottlingHttpClient(string $rateLimiter, string $name, ContainerBuilder $container): void
     {
         if (!class_exists(ThrottlingHttpClient::class)) {
diff --git a/src/Symfony/Bundle/FrameworkBundle/Resources/config/http_client.php b/src/Symfony/Bundle/FrameworkBundle/Resources/config/http_client.php
@@ -15,6 +15,7 @@
 use Psr\Http\Client\ClientInterface;
 use Psr\Http\Message\ResponseFactoryInterface;
 use Psr\Http\Message\StreamFactoryInterface;
+use Symfony\Component\Cache\Adapter\TagAwareAdapter;
 use Symfony\Component\HttpClient\HttpClient;
 use Symfony\Component\HttpClient\HttplugClient;
 use Symfony\Component\HttpClient\Messenger\PingWebhookMessageHandler;
@@ -25,6 +26,14 @@
 
 return static function (ContainerConfigurator $container) {
     $container->services()
+        ->set('cache.http_client.pool')
+            ->parent('cache.app')
+            ->tag('cache.pool')
+
+        ->set('cache.http_client', TagAwareAdapter::class)
+            ->args([service('cache.http_client.pool')])
+            ->tag('cache.taggable', ['pool' => 'cache.http_client.pool'])
+
         ->set('http_client.transport', HttpClientInterface::class)
             ->factory([HttpClient::class, 'create'])
             ->args([
diff --git a/src/Symfony/Bundle/FrameworkBundle/Resources/config/schema/symfony-1.0.xsd b/src/Symfony/Bundle/FrameworkBundle/Resources/config/schema/symfony-1.0.xsd
@@ -730,6 +730,7 @@
             <xsd:element name="header" type="http_header" minOccurs="0" maxOccurs="unbounded" />
             <xsd:element name="var" type="http_var" minOccurs="0" maxOccurs="unbounded" />
             <xsd:element name="peer-fingerprint" type="fingerprint" minOccurs="0" maxOccurs="unbounded" />
+            <xsd:element name="caching" type="http_client_caching" minOccurs="0" maxOccurs="1" />
             <xsd:element name="retry-failed" type="http_client_retry_failed" minOccurs="0" maxOccurs="1" />
             <xsd:element name="extra" type="xsd:anyType" minOccurs="0" maxOccurs="unbounded" />
         </xsd:choice>
@@ -757,6 +758,7 @@
             <xsd:element name="resolve" type="http_resolve" minOccurs="0" maxOccurs="unbounded" />
             <xsd:element name="header" type="http_header" minOccurs="0" maxOccurs="unbounded" />
             <xsd:element name="peer-fingerprint" type="fingerprint" minOccurs="0" maxOccurs="unbounded" />
+            <xsd:element name="caching" type="http_client_caching" minOccurs="0" maxOccurs="1" />
             <xsd:element name="retry-failed" type="http_client_retry_failed" minOccurs="0" maxOccurs="1" />
             <xsd:element name="extra" type="xsd:anyType" minOccurs="0" maxOccurs="unbounded" />
         </xsd:choice>
@@ -790,6 +792,13 @@
         </xsd:choice>
     </xsd:complexType>
 
+    <xsd:complexType name="http_client_caching">
+        <xsd:attribute name="enabled" type="xsd:boolean" />
+        <xsd:attribute name="cache-pool" type="xsd:string" />
+        <xsd:attribute name="shared" type="xsd:boolean" />
+        <xsd:attribute name="max-ttl" type="xsd:unsignedInt" />
+    </xsd:complexType>
+
     <xsd:complexType name="http_client_retry_failed">
         <xsd:sequence>
             <xsd:element name="http-code" type="http_client_retry_code" minOccurs="0" maxOccurs="unbounded" />
diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/DependencyInjection/Fixtures/php/http_client_caching.php b/src/Symfony/Bundle/FrameworkBundle/Tests/DependencyInjection/Fixtures/php/http_client_caching.php
@@ -0,0 +1,24 @@
+<?php
+
+$container->loadFromExtension('framework', [
+    'annotations' => false,
+    'http_method_override' => false,
+    'handle_all_throwables' => true,
+    'php_errors' => ['log' => true],
+    'http_client' => [
+        'default_options' => [
+            'headers' => ['X-powered' => 'PHP'],
+            'caching' => [
+                'cache_pool' => 'foo',
+                'shared' => false,
+                'max_ttl' => 2,
+            ],
+        ],
+        'scoped_clients' => [
+            'bar' => [
+                'base_uri' => 'https://example.com',
+                'caching' => ['cache_pool' => 'baz'],
+            ],
+        ],
+    ],
+]);
diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/DependencyInjection/Fixtures/xml/http_client_caching.xml b/src/Symfony/Bundle/FrameworkBundle/Tests/DependencyInjection/Fixtures/xml/http_client_caching.xml
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<container xmlns="https://symfony.com/schema/dic/services"
+           xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+           xmlns:framework="https://symfony.com/schema/dic/symfony"
+           xsi:schemaLocation="https://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd
+        https://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+    <framework:config http-method-override="false" handle-all-throwables="true">
+        <framework:annotations enabled="false" />
+        <framework:php-errors log="true" />
+        <framework:http-client>
+            <framework:default-options>
+                <framework:header name="X-powered">PHP</framework:header>
+                <framework:caching enabled="true" cache-pool="foo" shared="false" max-ttl="2"/>
+            </framework:default-options>
+            <framework:scoped-client name="bar" base-uri="https://example.com">
+                <framework:caching cache-pool="baz"/>
+            </framework:scoped-client>
+        </framework:http-client>
+    </framework:config>
+</container>
diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/DependencyInjection/Fixtures/yml/http_client_caching.yml b/src/Symfony/Bundle/FrameworkBundle/Tests/DependencyInjection/Fixtures/yml/http_client_caching.yml
@@ -0,0 +1,19 @@
+framework:
+  annotations: false
+  http_method_override: false
+  handle_all_throwables: true
+  php_errors:
+    log: true
+  http_client:
+    default_options:
+      headers:
+        X-powered: PHP
+      caching:
+        cache_pool: foo
+        shared: false
+        max_ttl: 2
+    scoped_clients:
+      bar:
+        base_uri: https://example.com
+        caching:
+          cache_pool: baz
diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/DependencyInjection/FrameworkExtensionTestCase.php b/src/Symfony/Bundle/FrameworkBundle/Tests/DependencyInjection/FrameworkExtensionTestCase.php
@@ -54,6 +54,8 @@
 use Symfony\Component\HtmlSanitizer\HtmlSanitizer;
 use Symfony\Component\HtmlSanitizer\HtmlSanitizerConfig;
 use Symfony\Component\HtmlSanitizer\HtmlSanitizerInterface;
+use Symfony\Component\HttpClient\CachingHttpClient;
+use Symfony\Component\HttpClient\Exception\ChunkCacheItemNotFoundException;
 use Symfony\Component\HttpClient\MockHttpClient;
 use Symfony\Component\HttpClient\RetryableHttpClient;
 use Symfony\Component\HttpClient\ScopingHttpClient;
@@ -2185,6 +2187,39 @@ public function testHttpClientOverrideDefaultOptions()
         $this->assertEquals($expected, $container->getDefinition('foo')->getArgument(2));
     }
 
+    public function testCachingHttpClient()
+    {
+        if (!class_exists(ChunkCacheItemNotFoundException::class)) {
+            $this->expectException(LogicException::class);
+        }
+
+        $container = $this->createContainerFromFile('http_client_caching');
+
+        $this->assertTrue($container->hasDefinition('http_client.caching'));
+        $definition = $container->getDefinition('http_client.caching');
+        $this->assertSame(CachingHttpClient::class, $definition->getClass());
+        $this->assertSame('http_client', $definition->getDecoratedService()[0]);
+        $this->assertCount(5, $arguments = $definition->getArguments());
+        $this->assertInstanceOf(Reference::class, $arguments[0]);
+        $this->assertSame('http_client.caching.inner', (string) $arguments[0]);
+        $this->assertInstanceOf(Reference::class, $arguments[1]);
+        $this->assertSame('foo', (string) $arguments[1]);
+        $this->assertArrayHasKey('headers', $arguments[2]);
+        $this->assertSame(['X-powered' => 'PHP'], $arguments[2]['headers']);
+        $this->assertFalse($arguments[3]);
+        $this->assertSame(2, $arguments[4]);
+
+        $this->assertTrue($container->hasDefinition('bar.caching'));
+        $definition = $container->getDefinition('bar.caching');
+        $this->assertSame(CachingHttpClient::class, $definition->getClass());
+        $this->assertSame('bar', $definition->getDecoratedService()[0]);
+        $arguments = $definition->getArguments();
+        $this->assertInstanceOf(Reference::class, $arguments[0]);
+        $this->assertSame('bar.caching.inner', (string) $arguments[0]);
+        $this->assertInstanceOf(Reference::class, $arguments[1]);
+        $this->assertSame('baz', (string) $arguments[1]);
+    }
+
     public function testHttpClientRetry()
     {
         $container = $this->createContainerFromFile('http_client_retry');
diff --git a/src/Symfony/Component/HttpClient/CHANGELOG.md b/src/Symfony/Component/HttpClient/CHANGELOG.md
@@ -5,6 +5,8 @@ CHANGELOG
 ---
 
  * Deprecate using amphp/http-client < 5
+ * Add RFC 9111–based caching support to `CachingHttpClient`
+ * Deprecate passing an instance of `StoreInterface` as `$cache` argument to `CachingHttpClient` constructor
 
 7.3
 ---
diff --git a/src/Symfony/Component/HttpClient/Caching/Freshness.php b/src/Symfony/Component/HttpClient/Caching/Freshness.php
@@ -0,0 +1,35 @@
+<?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\HttpClient\Caching;
+
+/**
+ * @internal
+ */
+enum Freshness
+{
+    /**
+     * The cached response is fresh and can be used without revalidation.
+     */
+    case Fresh;
+    /**
+     * The cached response is stale and must be revalidated before use.
+     */
+    case MustRevalidate;
+    /**
+     * The cached response is stale and should not be used.
+     */
+    case Stale;
+    /**
+     * The cached response is stale but may be used as a fallback in case of errors.
+     */
+    case StaleButUsable;
+}
diff --git a/src/Symfony/Component/HttpClient/CachingHttpClient.php b/src/Symfony/Component/HttpClient/CachingHttpClient.php
diff --git a/src/Symfony/Component/HttpClient/Exception/ChunkCacheItemNotFoundException.php b/src/Symfony/Component/HttpClient/Exception/ChunkCacheItemNotFoundException.php
diff --git a/src/Symfony/Component/HttpClient/Tests/CachingHttpClientTest.php b/src/Symfony/Component/HttpClient/Tests/CachingHttpClientTest.php
diff --git a/src/Symfony/Component/HttpClient/Tests/LegacyCachingHttpClientTest.php b/src/Symfony/Component/HttpClient/Tests/LegacyCachingHttpClientTest.php
diff --git a/src/Symfony/Component/HttpClient/composer.json b/src/Symfony/Component/HttpClient/composer.json
