Class Client

The end user interface for doing HTTP requests.

Scoped clients

If you're doing multiple requests to the same hostname it's often convenient to use the constructor arguments to create a scoped client. This allows you to keep your code DRY and not repeat hostnames, authentication, and other options.

Doing requests

Once you've created an instance of Client you can do requests using several methods. Each corresponds to a different HTTP method.

get()
post()
put()
delete()
patch()

Cookie management

Client will maintain cookies from the responses done with a client instance. These cookies will be automatically added to future requests to matching hosts. Cookies will respect the Expires, Path and Domain attributes. You can get the client's CookieCollection using cookies()

You can use the 'cookieJar' constructor option to provide a custom cookie jar instance you've restored from cache/disk. By default, an empty instance of {@link \Cake\Http\Client\CookieCollection} will be created.

Sending request bodies

By default, any POST/PUT/PATCH/DELETE request with $data will send their data as application/x-www-form-urlencoded unless there are attached files. In that case multipart/form-data will be used.

When sending request bodies you can use the type option to set the Content-Type for the request:

$http->get('/users', [], ['type' => 'json']);

The type option sets both the Content-Type and Accept header, to the same mime type. When using type you can use either a full mime type or an alias. If you need different types in the Accept and Content-Type headers you should set them manually and not use type

Using authentication

By using the auth key you can use authentication. The type sub option can be used to specify which authentication strategy you want to use. CakePHP comes with a few built-in strategies:

Basic
Digest
Oauth

Using proxies

By using the proxy key you can set authentication credentials for a proxy if you need to use one. The type sub option can be used to specify which authentication strategy you want to use. CakePHP comes with built-in support for basic authentication.

Namespace: Cake\Http

Property Summary

$_adapter protected

Cake\Http\Client\AdapterInterface

Adapter for sending requests.
$_config protected

array<string, mixed>

Runtime config
$_configInitialized protected

bool

Whether the config property has already been configured with defaults
$_cookies protected

Cake\Http\Cookie\CookieCollection

List of cookies from responses made with this client.
$_defaultConfig protected

array<string, mixed>

Default configuration for the client.
$_eventClass protected

string

Default class name for new event objects.
$_eventManager protected

Cake\Event\EventManagerInterface|null

Instance of the Cake\Event\EventManager this object is using to dispatch inner events.
$_mockAdapter protected static

Cake\Http\Client\Adapter\Mock|null

Mock adapter for stubbing requests in tests.

Method Summary

__construct() public

Create a new HTTP Client.
_addAuthentication() protected

Add authentication headers to the request.
_addProxy() protected

Add proxy authentication headers.
_configDelete() protected

Deletes a single config key.
_configRead() protected

Reads a config key.
_configWrite() protected

Writes a config key.
_createAuth() protected

Create the authentication strategy.
_createRequest() protected

Creates a new request object based on the parameters.
_doRequest() protected

Helper method for doing non-GET requests.
_mergeOptions() protected

Does a recursive merge of the parameter with the scope config.
_sendRequest() protected

Send a request without redirection.
_typeHeaders() protected

Returns headers for Accept/Content-Type based on a short type or full mime-type.
addCookie() public

Adds a cookie to the Client collection.
addMockResponse() public static

Add a mocked response.
buildUrl() public

Generate a URL based on the scoped client options.
clearMockResponses() public static

Clear all mocked responses
configShallow() public

Merge provided config with existing config. Unlike config() which does a recursive merge for nested keys, this method does a simple merge.
cookies() public

Get the cookies stored in the Client.
createFromUrl() public static

Client instance returned is scoped to the domain, port, and scheme parsed from the passed URL string. The passed string must have a scheme and a domain. Optionally, if a port is included in the string, the port will be scoped too. If a path is included in the URL, the client instance will build urls with it prepended. Other parts of the url string are ignored.
delete() public

Do a DELETE request.
dispatchEvent() public

Wrapper for creating and dispatching events.
get() public

Do a GET request.
getConfig() public

Returns the config.
getConfigOrFail() public

Returns the config for this specific key.
getEventManager() public

