From fb86deb23d11c84c2477bbff479432f51c1278bb Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Thu, 29 Oct 2020 20:16:59 +0100 Subject: [PATCH 1/5] Update http_client.rst I started from scratch after https://github.com/symfony/symfony-docs/pull/14174 * The most important change is that the old text "your code is expected to handle it" didn't make it clear *how* people are supposed to handle it. * I omitted the note that a `Symfony\Component\HttpClient\Exception\ClientException` is thrown. Is this important? Or is the existing `Symfony\\Contracts\\HttpClient\\Exception\\HttpExceptionInterface` enough? --- http_client.rst | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/http_client.rst b/http_client.rst index 7591152da85..6c2ad3d4c1f 100644 --- a/http_client.rst +++ b/http_client.rst @@ -891,20 +891,21 @@ Handling Exceptions ~~~~~~~~~~~~~~~~~~~ When the HTTP status code of the response is in the 300-599 range (i.e. 3xx, -4xx or 5xx) your code is expected to handle it. If you don't do that, the -``getHeaders()``, ``getContent()`` and ``toArray()`` methods throw an appropriate exception, all of -which implement the :class:`Symfony\\Contracts\\HttpClient\\Exception\\HttpExceptionInterface`:: +4xx or 5xx), the ``getHeaders()``, ``getContent()`` and ``toArray()`` methods +throw an appropriate exception, all of which implement the +:class:`Symfony\\Contracts\\HttpClient\\Exception\\HttpExceptionInterface`. - // the response of this request will be a 403 HTTP error - $response = $client->request('GET', 'https://httpbin.org/status/403'); +You can prevent the exception from being thrown by either: - // this code results in a Symfony\Component\HttpClient\Exception\ClientException - // because it doesn't check the status code of the response - $content = $response->getContent(); +* Checking for the exact status code:: + + $response = $client->request('GET', 'https://httpbin.org/status/403'); + if ('403' === $response->getStatusCode()) { + $response->getContent(); + } - // pass FALSE as the optional argument to not throw an exception and return - // instead the original response content (even if it's an error message) - $content = $response->getContent(false); +* Or passing ``false`` as the optional argument to the methods, e.g. +``$response->getHeaders(false);`` While responses are lazy, their destructor will always wait for headers to come back. This means that the following request *will* complete; and if e.g. a 404 From 4baa60d8a2a2bc3862927e165c19bdaccfdc2a56 Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Thu, 29 Oct 2020 20:26:53 +0100 Subject: [PATCH 2/5] Update http_client.rst --- http_client.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/http_client.rst b/http_client.rst index 6c2ad3d4c1f..0b1896ff731 100644 --- a/http_client.rst +++ b/http_client.rst @@ -904,8 +904,7 @@ You can prevent the exception from being thrown by either: $response->getContent(); } -* Or passing ``false`` as the optional argument to the methods, e.g. -``$response->getHeaders(false);`` +* Or passing ``false`` as the optional argument to the methods, e.g. ``$response->getHeaders(false);`` While responses are lazy, their destructor will always wait for headers to come back. This means that the following request *will* complete; and if e.g. a 404 From b2eef6c2434109f50b7d1225b4bada50199e387e Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Thu, 29 Oct 2020 20:29:15 +0100 Subject: [PATCH 3/5] Update http_client.rst --- http_client.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/http_client.rst b/http_client.rst index 0b1896ff731..d7b917688a5 100644 --- a/http_client.rst +++ b/http_client.rst @@ -900,7 +900,7 @@ You can prevent the exception from being thrown by either: * Checking for the exact status code:: $response = $client->request('GET', 'https://httpbin.org/status/403'); - if ('403' === $response->getStatusCode()) { + if (403 === $response->getStatusCode()) { $response->getContent(); } From 9b8789924f508b1debc9cbcf7ddf954b3740c0ed Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Thu, 29 Oct 2020 22:08:03 +0100 Subject: [PATCH 4/5] Update http_client.rst --- http_client.rst | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/http_client.rst b/http_client.rst index d7b917688a5..f2e60c407ae 100644 --- a/http_client.rst +++ b/http_client.rst @@ -895,16 +895,12 @@ When the HTTP status code of the response is in the 300-599 range (i.e. 3xx, throw an appropriate exception, all of which implement the :class:`Symfony\\Contracts\\HttpClient\\Exception\\HttpExceptionInterface`. -You can prevent the exception from being thrown by either: +To prevent the exception from being thrown, you need to pass ``false`` as the optional argument +to every call of those methods, e.g. ``$response->getHeaders(false);``. -* Checking for the exact status code:: - - $response = $client->request('GET', 'https://httpbin.org/status/403'); - if (403 === $response->getStatusCode()) { - $response->getContent(); - } - -* Or passing ``false`` as the optional argument to the methods, e.g. ``$response->getHeaders(false);`` +If you do not call any of these 3 methods at all, the exception will still be thrown +when the Symfony kernel delivers the final response. +You can prevent this by calling ``$response->getStatusCode()``. While responses are lazy, their destructor will always wait for headers to come back. This means that the following request *will* complete; and if e.g. a 404 From b1aad97767e3dda6feb47228ca16362b1dc14b63 Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Wed, 19 May 2021 18:15:11 +0200 Subject: [PATCH 5/5] Update http_client.rst --- http_client.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/http_client.rst b/http_client.rst index f2e60c407ae..39aee19ad45 100644 --- a/http_client.rst +++ b/http_client.rst @@ -895,12 +895,14 @@ When the HTTP status code of the response is in the 300-599 range (i.e. 3xx, throw an appropriate exception, all of which implement the :class:`Symfony\\Contracts\\HttpClient\\Exception\\HttpExceptionInterface`. -To prevent the exception from being thrown, you need to pass ``false`` as the optional argument -to every call of those methods, e.g. ``$response->getHeaders(false);``. +To opt-out from this exception and deal with 300-599 status codes on your own, +pass ``false`` as the optional argument to every call of those methods, +e.g. ``$response->getHeaders(false);``. If you do not call any of these 3 methods at all, the exception will still be thrown -when the Symfony kernel delivers the final response. -You can prevent this by calling ``$response->getStatusCode()``. +when the ``$response`` object is destructed (i.e. when the Symfony kernel delivers the final response). +Calling ``$response->getStatusCode()`` is enough to disable this behavior +(but then don't miss checking the status code yourself). While responses are lazy, their destructor will always wait for headers to come back. This means that the following request *will* complete; and if e.g. a 404