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.
Properties summary
- $_adapter protected
\Cake\Http\Client\AdapterInterface
Adapter for sending requests.
- $_config protected
array
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
Default configuration for the client.
Method Summary
- _typeHeaders() protected
Returns headers for Accept/Content-Type based on a short type or full mime-type.
- configShallow() public
Merge provided config with existing config. Unlike
config()
which does a recursive merge for nested keys, this method does a simple merge.
Method Detail
__construct() public
__construct(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.
- 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. - protocolVersion - The HTTP protocol version to use. Defaults to 1.1
Parameters
-
array
$config optional Config options for scoped clients.
Throws
InvalidArgumentException
_addAuthentication() protected
_addAuthentication(\Cake\Http\Client\Request $request, mixed $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, mixed $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.
_configDelete() protected
_configDelete(mixed $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(mixed $key)
Reads a config key.
Parameters
-
string|null
$key Key to read.
Returns
mixed
_configWrite() protected
_configWrite(mixed $key, mixed $value, mixed $merge)
Writes a config key.
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.
Throws
Cake\Core\Exception\Exception
if attempting to clobber existing config
_createAuth() protected
_createAuth(mixed $auth, mixed $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.
Returns
object
Authentication strategy instance.
Throws
Cake\Core\Exception\Exception
when an invalid strategy is chosen.
_createRequest() protected
_createRequest(mixed $method, mixed $url, mixed $data, mixed $options)
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
$options The options to use. Contains auth, proxy, etc.
Returns
\Cake\Http\Client\Request
_doRequest() protected
_doRequest(mixed $method, mixed $url, mixed $data, mixed $options)
Helper 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\Http\Client\Response
_mergeOptions() protected
_mergeOptions(mixed $options)
Does a recursive merge of the parameter with the scope config.
Parameters
-
array
$options Options to merge.
Returns
array
Options merged with set config.
_sendRequest() protected
_sendRequest(\Cake\Http\Client\Request $request, mixed $options)
Send a request without redirection.
Parameters
-
\Cake\Http\Client\Request
$request The request to send.
-
array
$options Additional options to use.
Returns
\Cake\Http\Client\Response
_typeHeaders() protected
_typeHeaders(mixed $type)
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
string[]
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(mixed $url, mixed $query, mixed $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.
config() public
config(mixed $key, mixed $value, mixed $merge)
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']);
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
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(mixed $key, mixed $value)
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 The value to set.
Returns
$this
cookies() public
cookies()
Get the cookies stored in the Client.
Returns
\Cake\Http\Cookie\CookieCollection
delete() public
delete(mixed $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(mixed $url, mixed $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
getConfig() public
getConfig(mixed $key, mixed $default)
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|null
$default optional The return value when the key does not exist.
Returns
mixed|null
Configuration data at the named key or null if the key does not exist.
getConfigOrFail() public
getConfigOrFail(mixed $key)
Returns the config for this specific key.
The config value for this key must exist, it can never be null.
Parameters
-
string|null
$key The key to get.
Returns
mixed
Configuration data at the named key
Throws
InvalidArgumentException
head() public
head(mixed $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(mixed $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(mixed $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(mixed $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(mixed $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, mixed $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
setConfig() public
setConfig(mixed $key, mixed $value, mixed $merge)
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 The value to set.
-
bool
$merge optional 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.
trace() public
trace(mixed $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
Property Detail
$_adapter protected
Adapter for sending requests.
Type
\Cake\Http\Client\AdapterInterface
$_config protected
Runtime config
Type
array
$_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
© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/3.9/class-Cake.Http.Client.html