Returns the Cake\Event\EventManager manager instance for this object.
head() public

Do a HEAD request.
options() public

Do an OPTIONS request.
patch() public

Do a PATCH request.
post() public

Do a POST request.
put() public

Do a PUT request.
send() public

Send a request.
sendRequest() public

Sends a PSR-7 request and returns a PSR-7 response.
setConfig() public

Sets the config.
setEventManager() public

Returns the Cake\Event\EventManagerInterface instance for this object.
trace() public

Do a TRACE request.

Method Detail

__construct() ¶ public

__construct(array<string, mixed> $config = [])

Create a new HTTP Client.

Config options

You can set the following options when creating a client:

host - The hostname to do requests on.
port - The port to use.
scheme - The default scheme/protocol to use. Defaults to http.
basePath - A path to append to the domain to use. (/api/v1/)
timeout - The timeout in seconds. Defaults to 30
ssl_verify_peer - Whether SSL certificates should be validated. Defaults to true.
ssl_verify_peer_name - Whether peer names should be validated. Defaults to true.
ssl_verify_depth - The maximum certificate chain depth to traverse. Defaults to 5.
ssl_verify_host - Verify that the certificate and hostname match. Defaults to true.
redirect - Number of redirects to follow. Defaults to false.
adapter - The adapter class name or instance. Defaults to \Cake\Http\Client\Adapter\Curl if curl extension is loaded else \Cake\Http\Client\Adapter\Stream.
protocolVersion - The HTTP protocol version to use. Defaults to 1.1
auth - The authentication credentials to use. If a username and password key are provided without a type key Basic authentication will be assumed. You can use the type key to define the authentication adapter classname to use. Short class names are resolved to the Http\Client\Auth namespace.

Parameters

array<string, mixed> $config optional: Config options for scoped clients.

_addAuthentication() ¶ protected

_addAuthentication(Cake\Http\Client\Request $request, array<string, mixed> $options): Cake\Http\Client\Request

Add authentication headers to the request.

Uses the authentication type to choose the correct strategy and use its methods to add headers.

Parameters

Cake\Http\Client\Request $request: The request to modify.
array<string, mixed> $options: Array of options containing the 'auth' key.

Returns

Cake\Http\Client\Request

_addProxy() ¶ protected

_addProxy(Cake\Http\Client\Request $request, array<string, mixed> $options): Cake\Http\Client\Request

Add proxy authentication headers.

Uses the authentication type to choose the correct strategy and use its methods to add headers.

Parameters

Cake\Http\Client\Request $request: The request to modify.
array<string, mixed> $options: Array of options containing the 'proxy' key.

Returns

Cake\Http\Client\Request

_configDelete() ¶ protected

_configDelete(string $key): void

Deletes a single config key.

Parameters

string $key: Key to delete.

Returns

void

Throws

Cake\Core\Exception\CakeException
if attempting to clobber existing config

_configRead() ¶ protected

_configRead(string|null $key): mixed

Reads a config key.

Parameters

string|null $key: Key to read.

Returns

mixed

_configWrite() ¶ protected

_configWrite(array<string, mixed>|string $key, mixed $value, string|bool $merge = false): void

Writes a config key.

Parameters

array<string, mixed>|string $key: Key to write to.
mixed $value: Value to write.
string|bool $merge optional: True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.

Returns

void

Throws

Cake\Core\Exception\CakeException
if attempting to clobber existing config

_createAuth() ¶ protected

_createAuth(array $auth, array<string, mixed> $options): object

Create the authentication strategy.

Use the configuration options to create the correct authentication strategy handler.

Parameters

array $auth: The authentication options to use.
array<string, mixed> $options: The overall request options to use.

Returns

object

Throws

Cake\Core\Exception\CakeException
when an invalid strategy is chosen.

_createRequest() ¶ protected

_createRequest(string $method, string $url, mixed $data, array<string, mixed> $options): Cake\Http\Client\Request

Creates a new request object based on the parameters.

Parameters

string $method: HTTP method name.
string $url: The url including query string.
mixed $data: The request body.
array<string, mixed> $options: The options to use. Contains auth, proxy, etc.

