[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,38 @@ 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.
+A generator can also be passed instead.
 
-    $response = $httpClient->request('POST', 'https://...', [
-        'json' => ['param1' => 'value1', '...'],
+.. 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 +283,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 +332,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 answer 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 +581,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``.