HTTP 用戶端

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

$response = $client->request('POST', 'https://...', [
    // defining data using a regular string
    'body' => 'raw data',

    // defining data using an array of parameters
    'body' => ['parameter1' => 'value1', '...'],

    // using a closure to generate the uploaded data
    'body' => function (int $size): string {
        // ...
    },

    // using a resource to get the data from it
    'body' => fopen('/path/to/file', 'r'),
]);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

use Symfony\Component\HttpClient\HttpClient;
use Symfony\Component\HttpFoundation\Cookie;

$client = HttpClient::create([
    'headers' => [
        // set one cookie as a name=value pair
        'Cookie' => 'flavor=chocolate',

        // you can set multiple cookies at once separating them with a ;
        'Cookie' => 'flavor=chocolate; size=medium',

        // if needed, encode the cookie value to ensure that it contains valid characters
        'Cookie' => sprintf("%s=%s", 'foo', rawurlencode('...')),
    ],
]);

1
2
3
4
5
6
7
8
9
10
11
12
13
14

use Symfony\Component\HttpClient\HttpClient;
use Symfony\Component\HttpClient\NoPrivateNetworkHttpClient;

$client = new NoPrivateNetworkHttpClient(HttpClient::create());
// nothing changes when requesting public networks
$client->request('GET', 'https://example.com/');

// however, all requests to private networks are now blocked by default
$client->request('GET', 'https://127.0.0.1/');

// the second optional argument defines the networks to block
// in this example, requests from 104.26.14.0 to 104.26.15.255 will result in an exception
// but all the other requests, including other internal networks, will be allowed
$client = new NoPrivateNetworkHttpClient(HttpClient::create(), ['104.26.14.0/23']);

1
2
3
4
5
6
7
8
9
10
11
12

use Symfony\Component\HttpClient\AmpHttpClient;
use Symfony\Component\HttpClient\CurlHttpClient;
use Symfony\Component\HttpClient\NativeHttpClient;

// uses native PHP streams
$client = new NativeHttpClient();

// uses the cURL PHP extension
$client = new CurlHttpClient();

// uses the client from the `amphp/http-client` package
$client = new AmpHttpClient();

1
2
3
4
5
6
7
8
9
10
11
12

use Symfony\Component\HttpClient\CurlHttpClient;

$client = new CurlHttpClient();

$client->request('POST', 'https://...', [
    // ...
    'extra' => [
        'curl' => [
            CURLOPT_IPRESOLVE => CURL_IPRESOLVE_V6,
        ],
    ],
]);

1
2
3
4
5
6
7
8
9
10
11
12
13
14

$url = 'https://releases.ubuntu.com/18.04.1/ubuntu-18.04.1-desktop-amd64.iso';
$response = $client->request('GET', $url);

// Responses are lazy: this code is executed as soon as headers are received
if (200 !== $response->getStatusCode()) {
    throw new \Exception('...');
}

// get the response content in chunks and save them in a file
// response chunks implement Symfony\Contracts\HttpClient\ChunkInterface
$fileHandler = fopen('/ubuntu.iso', 'w');
foreach ($client->stream($response) as $chunk) {
    fwrite($fileHandler, $chunk->getContent());
}

1
2
3
4
5
6
7
8
9
10
11
12

foreach ($client->stream($responses) as $response => $chunk) {
    if ($chunk->isFirst()) {
        // headers of $response just arrived
        // $response->getHeaders() is now a non-blocking call
    } elseif ($chunk->isLast()) {
        // the full content of $response just completed
        // $response->getContent() is now a non-blocking call
    } else {
        // $chunk->getContent() will return a piece
        // of the response body that just arrived
    }
}

1
2
3
4
5
6
7
8
9
10
11

use Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface;

