This is a development version of documentation for CakePHP 6.0. Go to latest docs.
Skip to content
Simple Analytics

Http Client ​

class Cake\Http\Client(mixed $config = [])

CakePHP includes a PSR-18 compliant HTTP client which can be used for making requests. It is a great way to communicate with webservices, and remote APIs.

Doing Requests ​

Doing requests is simple and straight forward. Doing a GET request looks like:

php
use Cake\Http\Client;

$http = new Client();

// Simple get
$response = $http->get('https://example.com/test.html');

// Simple get with querystring
$response = $http->get('https://example.com/search', ['q' => 'widget']);

// Simple get with querystring & additional headers
$response = $http->get('https://example.com/search', ['q' => 'widget'], [
    'headers' => ['X-Requested-With' => 'XMLHttpRequest'],
]);

Doing POST and PUT requests is equally simple:

php
// Send a POST request with application/x-www-form-urlencoded encoded data
$http = new Client();
$response = $http->post('https://example.com/posts/add', [
    'title' => 'testing',
    'body' => 'content in the post',
]);

// Send a PUT request with application/x-www-form-urlencoded encoded data
$response = $http->put('https://example.com/posts/add', [
    'title' => 'testing',
    'body' => 'content in the post',
]);

// Other methods as well.
$http->delete(/* ... */);
$http->head(/* ... */);
$http->patch(/* ... */);

If you have created a PSR-7 request object you can send it using sendRequest():

php
use Cake\Http\Client;
use Cake\Http\Client\Request as ClientRequest;

$request = new ClientRequest(
    'https://example.com/search',
    ClientRequest::METHOD_GET,
);
$http = new Client();
$response = $http->sendRequest($request);

Creating Multipart Requests with Files ​

You can include files in request bodies by including a filehandle in the array:

php
$http = new Client();
$response = $http->post('https://example.com/api', [
    'image' => fopen('/path/to/a/file', 'r'),
]);

The filehandle will be read until its end; it will not be rewound before being read.

Building Multipart Request Bodies ​

There may be times when you need to build a request body in a very specific way. In these situations you can often use Cake\Http\Client\FormData to craft the specific multipart HTTP request you want:

php
use Cake\Http\Client\FormData;

$data = new FormData();

// Create an XML part
$xml = $data->newPart('xml', $xmlString);
// Set the content type.
$xml->type('application/xml');
$data->add($xml);

// Create a file upload with addFile()
// This will append the file to the form data as well.
$file = $data->addFile('upload', fopen('/some/file.txt', 'r'));
$file->contentId('abc123');
$file->disposition('attachment');

// Send the request.
$response = $http->post(
    'https://example.com/api',
    (string)$data,
    ['headers' => ['Content-Type' => $data->contentType()]],
);

Sending Request Bodies ​

When dealing with REST APIs you often need to send request bodies that are not form encoded. Http\Client exposes this through the type option:

php
// Send a JSON request body.
$http = new Client();
$response = $http->post(
    'https://example.com/tasks',
    json_encode($data),
    ['type' => 'json'],
);

The type key can either be a one of 'json', 'xml' or a full mime type. When using the type option, you should provide the data as a string. If you're doing a GET request that needs both querystring parameters and a request body you can do the following:

php
// Send a JSON body in a GET request with query string parameters.
$http = new Client();
$response = $http->get(
    'https://example.com/tasks',
    ['q' => 'test', '_content' => json_encode($data)],
    ['type' => 'json'],
);

Request Method Options ​

Each HTTP method takes an $options parameter which is used to provide addition request information. The following keys can be used in $options:

  • headers - Array of additional headers
  • cookie - Array of cookies to use.
  • proxy - Array of proxy information.
  • auth - Array of authentication data, the type key is used to delegate to an authentication strategy. By default, Basic auth is used.
  • ssl_verify_peer - defaults to true. Set to false to disable SSL certification verification (not recommended).
  • ssl_verify_peer_name - defaults to true. Set to false to disable host name verification when verifying SSL certificates (not recommended).
  • ssl_verify_depth - defaults to 5. Depth to traverse in the CA chain.
  • ssl_verify_host - defaults to true. Validate the SSL certificate against the host name.
  • ssl_cafile - defaults to built in cafile. Overwrite to use custom CA bundles.
  • timeout - Duration to wait before timing out in seconds.
  • stream - Return a live response body after receiving headers instead of buffering the entire body. Defaults to false. Requires the Stream adapter.
  • readTimeout - Timeout in seconds for each live response body read. Defaults to timeout; 0 disables the read timeout. Must be finite and non-negative.
  • type - Send a request body in a custom content type. Requires $data to either be a string, or the _content option to be set when doing GET requests.
  • redirect - Number of redirects to follow. Defaults to false.
  • curl - An array of additional curl options (if the curl adapter is used), for example, [CURLOPT_SSLKEY => 'key.pem'].

