feature #30499 [HttpClient] add ResponseInterface::toArray() (nicolas-grekas)

This PR was merged into the 4.3-dev branch.

Discussion
----------

[HttpClient] add ResponseInterface::toArray()

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | -
| License       | MIT
| Doc PR        | -

I'd like we discuss adding a `toArray()` method to `ResponseInterface`.

JSON responses are so common when doing server-side requests that this may help remove boilerplate - especially the logic dealing with errors.

WDYT?

(about flags, I don't think we should make them configurable: if one really needs to deal with custom flags, there's always `ResponseInterface::getContent()` - but it should be very rare.).

Commits
-------

aabd1d455e [HttpClient] add ResponseInterface::toArray()

Author: nicolas-grekas

ResponseInterface.php

@@ -59,6 +59,18 @@ public function getHeaders(bool $throw = true): array;
      */
     public function getContent(bool $throw = true): string;
 
+    /**
+     * Gets the response body decoded as array, typically from a JSON payload.
+     *
+     * @param bool $throw Whether an exception should be thrown on 3/4/5xx status codes
+     *
+     * @throws TransportExceptionInterface   When the body cannot be decoded or when a network error occurs
+     * @throws RedirectionExceptionInterface On a 3xx when $throw is true and the "max_redirects" option has been reached
+     * @throws ClientExceptionInterface      On a 4xx when $throw is true
+     * @throws ServerExceptionInterface      On a 5xx when $throw is true
+     */
+    public function toArray(bool $throw = true): array;
+
     /**
      * Returns info coming from the transport layer.
      *

Test/HttpClientTestCase.php

@@ -58,6 +58,7 @@ public function testGetRequest()
         $this->assertSame(['application/json'], $headers['content-type']);
 
         $body = json_decode($response->getContent(), true);
+        $this->assertSame($body, $response->toArray());
 
         $this->assertSame('HTTP/1.1', $body['SERVER_PROTOCOL']);
         $this->assertSame('/', $body['REQUEST_URI']);
@@ -79,7 +80,7 @@ public function testNonBufferedGetRequest()
             'headers' => ['Foo' => 'baR'],
         ]);
 
-        $body = json_decode($response->getContent(), true);
+        $body = $response->toArray();
         $this->assertSame('baR', $body['HTTP_FOO']);
 
         $this->expectException(TransportExceptionInterface::class);
@@ -106,7 +107,7 @@ public function testHttpVersion()
         $this->assertSame(200, $response->getStatusCode());
         $this->assertSame('HTTP/1.0 200 OK', $response->getInfo('raw_headers')[0]);
 
-        $body = json_decode($response->getContent(), true);
+        $body = $response->toArray();
 
         $this->assertSame('HTTP/1.0', $body['SERVER_PROTOCOL']);
         $this->assertSame('GET', $body['REQUEST_METHOD']);
@@ -203,7 +204,7 @@ public function testInlineAuth()
         $client = $this->getHttpClient();
         $response = $client->request('GET', 'http://foo:bar%3Dbar@localhost:8057');
 
-        $body = json_decode($response->getContent(), true);
+        $body = $response->toArray();
 
         $this->assertSame('foo', $body['PHP_AUTH_USER']);
         $this->assertSame('bar=bar', $body['PHP_AUTH_PW']);
@@ -219,7 +220,7 @@ public function testRedirects()
             },
         ]);
 
-        $body = json_decode($response->getContent(), true);
+        $body = $response->toArray();
         $this->assertSame('GET', $body['REQUEST_METHOD']);
         $this->assertSame('Basic Zm9vOmJhcg==', $body['HTTP_AUTHORIZATION']);
         $this->assertSame('http://localhost:8057/', $response->getInfo('url'));
@@ -250,7 +251,8 @@ public function testRelativeRedirects()
         $client = $this->getHttpClient();
         $response = $client->request('GET', 'http://localhost:8057/302/relative');
 
-        $body = json_decode($response->getContent(), true);
+        $body = $response->toArray();
+
         $this->assertSame('/', $body['REQUEST_URI']);
         $this->assertNull($response->getInfo('redirect_url'));
 
@@ -279,7 +281,7 @@ public function testRedirect307()
             'body' => 'foo=bar',
         ]);
 
-        $body = json_decode($response->getContent(), true);
+        $body = $response->toArray();
 
         $this->assertSame(['foo' => 'bar', 'REQUEST_METHOD' => 'POST'], $body);
     }
@@ -388,7 +390,7 @@ public function testOnProgress()
             'on_progress' => function (...$state) use (&$steps) { $steps[] = $state; },
         ]);
 
-        $body = json_decode($response->getContent(), true);
+        $body = $response->toArray();
 
         $this->assertSame(['foo' => '0123456789', 'REQUEST_METHOD' => 'POST'], $body);
         $this->assertSame([0, 0], \array_slice($steps[0], 0, 2));
@@ -405,7 +407,7 @@ public function testPostArray()
             'body' => ['foo' => 'bar'],
         ]);
 
-        $this->assertSame(['foo' => 'bar', 'REQUEST_METHOD' => 'POST'], json_decode($response->getContent(), true));
+        $this->assertSame(['foo' => 'bar', 'REQUEST_METHOD' => 'POST'], $response->toArray());
     }
 
     public function testPostResource()
@@ -420,7 +422,7 @@ public function testPostResource()
             'body' => $h,
         ]);
 
-        $body = json_decode($response->getContent(), true);
+        $body = $response->toArray();
 
         $this->assertSame(['foo' => '0123456789', 'REQUEST_METHOD' => 'POST'], $body);
     }
@@ -438,7 +440,7 @@ public function testPostCallback()
             },
         ]);
 
-        $this->assertSame(['foo' => '0123456789', 'REQUEST_METHOD' => 'POST'], json_decode($response->getContent(), true));
+        $this->assertSame(['foo' => '0123456789', 'REQUEST_METHOD' => 'POST'], $response->toArray());
     }
 
     public function testOnProgressCancel()
@@ -581,15 +583,15 @@ public function testProxy()
             'proxy' => 'http://localhost:8057',
         ]);
 
-        $body = json_decode($response->getContent(), true);
+        $body = $response->toArray();
         $this->assertSame('localhost:8057', $body['HTTP_HOST']);
         $this->assertRegexp('#^http://(localhost|127\.0\.0\.1):8057/$#', $body['REQUEST_URI']);
 
         $response = $client->request('GET', 'http://localhost:8057/', [
             'proxy' => 'http://foo:b%3Dar@localhost:8057',
         ]);
 
-        $body = json_decode($response->getContent(), true);
+        $body = $response->toArray();
         $this->assertSame('Basic Zm9vOmI9YXI=', $body['HTTP_PROXY_AUTHORIZATION']);
     }
 
@@ -603,7 +605,7 @@ public function testNoProxy()
                 'proxy' => 'http://localhost:8057',
             ]);
 
-            $body = json_decode($response->getContent(), true);
+            $body = $response->toArray();
 
             $this->assertSame('HTTP/1.1', $body['SERVER_PROTOCOL']);
             $this->assertSame('/', $body['REQUEST_URI']);
@@ -629,7 +631,7 @@ public function testAutoEncodingRequest()
         $this->assertSame(['Accept-Encoding'], $headers['vary']);
         $this->assertContains('gzip', $headers['content-encoding'][0]);
 
-        $body = json_decode($response->getContent(), true);
+        $body = $response->toArray();
 
         $this->assertContains('gzip', $body['HTTP_ACCEPT_ENCODING']);
     }
@@ -652,7 +654,7 @@ public function testQuery()
             'query' => ['b' => 'b'],
         ]);
 
-        $body = json_decode($response->getContent(), true);
+        $body = $response->toArray();
         $this->assertSame('GET', $body['REQUEST_METHOD']);
         $this->assertSame('/?a=a&b=b', $body['REQUEST_URI']);
     }
@@ -673,10 +675,9 @@ public function testUserlandEncodingRequest()
         $this->assertContains('gzip', $headers['content-encoding'][0]);
 
         $body = $response->getContent();
-
         $this->assertSame("\x1F", $body[0]);
-        $body = json_decode(gzdecode($body), true);
 
+        $body = json_decode(gzdecode($body), true);
         $this->assertSame('gzip', $body['HTTP_ACCEPT_ENCODING']);
     }