[HttpClient] doc how to cancel a request + upload files

Author: nicolas-grekas

components/http_client.rst

@@ -186,7 +186,7 @@ processed automatically when making the requests::
         'body' => ['parameter1' => 'value1', '...'],
 
         // using a closure to generate the uploaded data
-        'body' => function () {
+        'body' => function (int $size): string {
             // ...
         },
 
@@ -199,12 +199,39 @@ When uploading data with the ``POST`` method, if you don't define the
 form data and adds the required
 ``'Content-Type: application/x-www-form-urlencoded'`` header for you.
 
-When uploading JSON payloads, use the ``json`` option instead of ``body``. The
-given content will be JSON-encoded automatically and the request will add the
-``Content-Type: application/json`` automatically too::
+When the `body` option is set as a closure, it will be called several times until
+it returns the empty string, which signals the end of the body. Each time, the
+closure should return a string smaller than the amount requested as argument.
 
-    $response = $httpClient->request('POST', 'https://...', [
-        'json' => ['param1' => 'value1', '...'],
+A generator or any ``Traversable`` can also be used instead of a closure.
+
+.. tip::
+
+    When uploading JSON payloads, use the ``json`` option instead of ``body``. The
+    given content will be JSON-encoded automatically and the request will add the
+    ``Content-Type: application/json`` automatically too::
+
+        $response = $httpClient->request('POST', 'https://...', [
+            'json' => ['param1' => 'value1', '...'],
+        ]);
+
+        $decodedPayload = $response->toArray();
+
+To submit a form with file uploads, it is your responsibility to encode the body
+according to the ``multipart/form-data`` content-type. The
+:doc:`Symfony Mime </components/mime>` component makes it a few lines of code::
+
+    use Symfony\Component\Mime\Part\DataPart;
+    use Symfony\Component\Mime\Part\Multipart\FormDataPart;
+
+    $formFields = [
+        'regular_field' => 'some value',
+        'file_field' => DataPart::fromPath('/path/to/uploaded/file'),
+    ];
+    $formData = new FormDataPart($formFields);
+    $client->request('POST', 'https://...', [
+        'headers' => $formData->getPreparedHeaders()->toArray(),
+        'body' => $formData->bodyToIterable(),
     ]);
 
 Cookies
@@ -257,6 +284,9 @@ following methods::
     // gets the response body as a string
     $content = $response->getContent();
 
+    // cancels the request/response
+    $response->cancel();
+
     // returns info coming from the transport layer, such as "response_headers",
     // "redirect_count", "start_time", "redirect_url", etc.
     $httpInfo = $response->getInfo();
@@ -303,6 +333,29 @@ response sequentially instead of waiting for the entire response::
         fwrite($fileHandler, $chunk->getContent());
     }
 
+Canceling Responses
+~~~~~~~~~~~~~~~~~~~
+
+To abort a request (e.g. because it didn't complete in due time, or you want to
+fetch only the first bytes of the response, etc.), you can either:
+
+* use the ``cancel()`` method of ``ResponseInterface``::
+
+      $response->cancel()
+
+* throw an exception from a progress callback::
+
+      $response = $client->request('GET', 'https://..;', [
+        'on_progress' => function (int $dlNow, int $dlSize, array $info): void {
+            // ...
+
+            throw new \MyException();
+        },
+      ]);
+
+  The exception will be wrapped in a ``TransportExceptionInterface`` and will
+  abort the request.
+
 Handling Exceptions
 ~~~~~~~~~~~~~~~~~~~
 
@@ -529,7 +582,7 @@ PSR-18 Compatibility
 --------------------
 
 This component uses and implements abstractions defined by the
-``symfony/contracts`` package. It also implements the `PSR-18`_ (HTTP Client)
+``symfony/http-client-contracts``. It also implements the `PSR-18`_ (HTTP Client)
 specifications via the :class:`Symfony\\Component\\HttpClient\\Psr18Client`
 class, which is an adapter to turn a Symfony ``HttpClientInterface`` into a
 PSR-18 ``ClientInterface``.

reference/configuration/framework.rst

@@ -699,7 +699,7 @@ This service can be configured using ``framework.http_client.default_options``:
         http_client:
             max_host_connections: 10
             default_options:
-                headers: [{ 'X-Powered-By': 'ACME App' }]
+                headers: { 'X-Powered-By': 'ACME App' }
                 max_redirects: 7
 
 .. _reference-http-client-scoped-clients: