Class RequestHandlerComponent

Request object for handling alternative HTTP requests

Alternative HTTP requests can come from wireless units like mobile phones, palmtop computers, and the like. These units have no use for AJAX requests, and this Component can tell how Cake should respond to the different needs of a handheld computer and a desktop machine.

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

Property Summary

$_componentMap protected

array

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

array

Runtime config
$_configInitialized protected

bool

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

array

Default config
$_inputTypeMap protected

array

A mapping between extensions and deserializers for request bodies of that type. By default only JSON and XML are mapped, use RequestHandlerComponent::addInputType()
$_registry protected

Cake\Controller\ComponentRegistry

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

string

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

array

A mapping between type and viewClass. By default only JSON, XML, and AJAX are mapped. Use RequestHandlerComponent::viewClassMap() to manipulate this map.
$components public

array

Other Components this component uses.
$enabled public

bool

Determines whether or not callbacks will be fired on this component
$ext public

string

Contains the file extension parsed out by the Router
$request public

Cake\Network\Request

Request object
$response public

Cake\Network\Response

Holds the reference to Controller::$response

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

Delete a single config key
_configRead() protected

Read a config variable
_configWrite() protected

Write a config variable
_setExtension() protected

Set the extension based on the accept headers. 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.
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 Cake\Network\Request::accepts() this method deals entirely with mapped content types.
addInputType() public

Add a new mapped input type. Mapped input types are automatically converted by RequestHandlerComponent during the startup() callback.
beforeRedirect() public

Handles (fakes) redirects for AJAX requests using requestAction()
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.
config() public

Usage
configShallow() public

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

Helper method to parse xml input data, due to lack of anonymous functions this lives here.
implementedEvents() public

Events supported by this component.
initialize() public

Checks to see if a specific content type has been requested and sets RequestHandler::$ext accordingly. Checks the following in order: 1. The '_ext' value parsed by the Router. 2. A specific AJAX type request indicated by the presence of a header. 3. The Accept header. With the exception of an AJAX request indicated using the second header based method above, the type must have been configured in {@link Cake\Routing\Router}.
isAtom() public

Returns true if the current call accepts an Atom response, false otherwise
isMobile() public

Returns true if user agent string matches a mobile web browser, or if the client accepts WAP content.
isRss() public

Returns true if the current call accepts an RSS response, false otherwise
isWap() public

Returns true if the client accepts WAP content
isXml() public

Returns true if the current call accepts an XML response, false otherwise
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 Cake\Network\Response. It also allows you to use Content-Type aliases.
responseType() public

Returns the current response type (Content-type header), or null if not alias exists
startup() public

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

Getter/setter for viewClassMap

Method Detail

__construct() ¶ public

__construct(ComponentRegistry $registry, array $config = [])

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

Parameters

ComponentRegistry $registry: ComponentRegistry object.
array $config optional: Array of config.

__debugInfo() ¶ public

__debugInfo(): array

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

Returns

array

__get() ¶ public

__get(string $name): mixed

Magic method for lazy loading $components.

Parameters

string $name: Name of component to get.

Returns

mixed

A Component object or null.

_configDelete() ¶ protected

_configDelete(string $key): void

Delete 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

Read a config variable

Parameters

string|null $key: Key to read.

Returns

mixed

_configWrite() ¶ protected

_configWrite(string|array $key, mixed $value, bool|string $merge = false): void

Write a config variable

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

_setExtension() ¶ protected

_setExtension(Cake\Network\Request $request, Cake\Network\Response $response): void

Set the extension based on the accept headers. 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\Network\Request $request: The request instance.
Cake\Network\Response $response: The response instance.

Returns

void

accepts() ¶ public

accepts(string|array $type = null): mixed

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 Cake\Network\Request::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

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

Returns

mixed

If null or no parameter is passed, returns an array of content types the client accepts. If a string is passed, returns true if the client accepts it. If an array is passed, returns true if the client accepts one or more elements in the array.

addInputType() ¶ public

addInputType(string $type, array $handler): void

Add a new mapped input type. Mapped input types are automatically converted by RequestHandlerComponent during the startup() callback.

Parameters

string $type: The type alias being converted, ie. json
array $handler: The handler array for the type. The first index should be the handling callback, all other arguments should be additional parameters for the handler.

Returns

void

Throws

Cake\Core\Exception\Exception

beforeRedirect() ¶ public

beforeRedirect(Event $event, string|array $url, Cake\Network\Response $response): void|Cake\Network\Response

Handles (fakes) redirects for AJAX requests using requestAction()

Parameters

Event $event: The Controller.beforeRedirect event.
string|array $url: A string or array containing the redirect location
Cake\Network\Response $response: The response object.

Returns

void|Cake\Network\Response

The response object if the redirect is caught.

beforeRender() ¶ public

beforeRender(Event $event): bool

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.

Parameters

Event $event: The Controller.beforeRender event.

Returns

bool

false if the render process should be aborted

