CakePHP
  • Documentation
    • Book
    • API
    • Videos
    • Reporting Security Issues
    • Privacy Policy
    • Logos & Trademarks
  • Business Solutions
  • Swag
  • Road Trip
  • Team
  • Community
    • Community
    • Get Involved
    • Issues (Github)
    • Bakery
    • Featured Resources
    • Training
    • Meetups
    • My CakePHP
    • CakeFest
    • Newsletter
    • Linkedin
    • YouTube
    • Facebook
    • Twitter
    • Mastodon
    • Help & Support
    • Forum
    • Stack Overflow
    • IRC
    • Slack
    • Paid Support
CakePHP

C CakePHP 3.10 Red Velvet API

  • Project:
    • CakePHP
      • CakePHP
      • Authentication
      • Authorization
      • Chronos
      • Elastic Search
      • Queue
  • Version:
    • 3.10
      • 5.2
      • 5.1
      • 5.0
      • 4.6
      • 4.5
      • 4.4
      • 4.3
      • 4.2
      • 4.1
      • 4.0
      • 3.10
      • 3.9
      • 3.8
      • 3.7
      • 3.6
      • 3.5
      • 3.4
      • 3.3
      • 3.2
      • 3.1
      • 3.0
      • 2.10
      • 2.9
      • 2.8
      • 2.7
      • 2.6
      • 2.5
      • 2.4
      • 2.3
      • 2.2
      • 2.1
      • 2.0
      • 1.3
      • 1.2

Namespaces

  • Global
  • Cake
    • Auth
    • Cache
    • Collection
    • Command
    • Console
    • Controller
    • Core
    • Database
    • Datasource
    • Error
    • Event
    • Filesystem
    • Form
    • Http
      • Client
      • Cookie
      • Exception
      • Middleware
      • Session
    • I18n
    • Log
    • Mailer
    • Network
    • ORM
    • Routing
    • Shell
    • TestSuite
    • Utility
    • Validation
    • View

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.

Namespace: Cake\Http

Property 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

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

  • buildUrl() public

    Generate a URL based on the scoped client options.

  • config() public deprecated

    Gets/Sets the config.

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

  • getConfig() public

    Returns the config.

  • getConfigOrFail() public

    Returns the config for this specific key.

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

  • setConfig() public

    Sets the config.

  • 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.
  • 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, array $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 $options

Array of options containing the 'auth' key.

Returns
Cake\Http\Client\Request

_addProxy() ¶ protected

_addProxy(Cake\Http\Client\Request $request, array $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 $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\Exception
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(string|array $key, mixed $value, bool|string $merge = false): void

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.

Returns
void
Throws
Cake\Core\Exception\Exception
if attempting to clobber existing config

_createAuth() ¶ protected

_createAuth(array $auth, array $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 $options

The overall request options to use.

Returns
object
Throws
Cake\Core\Exception\Exception
when an invalid strategy is chosen.

_createRequest() ¶ protected

_createRequest(string $method, string $url, mixed $data, array $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 $options

The options to use. Contains auth, proxy, etc.

Returns
Cake\Http\Client\Request

_doRequest() ¶ protected

_doRequest(string $method, string $url, mixed $data, array $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 $options

The options to use. Contains auth, proxy, etc.

Returns
Cake\Http\Client\Response

_mergeOptions() ¶ protected

_mergeOptions(array $options): array

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

Parameters
array $options

Options to merge.

Returns
array

_sendRequest() ¶ protected

_sendRequest(Cake\Http\Client\Request $request, array $options): Cake\Http\Client\Response

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(string $type): 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
string[]
Throws
Cake\Core\Exception\Exception
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

buildUrl() ¶ public

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

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

config() ¶ public

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

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
Throws
Cake\Core\Exception\Exception
When trying to set a key that is invalid.

configShallow() ¶ public

configShallow(string|array $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
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(): Cake\Http\Cookie\CookieCollection

Get the cookies stored in the Client.

Returns
Cake\Http\Cookie\CookieCollection

delete() ¶ public

delete(string $url, mixed $data = [], array $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 $options optional

Additional options for the request.

Returns
Cake\Http\Client\Response

get() ¶ public

get(string $url, array $data = [], array $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 $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(string|null $key = null, mixed|null $default = null): mixed|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

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

getConfigOrFail() ¶ public

getConfigOrFail(string|null $key): mixed

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
Throws
InvalidArgumentException

head() ¶ public

head(string $url, array $data = [], array $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 $options optional

Additional options for the request.

Returns
Cake\Http\Client\Response

options() ¶ public

options(string $url, mixed $data = [], array $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 $options optional

Additional options for the request.

Returns
Cake\Http\Client\Response

patch() ¶ public

patch(string $url, mixed $data = [], array $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 $options optional

Additional options for the request.

Returns
Cake\Http\Client\Response

post() ¶ public

post(string $url, mixed $data = [], array $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 $options optional

Additional options for the request.

Returns
Cake\Http\Client\Response

put() ¶ public

put(string $url, mixed $data = [], array $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 $options optional

Additional options for the request.

Returns
Cake\Http\Client\Response

send() ¶ public

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

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(string|array $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
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(string $url, mixed $data = [], array $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 $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
OpenHub
Pingping
Linode
  • Business Solutions
  • Showcase
  • Documentation
  • Book
  • API
  • Videos
  • Reporting Security Issues
  • Privacy Policy
  • Logos & Trademarks
  • Community
  • Get Involved
  • Issues (Github)
  • Bakery
  • Featured Resources
  • Training
  • Meetups
  • My CakePHP
  • CakeFest
  • Newsletter
  • Linkedin
  • YouTube
  • Facebook
  • Twitter
  • Mastodon
  • Help & Support
  • Forum
  • Stack Overflow
  • IRC
  • Slack
  • Paid Support

Generated using CakePHP API Docs