// ...
try {
    // both lines can potentially throw
    $response = $client->request(/* ... */);
    $headers = $response->getHeaders();
    // ...
} catch (TransportExceptionInterface $e) {
    // ...
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

foreach ($client->stream($responses) as $response => $chunk) {
    try {
        if ($chunk->isTimeout()) {
            // ... decide what to do when a timeout occurs
            // if you want to stop a response that timed out, don't miss
            // calling $response->cancel() or the destructor of the response
            // will try to complete it one more time
        } elseif ($chunk->isFirst()) {
            // if you want to check the status code, you must do it when the
            // first chunk arrived, using $response->getStatusCode();
            // not doing so might trigger an HttpExceptionInterface
        } elseif ($chunk->isLast()) {
            // ... do something with $response
        }
    } catch (TransportExceptionInterface $e) {
        // ...
    }
}

1
2
3
4
5
6
7
8
9
10
11

use Symfony\Contracts\HttpClient\HttpClientInterface;

class MyApiLayer
{
    public function __construct(
        private HttpClientInterface $client,
    ) {
    }

    // [...]
}

1
2
3
4
5
6
7
8
9
10
11
12
13

use Symfony\Component\HttpClient\Psr18Client;

$client = (new Psr18Client())
    ->withOptions([
        'base_uri' => 'https://symfony.dev.org.tw',
        'headers' => [
            'Accept' => 'application/json',
        ],
    ]);

$request = $client->createRequest('GET', '/versions.json');

// ...

1
2
3
4
5
6
7
8
9
10
11

use Http\Client\HttpClient;
use Http\Message\StreamFactory;

class SomeSdk
{
    public function __construct(
        HttpClient $httpClient,
        StreamFactory $streamFactory
    )
    // [...]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

use Psr\Http\Message\ResponseInterface;
use Symfony\Component\HttpClient\HttplugClient;

$httpClient = new HttplugClient();
$request = $httpClient->createRequest('GET', 'https://my.api.com/');
$promise = $httpClient->sendAsyncRequest($request)
    ->then(
        function (ResponseInterface $response): ResponseInterface {
            echo 'Got status '.$response->getStatusCode();

            return $response;
        },
        function (\Throwable $exception): never {
            echo 'Error: '.$exception->getMessage();

            throw $exception;
        }
    );

// after you're done with sending several requests,
// you must wait for them to complete concurrently

// wait for a specific promise to resolve while monitoring them all
$response = $promise->wait();

// wait maximum 1 second for pending promises to resolve
$httpClient->wait(1.0);

// wait for all remaining promises to resolve
$httpClient->wait();

1
2
3
4
5
6
7
8
9
10

use Psr\Http\Message\ResponseInterface;
use Symfony\Component\HttpClient\HttplugClient;

$httpClient = (new HttplugClient())
    ->withOptions([
        'base_uri' => 'https://my.api.com',
    ]);
$request = $httpClient->createRequest('GET', '/');

// ...

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

use Symfony\Component\HttpClient\HttpClient;
use Symfony\Component\HttpClient\Response\StreamWrapper;

$client = HttpClient::create();
$response = $client->request('GET', 'https://symfony.dev.org.tw/versions.json');

$streamResource = StreamWrapper::createResource($response, $client);

// alternatively and contrary to the previous one, this returns
// a resource that is seekable and potentially stream_select()-able
$streamResource = $response->toStream();

echo stream_get_contents($streamResource); // outputs the content of the response

// later on if you need to, you can access the response from the stream
$response = stream_get_meta_data($streamResource)['wrapper_data']->getResponse();

1
2
3
4
5
6
7
8
9
10
11
12

use Symfony\Component\HttpClient\MockHttpClient;
use Symfony\Component\HttpClient\Response\MockResponse;

$responses = [
    new MockResponse($body1, $info1),
    new MockResponse($body2, $info2),
];

$client = new MockHttpClient($responses);
// responses are returned in the same order as passed to MockHttpClient
$response1 = $client->request('...'); // returns $responses[0]
$response2 = $client->request('...'); // returns $responses[1]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

$expectedRequests = [
    function ($method, $url, $options): MockResponse {
        $this->assertSame('GET', $method);
        $this->assertSame('https://example.com/api/v1/customer', $url);

        return new MockResponse('...');
    },
    function ($method, $url, $options): MockResponse {
        $this->assertSame('POST', $method);
        $this->assertSame('https://example.com/api/v1/customer/1/products', $url);

        return new MockResponse('...');
    },
];

$client = new MockHttpClient($expectedRequests);

// ...

1
2
3
4
5
6
7
8
9
10
11
12
13
14

namespace App\Tests;

use Symfony\Component\HttpClient\Response\MockResponse;
use Symfony\Contracts\HttpClient\ResponseInterface;

class MockClientCallback
{
    public function __invoke(string $method, string $url, array $options = []): ResponseInterface
    {
        // load a fixture file or generate data
        // ...
        return new MockResponse($data);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

$mockResponse = new MockResponse('', ['http_code' => 204]);
$httpClient = new MockHttpClient($mockResponse, 'https://example.com');

$response = $httpClient->request('DELETE', 'api/article/1337', [
    'headers' => [
        'Accept: */*',
        'Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l',
    ],
]);

$mockResponse->getRequestMethod();
// returns "DELETE"

$mockResponse->getRequestUrl();
// returns "https://example.com/api/article/1337"

$mockResponse->getRequestOptions()['headers'];
// returns ["Accept: */*", "Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l"]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

// ExternalArticleService.php
use Symfony\Contracts\HttpClient\HttpClientInterface;

final class ExternalArticleService
{
    public function __construct(
        private HttpClientInterface $httpClient,
    ) {
    }

    public function createArticle(array $requestData): array
    {
        $requestJson = json_encode($requestData, JSON_THROW_ON_ERROR);

        $response = $this->httpClient->request('POST', 'api/article', [
            'headers' => [
                'Content-Type: application/json',
                'Accept: application/json',
            ],
            'body' => $requestJson,
        ]);

        if (201 !== $response->getStatusCode()) {
            throw new Exception('Response status code is different than expected.');
        }

        // ... other checks

        $responseJson = $response->getContent();
        $responseData = json_decode($responseJson, true, 512, JSON_THROW_ON_ERROR);

        return $responseData;
    }
}

// ExternalArticleServiceTest.php
use PHPUnit\Framework\TestCase;
use Symfony\Component\HttpClient\MockHttpClient;
use Symfony\Component\HttpClient\Response\MockResponse;

final class ExternalArticleServiceTest extends TestCase
{
    public function testSubmitData(): void
    {
        // Arrange
        $requestData = ['title' => 'Testing with Symfony HTTP Client'];
        $expectedRequestData = json_encode($requestData, JSON_THROW_ON_ERROR);

        $expectedResponseData = ['id' => 12345];
        $mockResponseJson = json_encode($expectedResponseData, JSON_THROW_ON_ERROR);
        $mockResponse = new MockResponse($mockResponseJson, [
            'http_code' => 201,
            'response_headers' => ['Content-Type: application/json'],
        ]);

        $httpClient = new MockHttpClient($mockResponse, 'https://example.com');
        $service = new ExternalArticleService($httpClient);

        // Act
        $responseData = $service->createArticle($requestData);

        // Assert
        $this->assertSame('POST', $mockResponse->getRequestMethod());
        $this->assertSame('https://example.com/api/article', $mockResponse->getRequestUrl());
        $this->assertContains(
            'Content-Type: application/json',
            $mockResponse->getRequestOptions()['headers']
        );
        $this->assertSame($expectedRequestData, $mockResponse->getRequestOptions()['body']);

        $this->assertSame($expectedResponseData, $responseData);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

// ExternalArticleServiceTest.php
use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
use Symfony\Component\HttpClient\MockHttpClient;
use Symfony\Component\HttpClient\Response\MockResponse;

final class ExternalArticleServiceTest extends KernelTestCase
{
    public function testSubmitData(): void
    {
        // Arrange
        $fixtureDir = sprintf('%s/tests/fixtures/HTTP', static::getContainer()->getParameter('kernel.project_dir'));
        $factory = new HarFileResponseFactory("$fixtureDir/example.com_archive.har");
        $httpClient = new MockHttpClient($factory, 'https://example.com');
        $service = new ExternalArticleService($httpClient);

        // Act
        $responseData = $service->createArticle($requestData);

        // Assert
        $this->assertSame('the expected response', $responseData);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

// ExternalArticleServiceTest.php
use PHPUnit\Framework\TestCase;
use Symfony\Component\HttpClient\MockHttpClient;
use Symfony\Component\HttpClient\Response\MockResponse;

final class ExternalArticleServiceTest extends TestCase
{
    // ...

    public function testTransportLevelError(): void
    {
        $requestData = ['title' => 'Testing with Symfony HTTP Client'];
        $httpClient = new MockHttpClient([
            // Mock a transport level error at a time before
            // headers have been received (e. g. host unreachable)
            new MockResponse(info: ['error' => 'host unreachable']),

            // Mock a response with headers indicating
            // success, but a failure while retrieving the body by
            // creating the exception directly in the body...
            new MockResponse([new \RuntimeException('Error at transport level')]),

            // ... or by yielding it from a callback.
            new MockResponse((static function (): \Generator {
                yield new TransportException('Error at transport level');
            })()),
        ]);

        $service = new ExternalArticleService($httpClient);

        try {
            $service->createArticle($requestData);

            // An exception should have been thrown in `createArticle()`, so this line should never be reached
            $this->fail();
        } catch (TransportException $e) {
            $this->assertEquals(new \RuntimeException('Error at transport level'), $e->getPrevious());
            $this->assertSame('Error at transport level', $e->getMessage());
        }
    }
}