config() ¶ public

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

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(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->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: The value to set.

Returns

$this

The object itself.

convertXml() ¶ public

convertXml(string $xml): array

Helper method to parse xml input data, due to lack of anonymous functions this lives here.

Parameters

string $xml: XML string.

Returns

array

Xml array data

implementedEvents() ¶ public

implementedEvents(): array

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

initialize() ¶ public

initialize(array $config): void

Checks to see if a specific content type has been requested and sets RequestHandler::$ext accordingly. Checks the following in order: 1. The '_ext' value parsed by the Router. 2. A specific AJAX type request indicated by the presence of a header. 3. The Accept header. With the exception of an AJAX request indicated using the second header based method above, the type must have been configured in {@link Cake\Routing\Router}.

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

Parameters

array $config: The config data.

Returns

void

isAtom() ¶ public

isAtom(): bool

Returns true if the current call accepts an Atom response, false otherwise

Returns

bool

True if client accepts an RSS response

isMobile() ¶ public

isMobile(): bool

Returns true if user agent string matches a mobile web browser, or if the client accepts WAP content.

Returns

bool

True if user agent is a mobile web browser

isRss() ¶ public

isRss(): bool

Returns true if the current call accepts an RSS response, false otherwise

Returns

bool

True if client accepts an RSS response

isWap() ¶ public

isWap(): bool

Returns true if the client accepts WAP content

Returns

bool

isXml() ¶ public

isXml(): bool

Returns true if the current call accepts an XML response, false otherwise

Returns

bool

True if client accepts an XML response

log() ¶ public

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

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

Parameters

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

Returns

bool

Success of log write.

mapAlias() ¶ public

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

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

Parameters

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

Returns

string|null|array

Null on an undefined alias. String value of the mapped alias type. If an alias maps to more than one content type, the first one will be returned. If an array is provided for $alias, an array of mapped types will be returned.

prefers() ¶ public

prefers(string|array $type = null): mixed

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

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

Returns

mixed

If $type is null or not provided, the first content-type in the list, based on preference, is returned. If a single type is provided a boolean will be returned if that type is preferred. If an array of types are provided then the first preferred type is returned. If no type is provided the first preferred type is returned.

renderAs() ¶ public

renderAs(Controller $controller, string $type, array $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

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

Returns

void

requestedWith() ¶ public

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

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

Parameters

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

Returns

mixed

If a single type is supplied a boolean will be returned. If no type is provided The mapped value of CONTENT_TYPE will be returned. If an array is supplied the first type in the request content type will be returned.

respondAs() ¶ public

respondAs(string|array $type, array $options = []): bool

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

Parameters

string|array $type: Friendly type name, i.e. 'html' or 'xml', or a full content-type, like 'application/x-shockwave'.
array $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

Returns false if the friendly type name given in $type does not exist in the type map, or if the Content-type header has already been set by this method.

responseType() ¶ public

responseType(): mixed

Returns the current response type (Content-type header), or null if not alias exists

Returns

mixed

A string content type alias, or raw content type if no alias map exists, otherwise null

startup() ¶ public

startup(Event $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 Router::extensions() is enabled, the layout and template type are switched based on the parsed extension or Accept-Type header. For example, if controller/action.xml is requested, the view path becomes app/View/Controller/xml/action.ctp. Also if controller/action is requested with Accept-Type: application/xml in the headers the view path will become app/View/Controller/xml/action.ctp. Layout and template types will only switch to mime-types recognized by Cake\Network\Response. If you need to declare additional mime-types, you can do so using Cake\Network\Response::type() 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.
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

Event $event: The startup event that was fired.

Returns

void

viewClassMap() ¶ public

viewClassMap(array|string|null $type = null, array|null $viewClass = null): array|string

Getter/setter for viewClassMap

Parameters

array|string|null $type optional: The type string or array with format ['type' => 'viewClass'] to map one or more
array|null $viewClass optional: The viewClass to be used for the type without View appended

Returns

array|string

Returns viewClass when only string $type is set, else array with viewClassMap

Property Detail

`$_defaultConfig` ¶ protected

Default config

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

checkHttpCache - Whether to check for HTTP cache.
viewClassMap - Mapping between type and view class.

Property Summary

Method Summary

__construct() public

__debugInfo() public

__get() public

_configDelete() protected

_configRead() protected

_configWrite() protected

_setExtension() protected

accepts() public

addInputType() public

beforeRedirect() public

beforeRender() public

config() public

Usage

configShallow() public

convertXml() public

implementedEvents() public

initialize() public

isAtom() public

isMobile() public

isRss() public

isWap() public

isXml() public

log() public

mapAlias() public

prefers() public

renderAs() public

requestedWith() public

respondAs() public

responseType() public

startup() public

viewClassMap() 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

addInputType() ¶ public

Parameters

Returns

Throws

beforeRedirect() ¶ public

Parameters

Returns

beforeRender() ¶ public

Parameters

Returns

config() ¶ public

Usage

Parameters

Returns

Throws

configShallow() ¶ public

Parameters

Returns

convertXml() ¶ public

Parameters

`$_componentMap` ¶ protected

`$_config` ¶ protected

`$_configInitialized` ¶ protected

`$_defaultConfig` ¶ protected

`$_inputTypeMap` ¶ protected

`$_registry` ¶ protected

`$_renderType` ¶ protected

`$_viewClassMap` ¶ protected

`$components` ¶ public

`$enabled` ¶ public