By https://andreiabohner.

org
Consume APIs in a snap! Provides utilities to

HttpClient consume APIs

HttpClient is a
Install standalone package

$ composer require symfony/http-client

4.3
Create the low-level HTTP
client that makes requests

Using the HttpClient

use Symfony\Component\HttpClient\HttpClient;

Create Options: Request Options:

options defined here are added to here you can define
all requests made by this client default values options that apply only
to this request
$httpClient = HttpClient::create([], 6, 50); (overrides any global option
defined by the
max host max pending
HTTPclient::create)
The request() method perform connections pushes
all kinds of HTTP requests (optional) (optional)(only cURL)

$response = $httpClient->request('GET', 'https://symfony.com/versions.json’, []);

code execution continues immediately, HTTP method URL

it doesn't wait to receive the response

$statusCode = $response->getStatusCode();
returns the status code
getting the response headers E.g.: 200
waits until they arrive

$contentType = $response->getHeaders()['content-type'][0];
returns: ‘application/json’

getting the response contents will block the execution

$content = $response->getContent(); until the full response contents are received
(use streaming responses for full async apps)
returns:
{"lts":"3.4.28","latest":"4.2.9","dev":"4.3.0-RC1",...}
$content = $response->toArray();
returns:
["lts" => "3.4.28", “latest" => "4.2.9",
"dev" => "4.3.0-RC1", “2.0"=>"2.0.25", ...]

Only supported
when using cURL
HTTP/2 will be used by default if:
* cURL-based transport used
HTTPClient supports
HTTP/2 request * libcurl version is >= 7.36 native PHP streams
* request using HTTPs protocol
and cURL
To enable for HTTP requests:
HttpClient::create() selects cURL transport if cURL PHP
$httpClient = HttpClient::create(['http_version' => '2.0']); extension is enabled and falls back to PHP streams otherwise.

Explicitly selecting the transport

HTTP/2 PUSH support
use Symfony\Component\HttpClient\CurlHttpClient;
Available when: use Symfony\Component\HttpClient\NativeHttpClient;
* libcurl >= 7.61 is used
* PHP >= 7.2.17 / 7.3.4 // native PHP streams
$httpClient = new NativeHttpClient();
Pushed responses are put into a temporary cache and are used when a
subsequent request is triggered for the corresponding URLs. // cURL PHP extension
$httpClient = new CurlHttpClient();
 By https://andreiabohner.org

HttpClient
4.3 Options for Create and Request
option default value definition and examples
authentication

auth_basic null An array containing the username as first value, and optionally the password as the second one; or string
like username:password - enabling HTTP Basic authentication (RFC 7617).
Use the same authentication
auth_bearer null A token enabling HTTP Bearer authorization (RFC 6750). for all requests
$httpClient = HttpClient::create([ HTTP Basic authentication
'auth_basic' => ['the-username'], with only the username
'auth_basic' => ['the-username', 'the-password'], HTTP Basic authentication
with username and password
'auth_bearer' => 'the-bearer-token', HTTP Bearer authentication
]); (also called token authentication)

$response = $httpClient->request('GET', 'https://...', [ use a different HTTP

'auth_basic' => ['the-username', 'the-password'], Basic authentication
]); only for this request
query [] Associative array of query string values to merge with the request's URL.
query string params

$response = $httpClient->request('GET', 'https://httpbin.org/get', [

'query' => [
'token' => '...', these values are automatically
'name' => '...', encoded before including
], them in the URL
]);
setting HTTP headers

headers [] Headers names provided as keys or as part of values.

header added to
$httpClient = HttpClient::create(['headers' => [ all requests made
'User-Agent' => 'My Fancy App',
by this client
]]);

$response = $httpClient->request('POST', 'https://...', [ header only included in

'headers' => [ this request and overrides
'Content-Type' => 'text/plain', the value of the same
], header if defined
]); globally by create()
uploading data

body ‘' You can use regular strings, closures, iterables and resources to upload data.
They'll be processed automatically when making the requests.
$response = $httpClient->request('POST', 'https://...', [
'body' => 'raw data', using a regular string
using an array
'body' => ['parameter1' => 'value1', '...'],
of parameters
'body' => function () {
// ... using a closure to generate
}, the uploaded data
'body' => fopen('/path/to/file', 'r'), using a resource to
]); get the data from it

json null
json payload

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', '...'],
]);

user_data null Any extra data to attach to the request (scalar, callable, object...) that
must be available via $response->getInfo('user_data') - not used internally.

max_redirects 20 The maximum number of redirects to follow; a value lower or equal to zero means redirects should not be followed;
"Authorization" and "Cookie" headers must not follow except for the initial host name.
If the number of redirects is higher than the configured value, you'll get a RedirectionException.

http_version null Defaults to the best supported version, typically 1.1 or 2.0.

base_uri null The URI to resolve relative URLs, following rules in RFC 3986, section 2 .

buffer true Whether the content of the response should be buffered or not.
 By https://andreiabohner.org
PSR-18 compatible
HttpClient
4.3
option default value definition and examples

on_progress null Details about the response progress (e.g. display a progress bar) / abort a request throwing any exceptions.

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

'buffer' => false, optional: if you don't want to

buffer the response in memory

'on_progress' => function (int $dlNow, int $dlSize, array $info): void {
// ...
}, optional: to display details
]); about the response progress

resolve [] A map of host to IP address that should replace DNS resolution.

Protect webhooks against calls to internal endpoints.

proxy null Get through an HTTP proxy. By default, the proxy-related env vars handled by cURL should be honored.

no_proxy null A comma separated list of hosts that do not require a proxy to be reached.

timeout null The inactivity timeout - defaults to ini_get('default_socket_timeout').

bindto 0 The interface or the local socket to bind to.

verify_peer true
SSL / certificates (https://php.net/context.ssl)

Require verification of SSL certificate used.

verify_host true

cafile null Location of Certificate Authority file on local filesystem which should be used with the verify_peer context option
to authenticate the identity of the remote peer.

capath null If cafile is not specified or if the certificate is not found there, the directory pointed to by capath is searched for a
suitable certificate. capath must be a correctly hashed certificate directory.

local_cert null Path to local certificate file on filesystem.

local_pk null Path to local private key file on filesystem in case of separate files for certificate (local_cert) and private key.

passphrase null Passphrase with which your local_cert file was encoded.

ciphers null Sets the list of available ciphers.

peer_fingerprint null Pin public keys of remote certificates. Aborts when the remote certificate digest doesn't match the specified hash.

capture_peer_cert_chain false If set to TRUE a peer_certificate_chain context option will be created containing the certificate chain.

extra [] Additional options that can be ignored if unsupported, unlike regular options

HTTPClient is stateless so it doesn't handle cookies automatically. You can:

Cookies - handle cookies yourself using the Cookie HTTP header
- use the BrowserKit component which provides this feature and integrates seamlessly with the HttpClient component

Caching Requests and Responses

The CachingHttpClient decorator allows caching responses and serving them from the local storage for next requests.
The implementation leverages the HttpCache class under the hood so that the HttpKernel component needs to be installed in your app.

use Symfony\Component\HttpClient\HttpClient;
use Symfony\Component\HttpClient\CachingHttpClient;
use Symfony\Component\HttpKernel\HttpCache\Store;
accepts a third argument
$store = new Store('/path/to/cache/storage/'); to set the options for
$client = HttpClient::create(); HttpCache
$client = new CachingHttpClient($client, $store); won't hit the network
if the resource is already
$response = $client->request('GET', 'https://example.com/cacheable-resource'); in the cache
 By https://andreiabohner.org
Supports synchronous and

HttpClient asynchronous operations

Responses are always asynchronous:

the call to the method returns immediately
The response is instead of waiting to receive the response
4.3
an object of type
ResponseInterface
Response
Info coming from
the transport layer
Response Methods
$response = $httpClient->request('GET', 'https://...'); $response->getInfo() Options
returns the HTTP status
$statusCode = $response->getStatusCode(); code of the response user_data is non-blocking:
it returns live
gets the HTTP headers as string[][] response_headers info about
$headers = $response->getHeaders(); with the header names lower-cased the response
debug
gets the response
$content = $response->getContent();
body as a string url

gets info coming from error

$httpInfo = $response->getInfo();
the transport layer
http_method

$startTime = $response->getInfo('start_time'); gets individual info http_code

redirect_count

start_time

Streaming Responses for full async apps connect_time

$url = 'https://releases.ubuntu.com/18.04.1/ubuntu-18.04.1-desktop-amd64.iso'; redirect_time

$response = $httpClient->request('GET', $url, [
'buffer' => false, starttransfer_time
'on_progress' => function (int $dlNow, int $dlSize, array $info): void {
// ... total_time
},
]); responses are lazy: namelookup_time
this code is executed as soon
size_upload
as headers are received
if (200 !== $response->getStatusCode()) {
throw new \Exception('...'); size_download
}
primary_ip
(optional) max number of seconds to
primary_port
wait before yelding a timeout chunk
get the response redirect_url
$fileHandler = fopen('/ubuntu.iso', 'w'); contents in chunk
foreach ($httpClient->stream($response, 0.0) as $chunk) { gets detailed
fwrite($fileHandler, $chunk->getContent()); logs about the
} HTTP transaction
stream : get chunks of the response sequentially E.g.:
instead of waiting for the entire response $response->getInfo('debug')

response chunks implement Symfony\Contracts\HttpClient\ChunkInterface

autoconfigure the HTTP client HTTP client options that depend

based on the requested URL Scoping Client on the URL of the request

use Symfony\Component\HttpClient\HttpClient;
use Symfony\Component\HttpClient\ScopingHttpClient;

$client = HttpClient::create();
the key is a regexp
$httpClient = new ScopingHttpClient($client, [
which must match the options defined as values
'https://api\.github\.com/' => [
the beginning of 'headers' => [ apply only to the URLs
the request URL 'Accept' => 'application/vnd.github.v3+json', matching the regular
'Authorization' => 'token '.$githubToken, expressions defined as key
],
the (optional) 3rd 'base_uri' => 'https://api.github.com/',
argument is the ],
regexp applied to ],
all relative URLs 'https://api\.github\.com/'
(when using base_uri) );
 By https://andreiabohner.org

HttpClient
you can configure multiple clients with
different configurations and inject
them into your services
4.3
Symfony Framework Integration

# config/packages/framework.yaml # config/packages/framework.yaml
framework: framework:
# ... Use the http_client # ... Defining multiple
http_client: key to configure the http_client: http_clients
max_host_connections: 10 default HTTP client scoped_clients:
default_options: crawler.client:
max_redirects: 7
used in the app headers: { 'X-Powered-By': 'ACME App' }
http_version: '1.0'
some_api.client:
max_redirects: 5

you can choose the service

Injecting the HTTP Client into Services using any available method
in Symfony

One HTTP client Multiple HTTP clients

use Symfony\Contracts\HttpClient\HttpClientInterface; Each scoped client also defines a

inject the HTTP client into any corresponding named autowiring alias
class SomeService
{ service by type-hinting a constructor
private $httpClient; argument with the HttpClientInterface
E.g.: when using as type and name of an argument:
public function __construct(HttpClientInterface $httpClient)
{ Symfony\Contracts\HttpClient\HttpClientInterface $someApiClient
$this->httpClient = $httpClient;
} autowiring will inject the some_api.client service
}

Network errors (broken pipe, failed DNS resolution, etc.)

Dealing with Network Errors are thrown as instances of TransportExceptionInterface

To catch errors because responses are Multiplexing responses

lazy so errors can
Wrap calls to $client->request() Deal with errors for individual streams by catching TransportExceptionInterface
happen in any method,
but also calls to any methods of the in the foreach loop
(except $response->getInfo()
returned responses
that is non-blocking) foreach ($client->stream($responses) as $response => $chunk) {
try { try {
// both lines can potentially throw if ($chunk->isLast()) {
$response = $client->request(...); // ... do something with $response
$headers = $response->getHeaders(); }
// ... } catch (TransportExceptionInterface $e) {
} catch (TransportExceptionInterface $e) { // ...
// ... }
} }

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() and getContent() methods throw an appropriate exception:
the response of this
$response = $httpClient->request('GET', 'https://httpbin.org/status/403'); request will be a
403 HTTP error
// this code results in a Symfony\Component\HttpClient\Exception\ClientException
// because it doesn't check the status code of the response
$content = $response->getContent();
pass FALSE as the optional argument to
not throw an exception and return
$content = $response->getContent(false); instead the original response content
(even if it's an error message)