The options parameter is always the 3rd parameter in each of the HTTP methods. They can also be used when constructing Client to create scoped clients.

Following Redirects ​

Set the redirect option to the maximum number of redirects to follow:

php
$response = $http->get('https://example.com/old-path', [], ['redirect' => 3]);

Relative Location values are resolved against the current request URL. Redirect targets must use HTTP or HTTPS and have a host. When following a 303 response, non-HEAD requests become GET requests with no body or body headers. When the scheme, host, or port changes, the original Authorization and Cookie headers are removed. Cookies matching the destination are added from the client's cookie jar.

Authentication ​

Cake\Http\Client supports a few different authentication systems. Different authentication strategies can be added by developers. Auth strategies are called before the request is sent, and allow headers to be added to the request context.

Using Basic Authentication ​

An example of basic authentication:

php
$http = new Client();
$response = $http->get('https://example.com/profile/1', [], [
    'auth' => ['username' => 'mark', 'password' => 'secret'],
]);

By default, Cake\Http\Client will use basic authentication if there is no 'type' key in the auth option.

Using Digest Authentication ​

An example of basic authentication:

php
$http = new Client();
$response = $http->get('https://example.com/profile/1', [], [
    'auth' => [
        'type' => 'digest',
        'username' => 'mark',
        'password' => 'secret',
        'realm' => 'myrealm',
        'nonce' => 'onetimevalue',
        'qop' => 1,
        'opaque' => 'someval',
    ],
]);

By setting the 'type' key to 'digest', you tell the authentication subsystem to use digest authentication. Digest authentication supports the following algorithms:

  • MD5
  • SHA-256
  • SHA-512-256
  • MD5-sess
  • SHA-256-sess
  • SHA-512-256-sess

The algorithm will be automatically chosen based on the server challenge.

OAuth 1 Authentication ​

Many modern web-services require OAuth authentication to access their APIs. The included OAuth authentication assumes that you already have your consumer key and consumer secret:

php
$http = new Client();
$response = $http->get('https://example.com/profile/1', [], [
    'auth' => [
        'type' => 'oauth',
        'consumerKey' => 'bigkey',
        'consumerSecret' => 'secret',
        'token' => '...',
        'tokenSecret' => '...',
        'realm' => 'tickets',
    ],
]);

OAuth 2 Authentication ​

Because OAuth2 is often a single header, there is not a specialized authentication adapter. Instead you can create a client with the access token:

php
$http = new Client([
    'headers' => ['Authorization' => 'Bearer ' . $accessToken],
]);
$response = $http->get('https://example.com/api/profile/1');

Custom Authentication Strategies ​

Custom strategies must implement Cake\Http\Client\Auth\AuthenticationInterface. The authentication() method receives a request and the authentication options, and must return the request with any authentication changes applied:

php
namespace App\Http\Client\Auth;

use Cake\Http\Client\Auth\AuthenticationInterface;
use Cake\Http\Client\Request;

class ApiKey implements AuthenticationInterface
{
    public function authentication(Request $request, array $credentials): Request
    {
        return $request->withHeader('X-Api-Key', $credentials['key']);
    }
}

Select the strategy with the auth.type option:

php
$response = $http->get('https://example.com/profile', [], [
    'auth' => ['type' => \App\Http\Client\Auth\ApiKey::class, 'key' => $apiKey],
]);

Proxy Authentication ​

Some proxies require authentication to use them. Generally this authentication is Basic. A custom proxy strategy must implement both Cake\Http\Client\Auth\AuthenticationInterface and Cake\Http\Client\Auth\ProxyAuthenticationInterface, providing a proxyAuthentication(Request $request, array $credentials): Request method. Using a strategy without proxy support throws Cake\Core\Exception\CakeException. By default, Http\Client uses Basic authentication unless the type key is set:

php
$http = new Client();
$response = $http->get('https://example.com/test.php', [], [
    'proxy' => [
        'username' => 'mark',
        'password' => 'testing',
        'proxy' => '127.0.0.1:8080',
    ],
]);

The second proxy parameter must be a string with an IP or a domain without protocol. The username and password information will be passed through the request headers, while the proxy string will be passed through stream_context_create().

Creating Scoped Clients ​

Having to re-type the domain name, authentication and proxy settings can become tedious & error prone. To reduce the chance for mistake and relieve some of the tedium, you can create scoped clients:

php
// Create a scoped client.
$http = new Client([
    'host' => 'api.example.com',
    'scheme' => 'https',
    'auth' => ['username' => 'mark', 'password' => 'testing'],
]);

// Do a request to api.example.com
$response = $http->get('/test.php');

If your scoped client only needs information from the URL you can use createFromUrl():

php
$http = Client::createFromUrl('https://api.example.com/v1/test');

