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

Properties 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

  • $_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 public
    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 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.

  • renderAs() public

    Sets either the view class if one exists or the layout and template path of the view.

  • 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\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 $config)

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

Parameters

\Cake\Controller\ComponentRegistry $registry

ComponentRegistry object.

array $config optional

Array of config.

__debugInfo() public 

__debugInfo()

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

Returns

array

__get() public 

__get(string $name)

Magic method for lazy loading $components.

Parameters

string $name

Name of component to get.

Returns

\Cake\Controller\Component|null

A Component object or null.

_configDelete() protected 

_configDelete(string $key)

Deletes a single config key.

Parameters

string $key

Key to delete.

Throws

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

_configRead() protected 

_configRead(?string $key)

Reads a config key.

Parameters

string|null $key

Key to read.

Returns

mixed

_configWrite() protected 

_configWrite(mixed $key, mixed $value, mixed $merge)

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.

Throws

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

_setExtension() protected 

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

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.

accepts() public 

accepts(mixed $type)

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\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

string|array|null $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.

beforeRender() public 

beforeRender(\Cake\Event\EventInterface $event)

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 Cake\Http\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.

Parameters

\Cake\Event\EventInterface $event

The Controller.beforeRender event.

Throws

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

configShallow() public 

configShallow(mixed $key, mixed $value)

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

getConfig() public 

getConfig(?string $key, mixed $default)

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

Configuration data at the named key or null if the key does not exist.

getConfigOrFail() public 

getConfigOrFail(string $key)

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

Configuration data at the named key

Throws

InvalidArgumentException

getController() public 

getController()

Get the controller this component is bound to.

Returns

\Cake\Controller\Controller

The bound controller.

implementedEvents() public 

implementedEvents()

Events supported by this component.

Returns

array

initialize() public 

initialize(array $config)

Constructor hook method.

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

Parameters

array $config

The configuration settings provided to this component.

log() public 

log(string $message, mixed $level, mixed $context)

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

Parameters

string $message

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(mixed $alias)

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|array|null

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(mixed $type)

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|null $type optional

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

Returns

string|bool|null

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(\Cake\Controller\Controller $controller, string $type, array $options)

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 $options optional

Array of options to use

See Also

\Cake\Controller\Component\RequestHandlerComponent::respondAs()

requestedWith() public 

requestedWith(mixed $type)

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

Parameters

string|array|null $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(mixed $type, array $options)

Sets the response header based on type map index name. This wraps several methods available on 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 $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.

setConfig() public 

setConfig(mixed $key, mixed $value, mixed $merge)

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.

startup() public 

startup(\Cake\Event\EventInterface $event)

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.

Property Detail

$_componentMap protected

A component lookup table used to lazy load component objects.

Type

array

$_config protected

Runtime config

Type

array

$_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

$_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 public

Other Components this component uses.

Type

array

$ext protected

Contains the file extension parsed out by the Router

Type

string|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.0/class-Cake.Controller.Component.RequestHandlerComponent.html