Class RequestHandlerComponent

Request object handling for alternative HTTP requests.

This Component checks for requests for different content types like JSON, XML, XMLHttpRequest(AJAX) and configures the response object and view builder accordingly.

It can also check for HTTP caching headers like Last-Modified, If-Modified-Since etc. and return a response accordingly.

Namespace: Cake\Controller\Component
Link: https://book.cakephp.org/4/en/controllers/components/request-handling.html

Property Summary

$_componentMap protected

array<string, array>

A component lookup table used to lazy load component objects.
$_config protected

array<string, mixed>

Runtime config
$_configInitialized protected

bool

Whether the config property has already been configured with defaults
$_defaultConfig protected

array<string, mixed>

Default config
$_registry protected

Cake\Controller\ComponentRegistry

Component registry class used to lazy load components.
$_renderType protected

string|null

The template type to use when rendering the given content type.
$components protected

array

Other Components this component uses.
$ext protected

string|null

Contains the file extension parsed out by the Router

Method Summary

__construct() public

Constructor. Parses the accepted content types accepted by the client using HTTP_ACCEPT
__debugInfo() public

Returns an array that can be used to describe the internal state of this object.
__get() public

Magic method for lazy loading $components.
_configDelete() protected

Deletes a single config key.
_configRead() protected

Reads a config key.
_configWrite() protected

Writes a config key.
_setExtension() protected

Set the extension based on the Accept header or URL extension.
accepts() public

Determines which content types the client accepts. Acceptance is based on the file extension parsed by the Router (if present), and by the HTTP_ACCEPT header. Unlike {@link \Cake\Http\ServerRequest::accepts()} this method deals entirely with mapped content types.
beforeRender() public

Checks if the response can be considered different according to the request headers, and the caching response headers. If it was not modified, then the render process is skipped. And the client will get a blank response with a "304 Not Modified" header.
configShallow() public

Merge provided config with existing config. Unlike config() which does a recursive merge for nested keys, this method does a simple merge.
getConfig() public

Returns the config.
getConfigOrFail() public

Returns the config for this specific key.
getController() public

Get the controller this component is bound to.
implementedEvents() public

Events supported by this component.
initialize() public

Constructor hook method.
log() public

Convenience method to write a message to Log. See Log::write() for more information on writing to logs.
mapAlias() public

Maps a content type alias back to its mime-type(s)
prefers() public

Determines which content-types the client prefers. If no parameters are given, the single content-type that the client most likely prefers is returned. If $type is an array, the first item in the array that the client accepts is returned. Preference is determined primarily by the file extension parsed by the Router if provided, and secondarily by the list of content-types provided in HTTP_ACCEPT.
renderAs() public

Sets either the view class if one exists or the layout and template path of the view. The names of these are derived from the $type input parameter.
requestedWith() public

Determines the content type of the data the client has sent (i.e. in a POST request)
respondAs() public

Sets the response header based on type map index name. This wraps several methods available on {@link \Cake\Http\Response}. It also allows you to use Content-Type aliases.
setConfig() public

Sets the config.
startup() public

The startup method of the RequestHandler enables several automatic behaviors related to the detection of certain properties of the HTTP request, including:

Method Detail

__construct() ¶ public

__construct(Cake\Controller\ComponentRegistry $registry, array<string, mixed> $config = [])

Constructor. Parses the accepted content types accepted by the client using HTTP_ACCEPT

Parameters

Cake\Controller\ComponentRegistry $registry: ComponentRegistry object.
array<string, mixed> $config optional: Array of config.

__debugInfo() ¶ public

__debugInfo(): array<string, mixed>

Returns an array that can be used to describe the internal state of this object.

Returns

array<string, mixed>

__get() ¶ public

__get(string $name): Cake\Controller\Component|null

Magic method for lazy loading $components.

Parameters

string $name: Name of component to get.

Returns

Cake\Controller\Component|null

_configDelete() ¶ protected

_configDelete(string $key): void

Deletes a single config key.

Parameters

string $key: Key to delete.

Returns

void

Throws

Cake\Core\Exception\CakeException
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(array<string, mixed>|string $key, mixed $value, string|bool $merge = false): void

Writes a config key.

Parameters

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.

Returns

void

Throws

Cake\Core\Exception\CakeException
if attempting to clobber existing config

_setExtension() ¶ protected

_setExtension(Cake\Http\ServerRequest $request, Cake\Http\Response $response): void

Set the extension based on the Accept header or URL extension.

Compares the accepted types and configured extensions. If there is one common type, that is assigned as the ext/content type for the response. The type with the highest weight will be set. If the highest weight has more than one type matching the extensions, the order in which extensions are specified determines which type will be set.