The above creates a client with scheme, host, port and basePath options derived from the URL. Query strings and fragments are not used to configure the scoped client.

createFromUrl() uses PHP's WHATWG URL parser. Supply an absolute URL with a scheme and host. Malformed or relative URLs can throw Uri\WhatWg\InvalidUrlException; a parsed URL with no host raises InvalidArgumentException. The parser normalizes URLs, including removing default ports such as :80 from HTTP URLs.

The following information can be used when creating a scoped client:

  • host
  • basePath
  • scheme
  • proxy
  • auth
  • port
  • cookies
  • timeout
  • ssl_verify_peer
  • ssl_verify_depth
  • ssl_verify_host

Any of these options can be overridden by specifying them when doing requests. host, scheme, proxy, port are overridden in the request URL:

php
// Using the scoped client we created earlier.
$response = $http->get('http://foo.com/test.php');

The above will replace the domain, scheme, and port. However, this request will continue using all the other options defined when the scoped client was created. See Http Client Request Options for more information on the options supported.

Setting and Managing Cookies ​

Http\Client can also accept cookies when making requests. In addition to accepting cookies, it will also automatically store valid cookies set in responses. Any response with cookies, will have them stored in the originating instance of Http\Client. The cookies stored in a Client instance are automatically included in future requests to domain + path combinations that match:

php
$http = new Client([
    'host' => 'cakephp.org',
]);

// Do a request that sets some cookies
$response = $http->get('/');

// Cookies from the first request will be included
// by default.
$response2 = $http->get('/changelogs');

You can always override the auto-included cookies by setting them in the request's $options parameters:

php
// Replace a stored cookie with a custom value.
$response = $http->get('/changelogs', [], [
    'cookies' => ['sessionid' => '123abc'],
]);

You can add cookie objects to the client after creating it using the addCookie() method:

php
use Cake\Http\Cookie\Cookie;

$http = new Client([
    'host' => 'cakephp.org',
]);
$http->addCookie(new Cookie('session', 'abc123'));

Client Events ​

Client will emit events when requests are sent. The HttpClient.beforeSend event is fired before a request is sent, and HttpClient.afterSend is fired after a request is sent. You can modify the request, or set a response in a beforeSend listener. The afterSend event is triggered for all requests, even those that have their responses set by a beforeSend event.

Response Objects ​

class Cake\Http\Client\Response

Response objects have a number of methods for inspecting the response data.

Reading Response Bodies ​

You read the entire response body as a string:

php
// Read the entire response as a string.
$response->getStringBody();

You can also access the stream object for the response and use its methods:

php
// Get a Psr\Http\Message\StreamInterface containing the response body
$stream = $response->getBody();

// Read a stream 100 bytes at a time.
while (!$stream->eof()) {
    echo $stream->read(100);
}

Streaming Responses ​

By default the HTTP client buffers the response body before returning. To process an ongoing response, such as server-sent events (SSE), select the Stream adapter and enable the stream option:

php
use Cake\Http\Client;
use Cake\Http\Client\Adapter\Stream;

$http = new Client(['adapter' => Stream::class]);
$response = $http->get('https://example.com/events', [], [
    'stream' => true,
    'readTimeout' => 60,
    'headers' => ['Accept' => 'text/event-stream'],
]);

$body = $response->getBody();
try {
    while (!$body->eof()) {
        $chunk = $body->read(8192);
        // Process bytes incrementally; a chunk may contain only part of an event.
    }
} finally {
    $body->close();
}

Streaming requires PHP's allow_url_fopen setting. The Curl adapter rejects stream => true; explicitly select the Stream adapter even when the curl extension is installed.

The client returns after the response headers arrive. The body is non-seekable, has no known size, and cannot be replayed. readTimeout controls individual body reads, defaults to timeout, and accepts 0 to disable the read timeout. Read failures and timeouts throw Cake\Http\Client\Exception\NetworkException while consuming the body, so handle them around the read loop as well as the request.

getStringBody(), getJson(), getJsonArray(), getJsonAs() and getXml() consume a non-seekable body from its current position and wait for EOF. Avoid these methods for ongoing responses. HttpClient.afterSend runs before a live body has been consumed; logging and monitoring listeners should inspect headers and status without reading the body.

To forward a live body from a controller action, attach it to the server response and return that response. See Relaying a Live HTTP Response.

Reading JSON and XML Response Bodies ​

Since JSON and XML responses are commonly used, response objects provide a way to use accessors to read decoded data. JSON objects and arrays are decoded into PHP arrays; other JSON values retain their corresponding PHP types. XML data is decoded into a SimpleXMLElement tree:

php
// Get some XML
$http = new Client();
$response = $http->get('https://example.com/test.xml');
$xml = $response->getXml();

// Get some JSON
$http = new Client();
$response = $http->get('https://example.com/test.json');
$json = $response->getJson();

