The end user interface for doing HTTP requests.
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.
Once you've created an instance of Client you can do requests using several methods. Each corresponds to a different HTTP method.
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 {@link \Cake\Http\Client\CookieCollection} will be created.
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
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:
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\AdapterInterface
Adapter for sending requests.
array<string, mixed>
Runtime config
bool
Whether the config property has already been configured with defaults
Cake\Http\Cookie\CookieCollection
List of cookies from responses made with this client.
array<string, mixed>
Default configuration for the client.
Cake\Http\Client\Adapter\Mock|null
Mock adapter for stubbing requests in tests.
Create a new HTTP Client.
Add authentication headers to the request.
Add proxy authentication headers.
Deletes a single config key.
Reads a config key.
Writes a config key.
Create the authentication strategy.
Creates a new request object based on the parameters.
Helper method for doing non-GET requests.
Does a recursive merge of the parameter with the scope config.
Send a request without redirection.
Returns headers for Accept/Content-Type based on a short type or full mime-type.
Adds a cookie to the Client collection.
Add a mocked response.
Generate a URL based on the scoped client options.
Clear all mocked responses
Merge provided config with existing config. Unlike config()
which does a recursive merge for nested keys, this method does a simple merge.
Get the cookies stored in the Client.
Client instance returned is scoped to the domain, port, and scheme parsed from the passed URL string. The passed string must have a scheme and a domain. Optionally, if a port is included in the string, the port will be scoped too. If a path is included in the URL, the client instance will build urls with it prepended. Other parts of the url string are ignored.
Do a DELETE request.
Do a GET request.
Returns the config.
Returns the config for this specific key.
Do a HEAD request.
Do an OPTIONS request.
Do a PATCH request.
Do a POST request.
Do a PUT request.
Send a request.
Sends a PSR-7 request and returns a PSR-7 response.
Sets the config.
Do a TRACE request.
__construct(array<string, mixed> $config = [])
Create a new HTTP Client.
You can set the following options when creating a client:
curl
extension is loaded else \Cake\Http\Client\Adapter\Stream.username
and password
key are provided without a type
key Basic authentication will be assumed. You can use the type
key to define the authentication adapter classname to use. Short class names are resolved to the Http\Client\Auth
namespace.array<string, mixed>
$config optional Config options for scoped clients.
InvalidArgumentException
_addAuthentication(Cake\Http\Client\Request $request, array<string, mixed> $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.
Cake\Http\Client\Request
$request The request to modify.
array<string, mixed>
$options Array of options containing the 'auth' key.
Cake\Http\Client\Request
_addProxy(Cake\Http\Client\Request $request, array<string, mixed> $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.
Cake\Http\Client\Request
$request The request to modify.
array<string, mixed>
$options Array of options containing the 'proxy' key.
Cake\Http\Client\Request
_configDelete(string $key): void
Deletes a single config key.
string
$key Key to delete.
void
Cake\Core\Exception\CakeException
_configRead(string|null $key): mixed
Reads a config key.
string|null
$key Key to read.
mixed
_configWrite(array<string, mixed>|string $key, mixed $value, string|bool $merge = false): void
Writes a config key.
array<string, mixed>|string
$key Key to write to.
mixed
$value Value to write.
string|bool
$merge optional True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.
void
Cake\Core\Exception\CakeException
_createAuth(array $auth, array<string, mixed> $options): object
Create the authentication strategy.
Use the configuration options to create the correct authentication strategy handler.
array
$auth The authentication options to use.
array<string, mixed>
$options The overall request options to use.
object
Cake\Core\Exception\CakeException
_createRequest(string $method, string $url, mixed $data, array<string, mixed> $options): Cake\Http\Client\Request
Creates a new request object based on the parameters.
string
$method HTTP method name.
string
$url The url including query string.
mixed
$data The request body.
array<string, mixed>
$options The options to use. Contains auth, proxy, etc.
Cake\Http\Client\Request
_doRequest(string $method, string $url, mixed $data, array<string, mixed> $options): Cake\Http\Client\Response
Helper method for doing non-GET requests.
string
$method HTTP method.
string
$url URL to request.
mixed
$data The request body.
array<string, mixed>
$options The options to use. Contains auth, proxy, etc.
Cake\Http\Client\Response
_mergeOptions(array<string, mixed> $options): array
Does a recursive merge of the parameter with the scope config.
array<string, mixed>
$options Options to merge.
array
_sendRequest(Psr\Http\Message\RequestInterface $request, array<string, mixed> $options): Cake\Http\Client\Response
Send a request without redirection.
Psr\Http\Message\RequestInterface
$request The request to send.
array<string, mixed>
$options Additional options to use.
Cake\Http\Client\Response
_typeHeaders(string $type): array<string, string>
Returns headers for Accept/Content-Type based on a short type or full mime-type.
string
$type short type alias or full mimetype.
array<string, string>
Cake\Core\Exception\CakeException
addCookie(Cake\Http\Cookie\CookieInterface $cookie): $this
Adds a cookie to the Client collection.
Cake\Http\Cookie\CookieInterface
$cookie Cookie object.
$this
InvalidArgumentException
addMockResponse(string $method, string $url, Cake\Http\Client\Response $response, array<string, mixed> $options = []): void
Add a mocked response.
Mocked responses are stored in an adapter that is called before the network adapter is called.
TODO finish this.
match
An additional closure to match requests with.string
$method The HTTP method being mocked.
string
$url The URL being matched. See above for examples.
Cake\Http\Client\Response
$response The response that matches the request.
array<string, mixed>
$options optional See above.
void
buildUrl(string $url, array|string $query = [], array<string, mixed> $options = []): string
Generate a URL based on the scoped client options.
string
$url Either a full URL or just the path.
array|string
$query optional The query data for the URL.
array<string, mixed>
$options optional The config options stored with Client::config()
string
clearMockResponses(): void
Clear all mocked responses
void
configShallow(array<string, mixed>|string $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']);
array<string, mixed>|string
$key The key to set, or a complete array of configs.
mixed|null
$value optional The value to set.
$this
cookies(): Cake\Http\Cookie\CookieCollection
Get the cookies stored in the Client.
Cake\Http\Cookie\CookieCollection
createFromUrl(string $url): static
Client instance returned is scoped to the domain, port, and scheme parsed from the passed URL string. The passed string must have a scheme and a domain. Optionally, if a port is included in the string, the port will be scoped too. If a path is included in the URL, the client instance will build urls with it prepended. Other parts of the url string are ignored.
string
$url A string URL e.g. https://example.com
static
InvalidArgumentException
delete(string $url, mixed $data = [], array<string, mixed> $options = []): Cake\Http\Client\Response
Do a DELETE request.
string
$url The url or path you want to request.
mixed
$data optional The request data you want to send.
array<string, mixed>
$options optional Additional options for the request.
Cake\Http\Client\Response
get(string $url, array|string $data = [], array<string, mixed> $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.
string
$url The url or path you want to request.
array|string
$data optional The query data you want to send.
array<string, mixed>
$options optional Additional options for the request.
Cake\Http\Client\Response
getConfig(string|null $key = null, mixed $default = null): mixed
Returns the config.
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');
string|null
$key optional The key to get or null for the whole config.
mixed
$default optional The return value when the key does not exist.
mixed
getConfigOrFail(string $key): mixed
Returns the config for this specific key.
The config value for this key must exist, it can never be null.
string
$key The key to get.
mixed
InvalidArgumentException
head(string $url, array $data = [], array<string, mixed> $options = []): Cake\Http\Client\Response
Do a HEAD request.
string
$url The url or path you want to request.
array
$data optional The query string data you want to send.
array<string, mixed>
$options optional Additional options for the request.
Cake\Http\Client\Response
options(string $url, mixed $data = [], array<string, mixed> $options = []): Cake\Http\Client\Response
Do an OPTIONS request.
string
$url The url or path you want to request.
mixed
$data optional The request data you want to send.
array<string, mixed>
$options optional Additional options for the request.
Cake\Http\Client\Response
patch(string $url, mixed $data = [], array<string, mixed> $options = []): Cake\Http\Client\Response
Do a PATCH request.
string
$url The url or path you want to request.
mixed
$data optional The request data you want to send.
array<string, mixed>
$options optional Additional options for the request.
Cake\Http\Client\Response
post(string $url, mixed $data = [], array<string, mixed> $options = []): Cake\Http\Client\Response
Do a POST request.
string
$url The url or path you want to request.
mixed
$data optional The post data you want to send.
array<string, mixed>
$options optional Additional options for the request.
Cake\Http\Client\Response
put(string $url, mixed $data = [], array<string, mixed> $options = []): Cake\Http\Client\Response
Do a PUT request.
string
$url The url or path you want to request.
mixed
$data optional The request data you want to send.
array<string, mixed>
$options optional Additional options for the request.
Cake\Http\Client\Response
send(Psr\Http\Message\RequestInterface $request, array<string, mixed> $options = []): Cake\Http\Client\Response
Send a request.
Used internally by other methods, but can also be used to send handcrafted Request objects.
Psr\Http\Message\RequestInterface
$request The request to send.
array<string, mixed>
$options optional Additional options to use.
Cake\Http\Client\Response
sendRequest(RequestInterface $request): Psr\Http\Message\ResponseInterface
Sends a PSR-7 request and returns a PSR-7 response.
RequestInterface
$request Request instance.
Psr\Http\Message\ResponseInterface
Psr\Http\Client\ClientExceptionInterface
setConfig(array<string, mixed>|string $key, mixed|null $value = null, bool $merge = true): $this
Sets the config.
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']);
array<string, mixed>|string
$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.
$this
Cake\Core\Exception\CakeException
trace(string $url, mixed $data = [], array<string, mixed> $options = []): Cake\Http\Client\Response
Do a TRACE request.
string
$url The url or path you want to request.
mixed
$data optional The request data you want to send.
array<string, mixed>
$options optional Additional options for the request.
Cake\Http\Client\Response
Adapter for sending requests.
Cake\Http\Client\AdapterInterface
Runtime config
array<string, mixed>
Whether the config property has already been configured with defaults
bool
List of cookies from responses made with this client.
Cookies are indexed by the cookie's domain or request host name.
Cake\Http\Cookie\CookieCollection
Default configuration for the client.
array<string, mixed>
Mock adapter for stubbing requests in tests.
Cake\Http\Client\Adapter\Mock|null
© 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/4.4/class-Cake.Http.Client.html