Returns

Cake\Http\Client\Request

_doRequest() ¶ protected

_doRequest(string $method, string $url, mixed $data, array<string, mixed> $options): Cake\Http\Client\Response

Helper method for doing non-GET requests.

Parameters

string $method: HTTP method.
string $url: URL to request.
mixed $data: The request body.
array<string, mixed> $options: The options to use. Contains auth, proxy, etc.

Returns

Cake\Http\Client\Response

_mergeOptions() ¶ protected

_mergeOptions(array<string, mixed> $options): array

Does a recursive merge of the parameter with the scope config.

Parameters

array<string, mixed> $options: Options to merge.

Returns

array

_sendRequest() ¶ protected

_sendRequest(Psr\Http\Message\RequestInterface $request, array<string, mixed> $options): Cake\Http\Client\Response

Send a request without redirection.

Parameters

Psr\Http\Message\RequestInterface $request: The request to send.
array<string, mixed> $options: Additional options to use.

Returns

Cake\Http\Client\Response

_typeHeaders() ¶ protected

_typeHeaders(string $type): array<string, string>

Returns headers for Accept/Content-Type based on a short type or full mime-type.

Parameters

string $type: short type alias or full mimetype.

Returns

array<string, string>

Throws

Cake\Core\Exception\CakeException
When an unknown type alias is used.

addCookie() ¶ public

addCookie(Cake\Http\Cookie\CookieInterface $cookie): $this

Adds a cookie to the Client collection.

Parameters

Cake\Http\Cookie\CookieInterface $cookie: Cookie object.

Returns

$this

Throws

InvalidArgumentException

addMockResponse() ¶ public static

addMockResponse(string $method, string $url, Cake\Http\Client\Response $response, array<string, mixed> $options = []): void

Add a mocked response.

Mocked responses are stored in an adapter that is called before the network adapter is called.

Matching Requests

TODO finish this.

Options

match An additional closure to match requests with.

Parameters

string $method: The HTTP method being mocked.
string $url: The URL being matched. See above for examples.
Cake\Http\Client\Response $response: The response that matches the request.
array<string, mixed> $options optional: See above.

Returns

void

buildUrl() ¶ public

buildUrl(string $url, array|string $query = [], array<string, mixed> $options = []): string

Generate a URL based on the scoped client options.

Parameters

string $url: Either a full URL or just the path.
array|string $query optional: The query data for the URL.
array<string, mixed> $options optional: The config options stored with Client::config()

Returns

string

clearMockResponses() ¶ public static

clearMockResponses(): void

Clear all mocked responses

Returns

void

configShallow() ¶ public

configShallow(array<string, mixed>|string $key, mixed|null $value = null): $this

Merge provided config with existing config. Unlike config() which does a recursive merge for nested keys, this method does a simple merge.

Setting a specific value:

$this->configShallow('key', $value);

Setting a nested value:

