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 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\Network\Http\Client uses Cake\Core\InstanceConfigTrait
Method Detail
__constructsource 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.
_addAuthenticationsource protected
_addAuthentication( Cake\Network\Http\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\Network\Http\Request
$request
- The request to modify.
- array
$options
- Array of options containing the 'auth' key.
_addProxysource protected
_addProxy( Cake\Network\Http\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\Network\Http\Request
$request
- The request to modify.
- array
$options
- Array of options containing the 'proxy' key.
_createAuthsource 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.
Returns
mixed
Authentication strategy instance.
Throws
Cake\Core\Exception\Exception
when an invalid strategy is chosen.
_createRequestsource protected
_createRequest( string $method , string $url , mixed $data , array $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\Network\Http\Request
\Cake\Network\Http\Request
_doRequestsource protected
_doRequest( string $method , string $url , mixed $data , array $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\Network\Http\Response
\Cake\Network\Http\Response
_mergeOptionssource protected
_mergeOptions( array $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.
_typeHeaderssource protected
_typeHeaders( string $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
array
Headers to set on the request.
Throws
Cake\Core\Exception\Exception
When an unknown type alias is used.
buildUrlsource 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, path.
cookiessource public
cookies( )
Get the cookies stored in the Client.
Returns an array of cookie data arrays.
Returns
Cake\Network\Http\CookieCollection
\Cake\Network\Http\CookieCollection
deletesource 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\Network\Http\Response
\Cake\Network\Http\Response
getsource 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\Network\Http\Response
\Cake\Network\Http\Response
headsource 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\Network\Http\Response
\Cake\Network\Http\Response
optionssource 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\Network\Http\Response
\Cake\Network\Http\Response
patchsource 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\Network\Http\Response
\Cake\Network\Http\Response
postsource 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\Network\Http\Response
\Cake\Network\Http\Response
putsource 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\Network\Http\Response
\Cake\Network\Http\Response
sendsource public
send( Cake\Network\Http\Request $request , array $options [] )
Send 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\Response
\Cake\Network\Http\Response
tracesource 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\Network\Http\Response
\Cake\Network\Http\Response
Methods used from Cake\Core\InstanceConfigTrait
_configDeletesource protected
_configDelete( string $key )
Delete a single config key
Parameters
- string
$key
- Key to delete.
Throws
Cake\Core\Exception\Exception
if attempting to clobber existing config
_configReadsource protected
_configRead( string|null $key )
Read a config variable
Parameters
- string|null
$key
- Key to read.
Returns
mixed
mixed
_configWritesource protected
_configWrite( string|array $key , mixed $value , boolean|string $merge false )
Write a config variable
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
configsource public
config( string|array|null $key null , mixed|null $value null , boolean $merge true )
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 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.
configShallowsource 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->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 null - The value to set.
Returns
mixed
$this The object itself.
Properties summary
Properties used from Cake\Core\InstanceConfigTrait
$_configInitializedsource
protected boolean
Whether the config property has already been configured with defaults
false
© 2005–2016 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.
http://api.cakephp.org/3.1/class-Cake.Network.Http.Client.html