Merge branch '7.4' into 8.0

* 7.4:
  Minor tweaks
  [HttpClient] Document `CachingHttpClient` compatible with RFC 9111

Author: javiereguiluz

http_client.rst

@@ -619,6 +619,8 @@ making a request. Use the ``max_redirects`` setting to configure this behavior
         'max_redirects' => 0,
     ]);
 
+.. _http-client-retry-failed-requests:
+
 Retry Failed Requests
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -1331,29 +1333,114 @@ in the foreach loop::
         }
     }
 
+.. _http-client_caching:
+
 Caching Requests and Responses
 ------------------------------
 
 This component provides a :class:`Symfony\\Component\\HttpClient\\CachingHttpClient`
-decorator that allows caching responses and serving them from the local storage
-for next requests. The implementation leverages the
-:class:`Symfony\\Component\\HttpKernel\\HttpCache\\HttpCache` class under the hood
-so that the :doc:`HttpKernel component </components/http_kernel>` needs to be
-installed in your application::
+decorator that enables caching of HTTP responses and serving them from cache
+storage on subsequent requests, as described in `RFC 9111`_.
 
-    use Symfony\Component\HttpClient\CachingHttpClient;
-    use Symfony\Component\HttpClient\HttpClient;
-    use Symfony\Component\HttpKernel\HttpCache\Store;
+Internally, it relies on a :class:`tag aware cache <Symfony\\Contracts\\Cache\\TagAwareCacheInterface>`,
+so the :doc:`Cache component </components/cache>` must be installed in your application.
 
-    $store = new Store('/path/to/cache/storage/');
-    $client = HttpClient::create();
-    $client = new CachingHttpClient($client, $store);
+.. tip::
+
+    The caching mechanism is asynchronous. The response must be fully consumed
+    (for example, by calling ``getContent()`` or using a stream) for it to be
+    stored in the cache.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/framework.yaml
+        framework:
+            http_client:
+                scoped_clients:
+                    example.client:
+                        base_uri: 'https://example.com'
+                        caching:
+                            cache_pool: example_cache_pool
+
+            cache:
+                pools:
+                    example_cache_pool:
+                        adapter: cache.adapter.redis_tag_aware
+                        tags: true
+
+    .. code-block:: xml
+
+        <!-- config/packages/framework.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <framework:config>
+                <framework:http-client>
+                    <framework:scoped-client name="example.client"
+                        base-uri="https://example.com"
+                    >
+                        <framework:caching cache-pool="example_cache_pool"/>
+                    </framework:scoped-client>
+                </framework:http-client>
+
+                <framework:cache>
+                    <framework:pool name="example_cache_pool"
+                        adapter="cache.adapter.redis_tag_aware"
+                        tags="true"
+                    />
+                </framework:cache>
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/framework.php
+        use Symfony\Config\FrameworkConfig;
+
+        return static function (FrameworkConfig $framework): void {
+            $framework->httpClient()->scopedClient('example.client')
+                ->baseUri('https://example.com')
+                ->caching()
+                    ->cachePool('example_cache_pool')
+                // ...
+            ;
+
+            $framework->cache()
+                ->pool('example_cache_pool')
+                    ->adapter('cache.adapter.redis_tag_aware')
+                    ->tags(true)
+                ;
+        };
+
+    .. code-block:: php-standalone
+
+        use Symfony\Component\Cache\Adapter\FilesystemTagAwareAdapter;
+        use Symfony\Component\HttpClient\CachingHttpClient;
+        use Symfony\Component\HttpClient\HttpClient;
+
+        $cache = new FilesystemTagAwareAdapter();
+
+        $client = HttpClient::createForBaseUri('https://example.com');
+        $cachingClient = new CachingHttpClient($client, $cache);
+
+.. tip::
+
+    It is strongly recommended to configure a
+    :ref:`retry strategy <http-client-retry-failed-requests>` to gracefully
+    handle temporary cache inconsistencies or validation failures.
 
-    // this won't hit the network if the resource is already in the cache
-    $response = $client->request('GET', 'https://example.com/cacheable-resource');
+.. versionadded:: 7.4
 
