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 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.

Cake\Http\Client uses Cake\Core\InstanceConfigTrait

Namespace: Cake\Http
Location: Http/Client.php

Properties summary

$_adapter protected

Cake\Http\Client\AdapterInterface

Adapter for sending requests.
$_cookies protected

Cake\Http\Cookie\CookieCollection

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

array

Default configuration for the client.

Inherited Properties

_config, _configInitialized

Method Summary

__construct() public

Create a new HTTP Client.
_addAuthentication() protected

Add authentication headers to the request.
_addProxy() protected

Add proxy authentication headers.
_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.
buildUrl() public

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

Get the cookies stored in the Client.
delete() public

Do a DELETE request.
get() public

Do a GET request.
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.
trace() public

Do a TRACE request.

Method Detail

__construct() public ¶

__construct( array $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.
timeout - The timeout in seconds. Defaults to 30
ssl_verify_peer - Whether or not SSL certificates should be validated. Defaults to true.
ssl_verify_peer_name - Whether or not 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.

Parameters

array $config optional []: Config options for scoped clients.

Throws

InvalidArgumentException

_addAuthentication() protected ¶

_addAuthentication( Cake\Http\Client\Request $request , array $options )

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 $options: Array of options containing the 'auth' key.

Returns

Cake\Http\Client\Request
The updated request object.

_addProxy() protected ¶

_addProxy( Cake\Http\Client\Request $request , array $options )

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 $options: Array of options containing the 'proxy' key.

Returns

Cake\Http\Client\Request
The updated request object.

_createAuth() protected ¶

_createAuth( array $auth , array $options )

Create the authentication strategy.

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

Parameters

array $auth: The authentication options to use.
array $options: The overall request options to use.

Parameters

string $type: short type alias or full mimetype.

Returns

array
Headers to set on the request.

Throws

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

addCookie() public ¶

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

Adds a cookie to the Client collection.

Parameters

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

Returns

$this

Throws

InvalidArgumentException

buildUrl() public ¶

buildUrl( string $url , string|array $query = [] , array $options = [] )

Generate a URL based on the scoped client options.

Parameters

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

Returns

string
A complete url with scheme, port, host, and path.

cookies() public ¶

cookies( )

Get the cookies stored in the Client.

Returns

Cake\Http\Cookie\CookieCollection

delete() public ¶

delete( string $url , mixed $data = [] , array $options = [] )

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 $options optional []: Additional options for the request.

Returns

Cake\Http\Client\Response

get() public ¶

get( string $url , array $data = [] , array $options = [] )

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 $data optional []: The query data you want to send.
array $options optional []: Additional options for the request.

Returns

Cake\Http\Client\Response

head() public ¶

head( string $url , array $data = [] , array $options = [] )

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 $options optional []: Additional options for the request.

Returns

Cake\Http\Client\Response

options() public ¶

options( string $url , mixed $data = [] , array $options = [] )

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 $options optional []: Additional options for the request.

Returns

Cake\Http\Client\Response

patch() public ¶

patch( string $url , mixed $data = [] , array $options = [] )

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 $options optional []: Additional options for the request.

Returns

Cake\Http\Client\Response

post() public ¶

post( string $url , mixed $data = [] , array $options = [] )

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 $options optional []: Additional options for the request.

Returns

Cake\Http\Client\Response

put() public ¶

put( string $url , mixed $data = [] , array $options = [] )

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 $options optional []: Additional options for the request.

Returns

Cake\Http\Client\Response

send() public ¶

send( Cake\Http\Client\Request $request , array $options = [] )

Send a request.

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

Parameters

Cake\Http\Client\Request $request: The request to send.
array $options optional []: Additional options to use.

Returns

Cake\Http\Client\Response

trace() public ¶

trace( string $url , mixed $data = [] , array $options = [] )

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 $options optional []: Additional options for the request.

Returns

Cake\Http\Client\Response

Methods used from Cake\Core\InstanceConfigTrait

_configDelete() protected ¶

_configDelete( string $key )

Deletes a single config key.

Parameters

string $key: Key to delete.

Throws

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

_configRead() protected ¶

_configRead( string|null $key )

Reads a config key.

Parameters

string|null $key: Key to read.

Returns

mixed

_configWrite() protected ¶

_configWrite( string|array $key , mixed $value , boolean|string $merge = false )

Writes a config key.

Parameters

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

Throws

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

config() public deprecated ¶

config( string|array|null $key = null , mixed|null $value = null , boolean $merge = true )

Gets/Sets the config.

Usage

Reading the whole config:

$this->config();

Reading a specific value:

$this->config('key');

Reading a nested value:

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

Setting a specific value:

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

Setting a nested value:

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

Updating multiple config settings at the same time:

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

Deprecated

3.4.0 use setConfig()/getConfig() instead.

Parameters

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

Returns

mixed
Config value being read, or the object itself on write operations.

Throws

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

configShallow() public ¶

configShallow( string|array $key , mixed|null $value = null )

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

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

Returns

$this

getConfig() public ¶

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

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 null: The key to get or null for the whole config.
mixed $default optional null: The return value when the key does not exist.

Returns

mixed
Configuration data at the named key or null if the key does not exist.

setConfig() public ¶

setConfig( string|array $key , mixed|null $value = null , boolean $merge = true )

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

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

Returns

$this

Throws

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

Properties detail

`$_adapter` ¶

protected Cake\Http\Client\AdapterInterface

Adapter for sending requests.

`$_cookies` ¶

protected Cake\Http\Cookie\CookieCollection

List of cookies from responses made with this client.

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

`$_defaultConfig` ¶

protected array

Default configuration for the client.

[
    'adapter' => null,
    'host' => null,
    'port' => null,
    'scheme' => 'http',
    'timeout' => 30,
    'ssl_verify_peer' => true,
    'ssl_verify_peer_name' => true,
    'ssl_verify_depth' => 5,
    'ssl_verify_host' => true,
    'redirect' => false,
]

Namespaces

Classes

Class Client

Scoped clients

Doing requests

Cookie management

Sending request bodies

Using authentication

Using proxies

Properties summary

Inherited Properties

Method Summary

__construct() public

_addAuthentication() protected

_addProxy() protected

_createAuth() protected

_createRequest() protected

_doRequest() protected

_mergeOptions() protected

_sendRequest() protected

_typeHeaders() protected

addCookie() public

buildUrl() public

cookies() public

delete() public

get() public

head() public

options() public

patch() public

post() public

put() public

send() public

trace() public

Method Detail

__construct() public ¶

Config options

Parameters

Throws

_addAuthentication() protected ¶

Parameters

Returns

_addProxy() protected ¶

Parameters

Returns

_createAuth() protected ¶

Parameters

Returns

Throws

_createRequest() protected ¶

Parameters

Returns

_doRequest() protected ¶

Parameters

Returns

_mergeOptions() protected ¶

Parameters

Returns

_sendRequest() protected ¶

Parameters

Returns

_typeHeaders() protected ¶

Parameters

Returns

Throws

addCookie() public ¶

Parameters

Returns

Throws

buildUrl() public ¶

Parameters

Returns

cookies() public ¶

Returns

delete() public ¶

Parameters

Returns

get() public ¶

Parameters

Returns

head() public ¶

`$_adapter` ¶

`$_cookies` ¶

`$_defaultConfig` ¶