Class Client
The end user interface for doing HTTP requests.
Scoped clients
If you're doing multiple requests to the same hostname its 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 list of
currently stored cookies using the cookies() method.
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\Network\Http\CookieCollection will be created.
Sending request bodies
By default any POST/PUT/PATCH/DELETE request with $data will
send their data as multipart/form-data.
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.
Property Summary
-
$_adapter protected
Cake\Network\Http\Adapter\StreamAdapter for sending requests. Defaults to Cake\Network\Http\Adapter\Stream
-
$_config protected
arrayRuntime config
-
$_configInitialized protected
boolWhether the config property has already been configured with defaults
-
$_cookies protected
Cake\Network\Http\CookieCollectionList of cookies from responses made with this client.
-
$_defaultConfig protected
arrayDefault configuration for the client.
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
Delete a single config key
-
_configRead() protected
Read a config variable
-
_configWrite() protected
Write a config variable
-
_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.
-
_typeHeaders() protected
Returns headers for Accept/Content-Type based on a short type or full mime-type.
-
buildUrl() public
Generate a URL based on the scoped client options.
-
config() public
Usage
-
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.
-
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_depth - The maximum certificate chain depth to travers. 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.
Parameters
-
array$config optional Config options for scoped clients.
_addAuthentication() ¶ protected
_addAuthentication(Cake\Network\Http\Request $request, array $options): voidAdd authentication headers to the request.
Uses the authentication type to choose the correct strategy and use its methods to add headers.
Parameters
-
Cake\Network\Http\Request$request The request to modify.
-
array$options Array of options containing the 'auth' key.
Returns
void_addProxy() ¶ protected
_addProxy(Cake\Network\Http\Request $request, array $options): voidAdd proxy authentication headers.
Uses the authentication type to choose the correct strategy and use its methods to add headers.
Parameters
-
Cake\Network\Http\Request$request The request to modify.
-
array$options Array of options containing the 'proxy' key.
Returns
void_configDelete() ¶ protected
_configDelete(string $key): voidDelete a single config key
Parameters
-
string$key Key to delete.
Returns
voidThrows
Cake\Core\Exception\Exceptionif attempting to clobber existing config
_configRead() ¶ protected
_configRead(string|null $key): mixedRead a config variable
Parameters
-
string|null$key Key to read.
Returns
mixed_configWrite() ¶ protected
_configWrite(string|array $key, mixed $value, bool|string $merge = false): voidWrite a config variable
Parameters
-
string|array$key Key to write to.
-
mixed$value Value to write.
-
bool|string$merge optional True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.
Returns
voidThrows
Cake\Core\Exception\Exceptionif attempting to clobber existing config
_createAuth() ¶ protected
_createAuth(array $auth, array $options): mixedCreate 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.
Returns
mixedThrows
Cake\Core\Exception\Exceptionwhen an invalid strategy is chosen.
_createRequest() ¶ protected
_createRequest(string $method, string $url, mixed $data, array $options): Cake\Network\Http\RequestCreates 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$options The options to use. Contains auth, proxy etc.
Returns
Cake\Network\Http\Request_doRequest() ¶ protected
_doRequest(string $method, string $url, mixed $data, array $options): Cake\Network\Http\ResponseHelper method for doing non-GET requests.
Parameters
-
string$method HTTP method.
-
string$url URL to request.
-
mixed$data The request body.
-
array$options The options to use. Contains auth, proxy etc.
Returns
Cake\Network\Http\Response_mergeOptions() ¶ protected
_mergeOptions(array $options): arrayDoes a recursive merge of the parameter with the scope config.
Parameters
-
array$options Options to merge.
Returns
array_typeHeaders() ¶ protected
_typeHeaders(string $type): arrayReturns headers for Accept/Content-Type based on a short type or full mime-type.
Parameters
-
string$type short type alias or full mimetype.
Returns
arrayThrows
Cake\Core\Exception\ExceptionWhen an unknown type alias is used.
buildUrl() ¶ public
buildUrl(string $url, string|array $query = [], array $options = []): stringGenerate 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
stringconfig() ¶ public
config(string|array|null $key = null, mixed|null $value = null, bool $merge = true): mixedUsage
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']);Parameters
-
string|array|null$key optional The key to get/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
mixedThrows
Cake\Core\Exception\ExceptionWhen trying to set a key that is invalid.
configShallow() ¶ public
configShallow(string|array $key, mixed|null $value = null): $thisMerge 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->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']);Parameters
-
string|array$key The key to set, or a complete array of configs.
-
mixed|null$value optional The value to set.
Returns
$thiscookies() ¶ public
cookies(): Cake\Network\Http\CookieCollectionGet the cookies stored in the Client.
Returns an array of cookie data arrays.
Returns
Cake\Network\Http\CookieCollectiondelete() ¶ public
delete(string $url, mixed $data = [], array $options = []): Cake\Network\Http\ResponseDo 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\Network\Http\Responseget() ¶ public
get(string $url, array $data = [], array $options = []): Cake\Network\Http\ResponseDo 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\Network\Http\Responsehead() ¶ public
head(string $url, array $data = [], array $options = []): Cake\Network\Http\ResponseDo 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\Network\Http\Responseoptions() ¶ public
options(string $url, mixed $data = [], array $options = []): Cake\Network\Http\ResponseDo 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\Network\Http\Responsepatch() ¶ public
patch(string $url, mixed $data = [], array $options = []): Cake\Network\Http\ResponseDo 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\Network\Http\Responsepost() ¶ public
post(string $url, mixed $data = [], array $options = []): Cake\Network\Http\ResponseDo 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\Network\Http\Responseput() ¶ public
put(string $url, mixed $data = [], array $options = []): Cake\Network\Http\ResponseDo 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\Network\Http\Responsesend() ¶ public
send(Cake\Network\Http\Request $request, array $options = []): Cake\Network\Http\ResponseSend a request.
Used internally by other methods, but can also be used to send handcrafted Request objects.
Parameters
-
Cake\Network\Http\Request$request The request to send.
-
array$options optional Additional options to use.
Returns
Cake\Network\Http\Responsetrace() ¶ public
trace(string $url, mixed $data = [], array $options = []): Cake\Network\Http\ResponseDo 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\Network\Http\ResponseProperty Detail
$_adapter ¶ protected
Adapter for sending requests. Defaults to Cake\Network\Http\Adapter\Stream
Type
Cake\Network\Http\Adapter\Stream$_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\Network\Http\CookieCollection