-:class:`Symfony\\Component\\HttpClient\\CachingHttpClient` accepts a third argument
-to set the options of the :class:`Symfony\\Component\\HttpKernel\\HttpCache\\HttpCache`.
+    In Symfony 7.4, caching was refactored to comply with `RFC 9111`_ and to
+    leverage the :doc:`Cache component </components/cache>`. In previous versions,
+    it relied on ``HttpCache`` from the HttpKernel component.
 
 Limit the Number of Requests
 ----------------------------
@@ -2286,5 +2373,6 @@ body::
 .. _`idempotent method`: https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Idempotent_methods
 .. _`SSRF`: https://portswigger.net/web-security/ssrf
 .. _`RFC 6570`: https://www.rfc-editor.org/rfc/rfc6570
+.. _`RFC 9111`: https://www.rfc-editor.org/rfc/rfc9111
 .. _`HAR`: https://w3c.github.io/web-performance/specs/HAR/Overview.html
 .. _`the Cookie HTTP request header`: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cookie

reference/configuration/framework.rst

@@ -1335,6 +1335,88 @@ If this option is a boolean value, the response is buffered when the value is
 returned value is ``true`` (the closure receives as argument an array with the
 response headers).
 
+caching
+.......
+
+**type**: ``array``
+
+This option configures the behavior of the :ref:`HTTP client caching <http-client_caching>`,
+including which types of requests to cache and how many times. The behavior is
+defined with the following options:
+
+* :ref:`cache_pool <reference-http-client-caching-cache-pool>`
+* :ref:`shared <reference-http-client-caching-shared>`
+* :ref:`max_ttl <reference-http-client-caching-max-ttl>`
+
+.. code-block:: yaml
+
+    # config/packages/framework.yaml
+    framework:
+        # ...
+        http_client:
+            # ...
+            default_options:
+                caching:
+                    cache_pool: cache.app
+                    shared: true
+                    max_ttl: 86400
+
+            scoped_clients:
+                my_api.client:
+                    # ...
+                    caching:
+                        cache_pool: my_taggable_pool
+
+.. versionadded:: 7.4
+
+    The ``caching`` option was introduced in Symfony 7.4.
+
+.. _reference-http-client-caching-cache-pool:
+
+cache_pool
+""""""""""
+
+**type**: ``string``
+
+The service ID of the cache pool used to store the cached responses. The service
+must implement the :class:`Symfony\\Contracts\\Cache\\TagAwareCacheInterface`.
+
+By default, it uses an instance of :class:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapter`
+wrapping the ``cache.app`` pool.
+
+.. versionadded:: 7.4
+
+    The ``cache_pool`` option was introduced in Symfony 7.4.
+
+.. _reference-http-client-caching-shared:
+
+shared
+""""""
+
+**type**: ``boolean`` **default**: ``true``
+
+If ``true``, it uses a `shared cache`_ so cached responses can be reused across
+users. Set it to ``false`` to use a `private cache`_.
+
+.. versionadded:: 7.4
+
+    The ``shared`` option was introduced in Symfony 7.4.
+
+.. _reference-http-client-caching-max-ttl:
+
+max_ttl
+"""""""
+
+**type**: ``integer`` **default**: ``null``
+
+The maximum time-to-live (in seconds) for cached responses. By default, responses
+are cached for as long as the TTL specified by the server. When this option is
+set, server-provided TTLs are capped to this value.
+
+.. versionadded:: 7.4
+
+    The ``max_ttl`` option was introduced in Symfony 7.4.
+
 cafile
 ......
 
@@ -3403,3 +3485,5 @@ to know their differences.
 .. _`Link HTTP header`: https://tools.ietf.org/html/rfc5988
 .. _`SMTP session`: https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol#SMTP_transport_example
 .. _`PHP attributes`: https://www.php.net/manual/en/language.attributes.overview.php
+.. _`public cache`: https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Caching#shared_cache
+.. _`private cache`: https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Caching#private_caches