$this->configShallow('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->configShallow(['one' => 'value', 'another' => 'value']);

Parameters

array<string, mixed>|string $key: The key to set, or a complete array of configs.
mixed|null $value optional: The value to set.

Returns

$this

cookies() ¶ public

cookies(): Cake\Http\Cookie\CookieCollection

Get the cookies stored in the Client.

Returns

Cake\Http\Cookie\CookieCollection

createFromUrl() ¶ public static

createFromUrl(string $url): static

Client instance returned is scoped to the domain, port, and scheme parsed from the passed URL string. The passed string must have a scheme and a domain. Optionally, if a port is included in the string, the port will be scoped too. If a path is included in the URL, the client instance will build urls with it prepended. Other parts of the url string are ignored.

Parameters

string $url: A string URL e.g. https://example.com

Returns

static

Throws

InvalidArgumentException

delete() ¶ public

delete(string $url, mixed $data = [], array<string, mixed> $options = []): Cake\Http\Client\Response

Do a DELETE request.

Parameters

string $url: The url or path you want to request.
mixed $data optional: The request data you want to send.
array<string, mixed> $options optional: Additional options for the request.

Returns

Cake\Http\Client\Response

dispatchEvent() ¶ public

dispatchEvent(string $name, array $data = [], TSubject|null $subject = null): Cake\Event\EventInterface<TSubject>

Wrapper for creating and dispatching events.

Returns a dispatched event.

Parameters

string $name: Name of the event.
array $data optional: Any value you wish to be transported with this event to it can be read by listeners.
TSubject|null $subject optional: The object that this event applies to ($this by default).

Returns

Cake\Event\EventInterface<TSubject>

get() ¶ public

get(string $url, array|string $data = [], array<string, mixed> $options = []): Cake\Http\Client\Response

Do a GET request.

The $data argument supports a special _content key for providing a request body in a GET request. This is generally not used, but services like ElasticSearch use this feature.

Parameters

string $url: The url or path you want to request.
array|string $data optional: The query data you want to send.
array<string, mixed> $options optional: Additional options for the request.

Returns

Cake\Http\Client\Response

getConfig() ¶ public

getConfig(string|null $key = null, mixed $default = null): mixed

Returns the config.

Usage

Reading the whole config:

$this->getConfig();

Reading a specific value:

$this->getConfig('key');

Reading a nested value:

$this->getConfig('some.nested.key');

Reading with default value:

$this->getConfig('some-key', 'default-value');

Parameters

string|null $key optional: The key to get or null for the whole config.
mixed $default optional: The return value when the key does not exist.

Returns

mixed

getConfigOrFail() ¶ public

getConfigOrFail(string $key): mixed

Returns the config for this specific key.

The config value for this key must exist, it can never be null.

Parameters

string $key: The key to get.

Returns

mixed

Throws

InvalidArgumentException

getEventManager() ¶ public

getEventManager(): Cake\Event\EventManagerInterface

Returns the Cake\Event\EventManager manager instance for this object.

You can use this instance to register any new listeners or callbacks to the object events, or create your own events and trigger them at will.

Returns

Cake\Event\EventManagerInterface

head() ¶ public

head(string $url, array $data = [], array<string, mixed> $options = []): Cake\Http\Client\Response

Do a HEAD request.

Parameters

string $url: The url or path you want to request.
array $data optional: The query string data you want to send.
array<string, mixed> $options optional: Additional options for the request.

Returns

Cake\Http\Client\Response

options() ¶ public

options(string $url, mixed $data = [], array<string, mixed> $options = []): Cake\Http\Client\Response

Do an OPTIONS request.

Parameters

string $url: The url or path you want to request.
mixed $data optional: The request data you want to send.
array<string, mixed> $options optional: Additional options for the request.

Returns

Cake\Http\Client\Response

patch() ¶ public

patch(string $url, mixed $data = [], array<string, mixed> $options = []): Cake\Http\Client\Response

Do a PATCH request.

Parameters

string $url: The url or path you want to request.
mixed $data optional: The request data you want to send.
array<string, mixed> $options optional: Additional options for the request.

Returns

Cake\Http\Client\Response

post() ¶ public

post(string $url, mixed $data = [], array<string, mixed> $options = []): Cake\Http\Client\Response

Do a POST request.

Parameters

string $url: The url or path you want to request.
mixed $data optional: The post data you want to send.
array<string, mixed> $options optional: Additional options for the request.

Returns

Cake\Http\Client\Response

put() ¶ public

put(string $url, mixed $data = [], array<string, mixed> $options = []): Cake\Http\Client\Response

Do a PUT request.

Parameters

string $url: The url or path you want to request.
mixed $data optional: The request data you want to send.
array<string, mixed> $options optional: Additional options for the request.

Returns

Cake\Http\Client\Response

send() ¶ public

send(Psr\Http\Message\RequestInterface $request, array<string, mixed> $options = []): Cake\Http\Client\Response

Send a request.

Used internally by other methods, but can also be used to send handcrafted Request objects.

Parameters

Psr\Http\Message\RequestInterface $request: The request to send.
array<string, mixed> $options optional: Additional options to use.

Returns

Cake\Http\Client\Response

sendRequest() ¶ public

sendRequest(RequestInterface $request): Psr\Http\Message\ResponseInterface

Sends a PSR-7 request and returns a PSR-7 response.

Parameters

RequestInterface $request: Request instance.

Returns

Psr\Http\Message\ResponseInterface

Throws

Psr\Http\Client\ClientExceptionInterface
If an error happens while processing the request.

setConfig() ¶ public

setConfig(array<string, mixed>|string $key, mixed|null $value = null, bool $merge = true): $this

Sets the config.

Usage

Setting a specific value:

$this->setConfig('key', $value);

Setting a nested value:

$this->setConfig('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->setConfig(['one' => 'value', 'another' => 'value']);

Parameters

array<string, mixed>|string $key: The key to set, or a complete array of configs.
mixed|null $value optional: The value to set.
bool $merge optional: Whether to recursively merge or overwrite existing config, defaults to true.

Returns

$this

Throws

Cake\Core\Exception\CakeException
When trying to set a key that is invalid.

setEventManager() ¶ public

setEventManager(Cake\Event\EventManagerInterface $eventManager): $this

Returns the Cake\Event\EventManagerInterface instance for this object.

You can use this instance to register any new listeners or callbacks to the object events, or create your own events and trigger them at will.

Parameters

Cake\Event\EventManagerInterface $eventManager: the eventManager to set

Returns

$this

trace() ¶ public

trace(string $url, mixed $data = [], array<string, mixed> $options = []): Cake\Http\Client\Response

Do a TRACE request.

Parameters

string $url: The url or path you want to request.
mixed $data optional: The request data you want to send.
array<string, mixed> $options optional: Additional options for the request.

Returns

Cake\Http\Client\Response

Property Detail

`$_adapter` ¶ protected

Adapter for sending requests.

Type

Cake\Http\Client\AdapterInterface

`$_config` ¶ protected

Runtime config

Type

array<string, mixed>

`$_configInitialized` ¶ protected

Whether the config property has already been configured with defaults

Type

bool

`$_cookies` ¶ protected

List of cookies from responses made with this client.

Cookies are indexed by the cookie's domain or request host name.

Type

Cake\Http\Cookie\CookieCollection

`$_defaultConfig` ¶ protected

Default configuration for the client.

Type

array<string, mixed>

`$_eventClass` ¶ protected

Default class name for new event objects.

Type

string

`$_eventManager` ¶ protected

Instance of the Cake\Event\EventManager this object is using to dispatch inner events.

Type

Cake\Event\EventManagerInterface|null

`$_mockAdapter` ¶ protected static

Mock adapter for stubbing requests in tests.

Type

Cake\Http\Client\Adapter\Mock|null

Namespaces

Class Client

Scoped clients

Doing requests

Cookie management

Sending request bodies

Using authentication

Using proxies

Property Summary

Method Summary

__construct() public

_addAuthentication() protected

_addProxy() protected

_configDelete() protected

_configRead() protected

_configWrite() protected

_createAuth() protected

_createRequest() protected

_doRequest() protected

_mergeOptions() protected

_sendRequest() protected

_typeHeaders() protected

addCookie() public

addMockResponse() public static

buildUrl() public

clearMockResponses() public static

configShallow() public

cookies() public

createFromUrl() public static

delete() public

dispatchEvent() public

get() public

getConfig() public

getConfigOrFail() public

getEventManager() public

head() public

options() public

patch() public

post() public

put() public

send() public

sendRequest() public

setConfig() public

setEventManager() public

trace() public

Method Detail

__construct() ¶ public

Config options

Parameters

_addAuthentication() ¶ protected

Parameters

Returns

_addProxy() ¶ protected

Parameters

Returns

_configDelete() ¶ protected

Parameters

Returns

Throws

_configRead() ¶ protected

Parameters

Returns

_configWrite() ¶ protected

Parameters

Returns

Throws

_createAuth() ¶ protected

Parameters

Returns

Throws

_createRequest() ¶ protected

Parameters

Returns

_doRequest() ¶ protected

Parameters

Returns

_mergeOptions() ¶ protected

Parameters

Returns

_sendRequest() ¶ protected