The decoded response data is stored in the response object, so accessing it multiple times has no additional cost. Calling withBody() clears the cached JSON and XML values for the new response.

getJson() returns null for both invalid JSON and the JSON value null. Use getJsonArray() when you require an array or null and want decoding failures to raise exceptions:

php
$data = $response->getJsonArray();

JSON objects and arrays are returned as PHP arrays, and JSON null is returned as null. Invalid JSON throws JsonException. Valid scalar values, such as true, 42, or "text", throw UnexpectedValueException.

Use getJsonAs() to validate the decoded array and convert it into an application-specific value. The decoder receives the result of getJsonArray() and is responsible for validating its shape:

php
$name = $response->getJsonAs(function (?array $data): string {
    if (!isset($data['name']) || !is_string($data['name'])) {
        throw new \UnexpectedValueException('Expected a string name.');
    }

    return $data['name'];
});

Accessing Response Headers ​

You can access headers through a few different methods. Header names are always treated as case-insensitive values when accessing them through methods:

php
// Get all the headers as an associative array.
$response->getHeaders();

// Get a single header as an array.
$response->getHeader('content-type');

// Get a header as a string
$response->getHeaderLine('content-type');

// Get the response encoding
$response->getEncoding();

You can read cookies with a few different methods depending on how much data you need about the cookies:

php
// Get all cookies (full data)
$response->getCookies();

// Get a single cookie's value.
$response->getCookie('session_id');

// Get a the complete data for a single cookie
// includes value, expires, path, httponly, secure keys.
$response->getCookieData('session_id');

Checking the Status Code ​

Response objects provide a few methods for checking status codes:

php
// Was the response a 20x
$response->isOk();

// Was the response a 30x
$response->isRedirect();

// Get the status code
$response->getStatusCode();

Changing Transport Adapters ​

By default, Http\Client will prefer using a curl based transport adapter. If the curl extension is not available a stream based adapter will be used instead. You can force select a transport adapter using a constructor option:

php
use Cake\Http\Client\Adapter\Stream;

$http = new Client(['adapter' => Stream::class]);

Events ​

The HTTP client triggers couple of events before and after sending a request which allows you to modify either the request or response or do other tasks like caching, logging etc.

HttpClient.beforeSend ​

php
// Somewhere before calling one of the HTTP client's methods which makes a request
$http->getEventManager()->on(
    'HttpClient.beforeSend',
    function (
        \Cake\Http\Client\ClientEvent $event,
        \Cake\Http\Client\Request $request,
        array $adapterOptions,
        int $redirects,
    ) {
        // Modify the request
        $event->setRequest(....);
        // Modify the adapter options
        $event->setAdapterOptions(....);

        // Skip making the actual request by returning a response.
        // You can use $event->setResult($response) to achieve the same.
        return new \Cake\Http\Client\Response(body: 'something');
    }
);

HttpClient.afterSend ​

php
// Somewhere before calling one of the HTTP client's methods which makes a request
$http->getEventManager()->on(
    'HttpClient.afterSend',
    function (
        \Cake\Http\Client\ClientEvent $event,
        \Cake\Http\Client\Request $request,
        array $adapterOptions,
        int $redirects,
        bool $requestSent // Indicates whether the request was actually sent
                            // or response returned from ``beforeSend`` event
    ) {
        // Get the response
        $response = $event->getResponse();

        // Return a new/modified response.
        // You can use $event->setResult($response) to achieve the same.
        return new \Cake\Http\Client\Response(body: 'something');
    }
);

Testing ​

In tests you will often want to create mock responses to external APIs. You can use the HttpClientTrait to define responses to the requests your application is making:

php
use Cake\Http\TestSuite\HttpClientTrait;
use Cake\TestSuite\TestCase;

class CartControllerTests extends TestCase
{
    use HttpClientTrait;

    public function testCheckout()
    {
        // Mock a POST request that will be made.
        $this->mockClientPost(
            'https://example.com/process-payment',
            $this->newClientResponse(200, [], json_encode(['ok' => true])),
        );
        $this->post("/cart/checkout");
        // Do assertions.
    }
}

There are methods to mock the most commonly used HTTP methods:

php
$this->mockClientGet(/* ... */);
$this->mockClientPatch(/* ... */);
$this->mockClientPost(/* ... */);
$this->mockClientPut(/* ... */);
$this->mockClientDelete(/* ... */);

Response::newClientResponse() ​

method Cake\Http\TestSuite\HttpClientTrait::newClientResponse(int $code = 200, array $headers = [], string $body = ''): Cake\Http\Client\Response

As seen above you can use the newClientResponse() method to create responses for the requests your application will make. The headers need to be a list of strings:

php
$headers = [
    'Content-Type: application/json',
    'Connection: close',
];
$response = $this->newClientResponse(200, $headers, $body)

Released under the MIT License.