If html is one of the preferred types, no content type will be set, this is to avoid issues with browsers that prefer HTML and several other content types.

Parameters

Cake\Http\ServerRequest $request: The request instance.
Cake\Http\Response $response: The response instance.

Returns

void

accepts() ¶ public

accepts(array<string>|string|null $type = null): array|bool|string|null

Determines which content types the client accepts. Acceptance is based on the file extension parsed by the Router (if present), and by the HTTP_ACCEPT header. Unlike {@link \Cake\Http\ServerRequest::accepts()} this method deals entirely with mapped content types.

Usage:

$this->RequestHandler->accepts(['xml', 'html', 'json']);

Returns true if the client accepts any of the supplied types.

$this->RequestHandler->accepts('xml');

Returns true if the client accepts XML.

Parameters

array<string>|string|null $type optional: Can be null (or no parameter), a string type name, or an array of types

Returns

array|bool|string|null

beforeRender() ¶ public

beforeRender(Cake\Event\EventInterface $event): void

Checks if the response can be considered different according to the request headers, and the caching response headers. If it was not modified, then the render process is skipped. And the client will get a blank response with a "304 Not Modified" header.

If Router::extensions() is enabled, the layout and template type are switched based on the parsed extension or Accept header. For example, if controller/action.xml is requested, the view path becomes templates/Controller/xml/action.php. Also, if controller/action is requested with Accept: application/xml in the headers the view path will become templates/Controller/xml/action.php. Layout and template types will only switch to mime-types recognized by \Cake\Http\Response. If you need to declare additional mime-types, you can do so using {@link \Cake\Http\Response::setTypeMap()} in your controller's beforeFilter() method.
If a helper with the same name as the extension exists, it is added to the controller.
If the extension is of a type that RequestHandler understands, it will set that Content-type in the response header.

Parameters

Cake\Event\EventInterface $event: The Controller.beforeRender event.

Returns

void

Throws

Cake\Http\Exception\NotFoundException
If invoked extension is not configured.

configShallow() ¶ public

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']);

Parameters

array<string, mixed>|string $key: The key to set, or a complete array of configs.
mixed|null $value optional: The value to set.

Returns

$this

getConfig() ¶ public

getConfig(string|null $key = null, mixed $default = null): mixed

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 $default optional: The return value when the key does not exist.

Returns

mixed

getConfigOrFail() ¶ public

getConfigOrFail(string $key): mixed

Returns the config for this specific key.

The config value for this key must exist, it can never be null.

Parameters

string $key: The key to get.

Returns

mixed

Throws

InvalidArgumentException

getController() ¶ public

getController(): Cake\Controller\Controller

Get the controller this component is bound to.

Returns

Cake\Controller\Controller

implementedEvents() ¶ public

implementedEvents(): array<string, mixed>

Events supported by this component.

Uses Conventions to map controller events to standard component callback method names. By defining one of the callback methods a component is assumed to be interested in the related event.

Override this method if you need to add non-conventional event listeners. Or if you want components to listen to non-standard events.

Returns

array<string, mixed>

initialize() ¶ public

initialize(array<string, mixed> $config): void

Constructor hook method.

Implement this method to avoid having to overwrite the constructor and call parent.

Parameters

array<string, mixed> $config: The configuration settings provided to this component.

Returns

void

log() ¶ public

log(string $message, string|int $level = LogLevel::ERROR, array|string $context = []): bool

Convenience method to write a message to Log. See Log::write() for more information on writing to logs.

Parameters

string $message: Log message.
string|int $level optional: Error level.
array|string $context optional: Additional log data relevant to this message.

Returns

bool

mapAlias() ¶ public

mapAlias(array|string $alias): array|string|null

Maps a content type alias back to its mime-type(s)

Parameters

array|string $alias: String alias to convert back into a content type. Or an array of aliases to map.

Returns

array|string|null

prefers() ¶ public

prefers(array<string>|string|null $type = null): string|bool|null

Determines which content-types the client prefers. If no parameters are given, the single content-type that the client most likely prefers is returned. If $type is an array, the first item in the array that the client accepts is returned. Preference is determined primarily by the file extension parsed by the Router if provided, and secondarily by the list of content-types provided in HTTP_ACCEPT.

Parameters

array<string>|string|null $type optional: An optional array of 'friendly' content-type names, i.e. 'html', 'xml', 'js', etc.

Returns

string|bool|null

renderAs() ¶ public

renderAs(Cake\Controller\Controller $controller, string $type, array<string, mixed> $options = []): void

