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.
Link: http://book.cakephp.org/2.0/en/core-libraries/components/request-handling.html
Copyright: Copyright 2005-2012, Cake Software Foundation, Inc. (http://cakefoundation.org)
License: License (http://www.opensource.org/licenses/mit-license.php)
Location: Cake/Controller/Component/RequestHandlerComponent.php
Properties summary
-
$_inputTypeMapprotectedarrayA mapping between extensions and deserializers for request bodies of that type. By default only JSON and XML are mapped, use RequestHandlerComponent::addInputType()
-
$_renderTypeprotectedstringThe template to use when rendering the given content type. -
$ajaxLayoutpublicstringThe layout that will be switched to for Ajax requests -
$enabledpublicbooleanDetermines whether or not callbacks will be fired on this component -
$extpublicstringContains the file extension parsed out by the Router -
$requestpublicHolds the reference to Controller::$request -
$responsepublicHolds the reference to Controller::$response
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.
-
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 CakeRequest::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.
-
convertXml() public
Helper method to parse xml input data, due to lack of anonymous functions this lives here.
-
getAjaxVersion() public
Gets Prototype version if call is Ajax, otherwise empty string. The Prototype library sets a special "Prototype version" HTTP header.
-
getClientIP() public deprecated
Gets remote client IP -
getReferer() public deprecated
Gets the server name from which this request was referred -
initialize() public
Checks to see if a file extension has been parsed by the Router, or if the HTTP_ACCEPT_TYPE has matches only one content type with the supported extensions. If there is only one matching type between the supported content types & extensions, and the requested mime-types, RequestHandler::$ext is set to that value.
-
isAjax() public deprecated
Returns true if the current HTTP request is Ajax, false otherwise -
isAtom() public
Returns true if the current call accepts an Atom response, false otherwise -
isDelete() public deprecated
Returns true if the current call a DELETE request -
isFlash() public deprecated
Returns true if the current HTTP request is coming from a Flash-based client -
isGet() public deprecated
Returns true if the current call a GET request -
isMobile() public
Returns true if user agent string matches a mobile web browser, or if the client accepts WAP content.
-
isPost() public deprecated
Returns true if the current call a POST request -
isPut() public deprecated
Returns true if the current call a PUT request -
isRss() public
Returns true if the current call accepts an RSS response, false otherwise -
isSSL() public deprecated
Returns true if the current request is over HTTPS, 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) -
mapType() public deprecated
Maps a content-type back to an alias -
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 the layout and template paths for the content type defined by $type. -
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 CakeResponse. 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 -
setContent() public deprecated
Adds/sets the Content-type(s) for the given name. This method allows content-types to be mapped to friendly aliases (or extensions), which allows RequestHandler to automatically respond to requests of that type in the startup method.
-
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( ComponentCollection $collection , array $settings = array() )
Constructor. Parses the accepted content types accepted by the client using HTTP_ACCEPT
Parameters
-
ComponentCollection$collection - ComponentCollection object.
- array $settings optional array()
- Array of settings.
Overrides
_setExtension() protected ¶
_setExtension( )
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.
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.
accepts() public ¶
accepts( mixed $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 CakeRequest::accepts() this method deals entirely with mapped content types.
Usage:
$this->RequestHandler->accepts(array('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
- mixed $type optional null
Can be null (or no parameter), a string type name, or an array of types
Returns
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.
See
addInputType() public ¶
addInputType( string $type , array $handler )
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.
Throws
beforeRedirect() public ¶
beforeRedirect( Controller $controller , string|array $url , mixed $status = null , boolean $exit = true )
Handles (fakes) redirects for Ajax requests using requestAction()
Parameters
-
Controller$controller - A reference to the controller
- string|array $url
- A string or array containing the redirect location
- mixed $status optional null
- HTTP Status for redirect
- boolean $exit optional true
Overrides
beforeRender() public ¶
beforeRender( Controller $controller )
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
-
Controller$controller - Controller with components to beforeRender
Returns
false if the render process should be aborted
Params
Overrides
convertXml() public ¶
convertXml( string $xml )
Helper method to parse xml input data, due to lack of anonymous functions this lives here.
Parameters
- string $xml
Returns
Xml array data
getAjaxVersion() public ¶
getAjaxVersion( )
Gets Prototype version if call is Ajax, otherwise empty string. The Prototype library sets a special "Prototype version" HTTP header.
Returns
Prototype version of component making Ajax call
getClientIP() public deprecated ¶
getClientIP( boolean $safe = true )
Gets remote client IP
Deprecated
Parameters
- boolean $safe optional true
Returns
Client IP address
getReferer() public deprecated ¶
getReferer( )
Gets the server name from which this request was referred
Deprecated
Returns
Server address
initialize() public ¶
initialize( Controller $controller , array $settings = array() )
Checks to see if a file extension has been parsed by the Router, or if the HTTP_ACCEPT_TYPE has matches only one content type with the supported extensions. If there is only one matching type between the supported content types & extensions, and the requested mime-types, RequestHandler::$ext is set to that value.
Parameters
-
Controller$controller - A reference to the controller
- array $settings optional array()
- Array of settings to _set().
See
Overrides
isAjax() public deprecated ¶
isAjax( )
Returns true if the current HTTP request is Ajax, false otherwise
Deprecated
$this->request->is('ajax') instead.Returns
True if call is Ajax
isAtom() public ¶
isAtom( )
Returns true if the current call accepts an Atom response, false otherwise
Returns
True if client accepts an RSS response
isDelete() public deprecated ¶
isDelete( )
Returns true if the current call a DELETE request
Deprecated
Returns
True if call is a DELETE
isFlash() public deprecated ¶
isFlash( )
Returns true if the current HTTP request is coming from a Flash-based client
Deprecated
$this->request->is('flash') instead.Returns
True if call is from Flash
isGet() public deprecated ¶
isGet( )
Returns true if the current call a GET request
Deprecated
Returns
True if call is a GET
isMobile() public ¶
isMobile( )
Returns true if user agent string matches a mobile web browser, or if the client accepts WAP content.
Returns
True if user agent is a mobile web browser
isPost() public deprecated ¶
isPost( )
Returns true if the current call a POST request
Deprecated
Returns
True if call is a POST
isPut() public deprecated ¶
isPut( )
Returns true if the current call a PUT request
Deprecated
Returns
True if call is a PUT
isRss() public ¶
isRss( )
Returns true if the current call accepts an RSS response, false otherwise
Returns
True if client accepts an RSS response
isSSL() public deprecated ¶
isSSL( )
Returns true if the current request is over HTTPS, false otherwise.
Deprecated
$this->request->is('ssl') instead.Returns
True if call is over HTTPS
isXml() public ¶
isXml( )
Returns true if the current call accepts an XML response, false otherwise
Returns
True if client accepts an XML response
mapAlias() public ¶
mapAlias( mixed $alias )
Maps a content type alias back to its mime-type(s)
Parameters
- mixed $alias
- String alias to convert back into a content type. Or an array of aliases to map.
Returns
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.
mapType() public deprecated ¶
mapType( mixed $cType )
Maps a content-type back to an alias
Deprecated
Parameters
- mixed $cType
- Either a string content type to map, or an array of types.
Returns
Aliases for the types provided.
prefers() public ¶
prefers( mixed $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
- mixed $type optional null
An optional array of 'friendly' content-type names, i.e. 'html', 'xml', 'js', etc.
Returns
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.
See
renderAs() public ¶
renderAs( Controller $controller , string $type , array $options = array() )
Sets the layout and template paths for the content type defined by $type.
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', array('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()
- Array of options to use
See
RequestHandlerComponent::respondAs()
requestedWith() public ¶
requestedWith( mixed $type = null )
Determines the content type of the data the client has sent (i.e. in a POST request)
Parameters
- mixed $type optional null
- Can be null (or no parameter), a string type name, or an array of types
Returns
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 = array() )
Sets the response header based on type map index name. This wraps several methods available on CakeResponse. It also allows you to use Content-Type aliases.
Parameters
- mixed $type
Friendly type name, i.e. 'html' or 'xml', or a full content-type, like 'application/x-shockwave'.
- array $options optional array()
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
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.
See
responseType() public ¶
responseType( )
Returns the current response type (Content-type header), or null if not alias exists
Returns
A string content type alias, or raw content type if no alias map exists, otherwise null
setContent() public deprecated ¶
setContent( string $name , mixed $type = null )
Adds/sets the Content-type(s) for the given name. This method allows content-types to be mapped to friendly aliases (or extensions), which allows RequestHandler to automatically respond to requests of that type in the startup method.
Deprecated
$this->response->type() instead.Parameters
- string $name
- The name of the Content-type, i.e. "html", "xml", "css"
- mixed $type optional null
The Content-type or array of Content-types assigned to the name, i.e. "text/html", or "application/xml"
startup() public ¶
startup( Controller $controller )
The startup method of the RequestHandler enables several automatic behaviors related to the detection of certain properties of the HTTP request, including:
- Disabling layout rendering for Ajax requests (based on the HTTP_X_REQUESTED_WITH header)
- If Router::parseExtensions() is enabled, the layout and template type are
switched based on the parsed extension or Accept-Type header. For example, if
controller/action.xmlis requested, the view path becomesapp/View/Controller/xml/action.ctp. Also ifcontroller/actionis requested withAccept-Type: application/xmlin the headers the view path will becomeapp/View/Controller/xml/action.ctp. Layout and template types will only switch to mime-types recognized by CakeResponse. If you need to declare additional mime-types, you can do so using CakeResponse::type() in your controllers 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
-
Controller$controller - A reference to the controller
Overrides
Methods inherited from Component
__get() public ¶
__get( string $name )
Magic method for lazy loading $components.
Parameters
- string $name
- Name of component to get.
Returns
A Component object or null.
shutdown() public ¶
shutdown( Controller $controller )
Called after Controller::render() and before the output is printed to the browser.
Parameters
-
Controller$controller - Controller with components to shutdown
Link
Methods inherited from Object
_mergeVars() protected ¶
_mergeVars( array $properties , string $class , boolean $normalize = true )
Merges this objects $property with the property in $class' definition. This classes value for the property will be merged on top of $class'
This provides some of the DRY magic CakePHP provides. If you want to shut it off, redefine this method as an empty function.
Parameters
- array $properties
- The name of the properties to merge.
- string $class
- The class to merge the property with.
- boolean $normalize optional true
- Set to true to run the properties through Set::normalize() before merging.
_set() protected ¶
_set( array $properties = array() )
Allows setting of multiple properties of the object in a single line of code. Will only set properties that are part of a class declaration.
Parameters
- array $properties optional array()
- An associative array containing properties and corresponding values.
_stop() protected ¶
_stop( integer|string $status = 0 )
Stop execution of the current script. Wraps exit() making testing easier.
Parameters
- integer|string $status optional 0
- see http://php.net/exit for values
dispatchMethod() public ¶
dispatchMethod( string $method , array $params = array() )
Calls a method on this object with the given parameters. Provides an OO wrapper
for call_user_func_array
Parameters
- string $method
- Name of the method to call
- array $params optional array()
- Parameter list to use when calling $method
Returns
Returns the result of the method call
log() public ¶
log( string $msg , integer $type = LOG_ERROR )
Convenience method to write a message to CakeLog. See CakeLog::write() for more information on writing to logs.
Parameters
- string $msg
- Log message
- integer $type optional LOG_ERROR
- Error type constant. Defined in app/Config/core.php.
Returns
Success of log write
requestAction() public ¶
requestAction( mixed $url , array $extra = array() )
Calls a controller's method from any location. Can be used to connect controllers together or tie plugins into a main application. requestAction can be used to return rendered views or fetch the return value from controller actions.
Under the hood this method uses Router::reverse() to convert the $url parameter into a string URL. You should use URL formats that are compatible with Router::reverse()
Passing POST and GET data
POST and GET data can be simulated in requestAction. Use $extra['url'] for
GET data. The $extra['data'] parameter allows POST data simulation.
Parameters
- mixed $url
String or array-based url. Unlike other url arrays in CakePHP, this url will not automatically handle passed and named arguments in the $url parameter.
- array $extra optional array()
if array includes the key "return" it sets the AutoRender to true. Can also be used to submit GET/POST data, and named/passed arguments.
Returns
Boolean true or false on success/failure, or contents of rendered action if 'return' is set in $extra.
toString() public ¶
toString( )
Object-to-string conversion. Each class can override this method as necessary.
Returns
The name of this class
Properties detail
$_inputTypeMap ¶
A mapping between extensions and deserializers for request bodies of that type. By default only JSON and XML are mapped, use RequestHandlerComponent::addInputType()
array( 'json' => array('json_decode', true) )
$ajaxLayout ¶
The layout that will be switched to for Ajax requests
See
'ajax'