W3cubDocs

/CakePHP 3.4

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.

Cake\Controller\Component implements Cake\Event\EventListenerInterface uses Cake\Core\InstanceConfigTrait , Cake\Log\LogTrait
Extended by Cake\Controller\Component\RequestHandlerComponent

Properties summary

  • $_defaultConfig protected
    array
    Default config
  • $_renderType protected
    string|null
    The template to use when rendering the given content type.
  • $ajaxLayout public
    string
    Set the layout to be used when rendering the AuthComponent's ajaxLogin element.
  • $enabled public
    boolean
  • $ext public
    string|null
    Contains the file extension parsed out by the Router

Inherited Properties

Method Summary

  • __construct() public
    Constructor. Parses the accepted content types accepted by the client using HTTP_ACCEPT
  • _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.

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

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

  • convertXml() public

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

  • Events supported by this component.
  • initialize() public
  • 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
  • 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.

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

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

  • Getter/setter for viewClassMap

Method Detail

__construct()source 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.

Overrides

Cake\Controller\Component::__construct()

_setExtension()source protected

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

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\Http\ServerRequest $request
The request instance.
Cake\Network\Response $response
The response instance.

accepts()source public

accepts( string|array|null $type 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 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|null $type optional null

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()source public

addInputType( string $type , array $handler )

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

Deprecated

3.1.0 Use setConfig('addInputType', ...) instead.

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.

Throws

Cake\Core\Exception\Exception

beforeRedirect()source public

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

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

Deprecated

3.3.5 This functionality will be removed in 4.0.0. You can disable this function now by setting the enableBeforeRedirect config option to false.


Parameters

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

Cake\Network\Response|null
The response object if the redirect is caught.

beforeRender()source public

beforeRender( Cake\Event\Event $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 app/View/Controller/xml/action.ctp. Also if controller/action is requested with Accept: 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.

Parameters

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

Returns

boolean
false if the render process should be aborted

convertXml()source public

convertXml( string $xml )

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()source public

implementedEvents( )

Events supported by this component.

Returns

array

Overrides

Cake\Controller\Component::implementedEvents()

initialize()source public

initialize( array $config )

Deprecated

3.4.0 Unused. To be removed in 4.0.0

Parameters

array $config
The config data.

Overrides

Cake\Controller\Component::initialize()

isAtom()source public

isAtom( )

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

Returns

boolean
True if client accepts an RSS response

isMobile()source public

isMobile( )

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

Returns

boolean
True if user agent is a mobile web browser

isRss()source public

isRss( )

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

Returns

boolean
True if client accepts an RSS response

isWap()source public

isWap( )

Returns true if the client accepts WAP content

Returns

boolean

isXml()source public

isXml( )

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

Returns

boolean
True if client accepts an XML response

mapAlias()source public

mapAlias( string|array $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|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()source public

prefers( string|array|null $type 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

string|array|null $type optional null

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

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

requestedWith()source public

requestedWith( string|array|null $type null )

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

Parameters

string|array|null $type optional null
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()source public

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

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

boolean

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()source public

responseType( )

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()source public

startup( Cake\Event\Event $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\Event $event
The startup event that was fired.

viewClassMap()source public

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

Getter/setter for viewClassMap

Deprecated

3.1.0 Use setConfig('viewClassMap', ...) instead.

Parameters

array|string|null $type optional null
The type string or array with format ['type' => 'viewClass'] to map one or more
array|null $viewClass optional null
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

Methods inherited from Cake\Controller\Component

__debugInfo()source public

__debugInfo( )

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

Returns

array

__get()source public

__get( string $name )

Magic method for lazy loading $components.

Parameters

string $name
Name of component to get.

Returns

mixed
A Component object or null.

getController()source public

getController( )

Get the controller this component is bound to.

Returns

Cake\Controller\Controller
The bound controller.

Methods used from Cake\Core\InstanceConfigTrait

_configDelete()source 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()source protected

_configRead( string|null $key )

Reads a config key.

Parameters

string|null $key
Key to read.

Returns

mixed

_configWrite()source protected

_configWrite( string|array $key , mixed $value , boolean|string $merge false )

Writes a config key.

Parameters

string|array $key
Key to write to.
mixed $value
Value to write.
boolean|string $merge optional false

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

config()source public

config( string|array|null $key null , mixed|null $value null , boolean $merge true )

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

Deprecated

3.4.0 use setConfig()/getConfig() instead.

Parameters

string|array|null $key optional null
The key to get/set, or a complete array of configs.
mixed|null $value optional null
The value to set.
boolean $merge optional true
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()source public

configShallow( string|array $key , mixed|null $value null )

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

Returns


$this

getConfig()source public

getConfig( string|null $key 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');

Parameters

string|null $key optional null
The key to get or null for the whole config.

Returns

mixed
Config value being read.

setConfig()source public

setConfig( string|array $key , mixed|null $value null , boolean $merge true )

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 null
The value to set.
boolean $merge optional true
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.

Methods used from Cake\Log\LogTrait

log()source public

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

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

Parameters

mixed $msg
Log message.
integer|string $level optional LogLevel::ERROR
Error level.
string|array $context optional []
Additional log data relevant to this message.

Returns

boolean
Success of log write.

Properties detail

$_defaultConfigsource

protected array

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 classes. If undefined json, xml, and ajax will be mapped. Defining any types will omit the defaults.
  • inputTypeMap - A mapping between types and deserializers for request bodies. If undefined json & xml will be mapped. Defining any types will omit the defaults.
  • enableBeforeRedirect - Set to false to disable the beforeRedirect callback. The beforeRedirect functionality has been deprecated.
[
    'checkHttpCache' => true,
    'viewClassMap' => [],
    'inputTypeMap' => [],
    'enableBeforeRedirect' => true
]

$_renderTypesource

protected string|null

The template to use when rendering the given content type.

null

$ajaxLayoutsource

public string

Set the layout to be used when rendering the AuthComponent's ajaxLogin element.

Deprecated

3.3.11 This feature property is not supported and will be removed in 4.0.0


$enabledsource

public boolean

Deprecated

3.4.0 Unused. Will be removed in 4.0.0
true

$extsource

public string|null

Contains the file extension parsed out by the Router

See

\Cake\Routing\Router::extensions()
null

© 2005–2017 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/3.4/class-Cake.Controller.Component.RequestHandlerComponent.html