Sets either the view class if one exists or the layout and template path of the view. The names of these are derived from the $type input parameter.

Usage:

Render the response as an 'ajax' response.

$this->RequestHandler->renderAs($this, 'ajax');

Render the response as an XML file and force the result as a file download.

$this->RequestHandler->renderAs($this, 'xml', ['attachment' => 'myfile.xml'];

Parameters

Cake\Controller\Controller $controller: A reference to a controller object
string $type: Type of response to send (e.g: 'ajax')
array<string, mixed> $options optional: Array of options to use

Returns

void

requestedWith() ¶ public

requestedWith(array<string>|string|null $type = null): mixed

Determines the content type of the data the client has sent (i.e. in a POST request)

Parameters

array<string>|string|null $type optional: Can be null (or no parameter), a string type name, or an array of types

Returns

mixed

respondAs() ¶ public

respondAs(string $type, array<string, mixed> $options = []): bool

Sets the response header based on type map index name. This wraps several methods available on {@link \Cake\Http\Response}. It also allows you to use Content-Type aliases.

Parameters

string $type: Friendly type name, i.e. 'html' or 'xml', or a full content-type, like 'application/x-shockwave'.
array<string, mixed> $options optional: If $type is a friendly type name that is associated with more than one type of content, $index is used to select which content-type to use.

Returns

bool

setConfig() ¶ public

setConfig(array<string, mixed>|string $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

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.

Returns

$this

Throws

Cake\Core\Exception\CakeException
When trying to set a key that is invalid.

startup() ¶ public

startup(Cake\Event\EventInterface $event): void

The startup method of the RequestHandler enables several automatic behaviors related to the detection of certain properties of the HTTP request, including:

If the XML data is POSTed, the data is parsed into an XML object, which is assigned to the $data property of the controller, which can then be saved to a model object.

Parameters

Cake\Event\EventInterface $event: The startup event that was fired.

Returns

void

Property Detail

`$_componentMap` ¶ protected

A component lookup table used to lazy load component objects.

Type

array<string, array>

`$_config` ¶ protected

Runtime config

Type

array<string, mixed>

`$_configInitialized` ¶ protected

Whether the config property has already been configured with defaults

Type

bool

`$_defaultConfig` ¶ protected

Default config

These are merged with user-provided config when the component is used.

checkHttpCache - Whether to check for HTTP cache. Default true.
viewClassMap - Mapping between type and view classes. If undefined JSON, XML, and AJAX will be mapped. Defining any types will omit the defaults.

Type

array<string, mixed>

`$_registry` ¶ protected

Component registry class used to lazy load components.

Type

Cake\Controller\ComponentRegistry

`$_renderType` ¶ protected

The template type to use when rendering the given content type.

Type

string|null

`$components` ¶ protected

Other Components this component uses.

Type

array

`$ext` ¶ protected

Contains the file extension parsed out by the Router

Type

string|null

Namespaces

Class RequestHandlerComponent

Property Summary

Method Summary

__construct() public

__debugInfo() public

__get() public

_configDelete() protected

_configRead() protected

_configWrite() protected

_setExtension() protected

accepts() public

beforeRender() public

configShallow() public

getConfig() public

getConfigOrFail() public

getController() public

implementedEvents() public

initialize() public

log() public

mapAlias() public

prefers() public

renderAs() public

requestedWith() public

respondAs() public

setConfig() public

startup() public

Method Detail

__construct() ¶ public

Parameters

__debugInfo() ¶ public

Returns

__get() ¶ public

Parameters

Returns

_configDelete() ¶ protected

Parameters

Returns

Throws

_configRead() ¶ protected

Parameters

Returns

_configWrite() ¶ protected

Parameters

Returns

Throws

_setExtension() ¶ protected

Parameters

Returns

accepts() ¶ public

Parameters

Returns

beforeRender() ¶ public

Parameters

Returns

Throws

configShallow() ¶ public

Parameters

Returns

getConfig() ¶ public

Usage

Parameters

Returns

getConfigOrFail() ¶ public

Parameters

Returns

Throws

getController() ¶ public

Returns

implementedEvents() ¶ public

Returns

initialize() ¶ public

Parameters

Returns

log() ¶ public

Parameters

Returns

mapAlias() ¶ public

Parameters

Returns

`$_componentMap` ¶ protected

`$_config` ¶ protected

`$_configInitialized` ¶ protected

`$_defaultConfig` ¶ protected

`$_registry` ¶ protected

`$_renderType` ¶ protected

`$components` ¶ protected

`$ext` ¶ protected