Class Router

Parses the request URL into controller, action, and parameters.

Object

Router

Package: cake\cake\libs
Copyright: Copyright 2005-2012, Cake Software Foundation, Inc. (http://cakefoundation.org)
License: The MIT License
Location: router.php

Properties summary

$__admin public

array

Caches admin setting from Configure class
$__currentRoute public

array

The route matching the URL of the current request
$__defaultsMapped public

boolean

Keeps Router state to determine if default routes have already been connected
$__headerMap public

array

HTTP header shortcut map. Used for evaluating header-based route expressions.
$__named public

array

'Constant' regular expression definitions for named route elements
$__params public

array

Maintains the parameter stack for the current request
$__parseExtensions public

boolean

Directive for Router to parse out file extensions for mapping to Content-types.
$__paths public

array

Maintains the path stack for the current request
$__prefixes public

array

List of action prefixes used in connected routes
$__resourceMap public

array

Default HTTP request method => controller action map.
$__resourceMapped public

array

List of resource-mapped controllers
$__validExtensions public

array

List of valid extensions to parse from a URL. If null, any extension is allowed.
$named public

string

Stores all information necessary to decide what named arguments are parsed under what conditions.
$routes public

array

Array of routes

Inherited Properties

_log

Method Summary

__connectDefaultRoutes() public

Connects the default, built-in routes, including admin routes, and (deprecated) web services routes.
__mapRoute() public

Merges URL parameters into a route string
__matchRoute() public

Checks to see if the given URL matches the given route
__parseExtension() public

Parses a file extension out of a URL, if Router::parseExtensions() is enabled.
compile() public

Compiles a route by numeric key and returns the compiled expression, replacing the existing uncompiled route. Do not call statically.
connect() public

Returns this object's routes array. Returns false if there are no routes available.
connectNamed() public

Specifies what named parameters CakePHP should be parsing. The most common setups are:
currentRoute() public

Returns the route matching the current request (useful for requestAction traces)
getArgs() public

Takes an passed params and converts it to args
getInstance() public

Gets a reference to the Router object instance
getNamedElements() public

Takes an array of URL parameters and separates the ones that can be used as named arguments
getNamedExpressions() public

Gets the named route elements for use in app/config/routes.php
getParam() public

Gets URL parameter by name
getParams() public

Gets parameter information
getPaths() public

Gets path information
mapResources() public

Creates REST resource routes for the given controller(s)
mapRouteElements() public

Maps a URL array onto a route and returns the string result, or false if no match
matchNamed() public

Return true if a given named $param's $val matches a given $rule depending on $context. Currently implemented rule types are controller, action and match that can be combined with each other.
normalize() public

Normalizes a URL for purposes of comparison. Will strip the base path off and replace any double /'s. It will not unify the casing and underscoring of the input value.
parse() public

Parses given URL and returns an array of controllers, action and parameters taken from that URL.
parseExtensions() public

Instructs the router to parse out file extensions from the URL. For example, http://example.com/posts.rss would yield an file extension of "rss". The file extension itself is made available in the controller as $this->params['url']['ext'], and is used by the RequestHandler component to automatically switch to alternate layouts and templates, and load helpers corresponding to the given content, i.e. RssHelper.
prefixes() public

Returns the list of prefixes used in connected routes
promote() public

Promote a route (by default, the last one added) to the beginning of the list
queryString() public

Generates a well-formed querystring from $q
reload() public

Reloads default Router settings
requestRoute() public

Returns the route matching the current request URL.
setRequestInfo() public

Takes parameter and path information back from the Dispatcher
stripEscape() public

Strip escape characters from parameter values.
stripPlugin() public

Removes the plugin name from the base URL.
url() public

Finds URL for specified action.
writeRoute() public

Builds a route regular expression

Method Detail

__connectDefaultRoutes() public ¶

__connectDefaultRoutes( )

Connects the default, built-in routes, including admin routes, and (deprecated) web services routes.

__mapRoute() public ¶

__mapRoute( array $route , array $params = array() )

Merges URL parameters into a route string

Parameters

array $route: Route
array $params optional array(): Parameters

Returns

string
Merged URL with parameters

__matchRoute() public ¶

__matchRoute( array $route , string $url )

Checks to see if the given URL matches the given route

Parameters

array $route
string $url

Returns

mixed
Boolean false on failure, otherwise array

__parseExtension() public ¶

__parseExtension( string $url )

Parses a file extension out of a URL, if Router::parseExtensions() is enabled.

Parameters

string $url

Returns

array
Returns an array containing the altered URL and the parsed extension.

compile() public ¶

compile( integer $i )

Compiles a route by numeric key and returns the compiled expression, replacing the existing uncompiled route. Do not call statically.

Parameters

integer $i

Returns

array
Returns an array containing the compiled route

connect() public ¶

connect( string $route , array $default = array() , array $params = array() )

Returns this object's routes array. Returns false if there are no routes available.

Parameters

string $route: An empty string, or a route string "/"
array $default optional array(): NULL or an array describing the default route
array $params optional array(): An array matching the named elements in the route to regular expressions which that element should match.

Returns

array
Array of routes

See

Router::$routes

connectNamed() public ¶

connectNamed( array $named , array $options = array() )

Specifies what named parameters CakePHP should be parsing. The most common setups are:

Do not parse any named parameters: {{{ Router::connectNamed(false); }}}

Parse only default parameters used for CakePHP's pagination: {{{ Router::connectNamed(false, array('default' => true)); }}}

Parse only the page parameter if its value is a number: {{{ Router::connectNamed(array('page' => '[\d]+'), array('default' => false, 'greedy' => false)); }}}

Parse only the page parameter no mater what. {{{ Router::connectNamed(array('page'), array('default' => false, 'greedy' => false)); }}}

Parse only the page parameter if the current action is 'index'. {{{ Router::connectNamed(array('page' => array('action' => 'index')), array('default' => false, 'greedy' => false)); }}}

Parse only the page parameter if the current action is 'index' and the controller is 'pages'. {{{ Router::connectNamed(array('page' => array('action' => 'index', 'controller' => 'pages')), array('default' => false, 'greedy' => false)); }}}

Parameters

array $named: A list of named parameters. Key value pairs are accepted where values are either regex strings to match, or arrays as seen above.
array $options optional array(): Allows to control all settings: separator, greedy, reset, default

Returns

array

currentRoute() public ¶

currentRoute( )

Returns the route matching the current request (useful for requestAction traces)

Returns

array
Matching route

getArgs() public ¶

getArgs( array $args , $options = array() )

Takes an passed params and converts it to args

Parameters

array $args: $params
$options optional array()

Returns

array
Array containing passed and named parameters

getInstance() public ¶

getInstance( )

boolean $current optional false: Current parameter

Returns

array

mapResources() public ¶

mapResources( mixed $controller , array $options = array() )

Creates REST resource routes for the given controller(s)

Options:

'id' - The regular expression fragment to use when matching IDs. By default, matches integer values and UUIDs.
'prefix' - URL prefix to use for the generated routes. Defaults to '/'.

Parameters

mixed $controller: A controller name or array of controller names (i.e. "Posts" or "ListItems")
array $options optional array(): Options to use when generating REST routes

mapRouteElements() public ¶

mapRouteElements( array $route , array $url )

Maps a URL array onto a route and returns the string result, or false if no match

Parameters

array $route: Route Route
array $url: URL URL to map

Returns

mixed
Result (as string) or false if no match

matchNamed() public ¶

matchNamed( string $param , string $val , array $rule , string $context = array() )

Return true if a given named $param's $val matches a given $rule depending on $context. Currently implemented rule types are controller, action and match that can be combined with each other.

Parameters

string $param: The name of the named parameter
string $val: The value of the named parameter
array $rule: The rule(s) to apply, can also be a match string
string $context optional array(): An array with additional context information (controller / action)

Returns

boolean

normalize() public ¶

normalize( mixed $url = '/' )

Normalizes a URL for purposes of comparison. Will strip the base path off and replace any double /'s. It will not unify the casing and underscoring of the input value.

Parameters

mixed $url optional '/': URL to normalize Either an array or a string url.

Returns

string
Normalized URL

parse() public ¶

parse( string $url )

Parses given URL and returns an array of controllers, action and parameters taken from that URL.

Parameters

string $url: URL to be parsed

Returns

array
Parsed elements from URL

parseExtensions() public ¶

parseExtensions( )

Instructs the router to parse out file extensions from the URL. For example, http://example.com/posts.rss would yield an file extension of "rss". The file extension itself is made available in the controller as $this->params['url']['ext'], and is used by the RequestHandler component to automatically switch to alternate layouts and templates, and load helpers corresponding to the given content, i.e. RssHelper.

A list of valid extension can be passed to this method, i.e. Router::parseExtensions('rss', 'xml'); If no parameters are given, anything after the first . (dot) after the last / in the URL will be parsed, excluding querystring parameters (i.e. ?q=...).

prefixes() public ¶

prefixes( )

requestRoute( )

Returns the route matching the current request URL.

Returns

array
Matching route

setRequestInfo() public ¶

setRequestInfo( array $params )

Takes parameter and path information back from the Dispatcher

Parameters

array $params: Parameters and path information

stripEscape() public ¶

stripEscape( mixed $param )

Strip escape characters from parameter values.

Parameters

mixed $param: Either an array, or a string

Returns

mixed
Array or string escaped

stripPlugin() public ¶

stripPlugin( string $base , string $plugin = null )

Removes the plugin name from the base URL.

Parameters

string $base: Base URL
string $plugin optional null: Plugin name

Returns

base
url with plugin name removed if present

url() public ¶

url( mixed $url = null , mixed $full = false )

Finds URL for specified action.

Returns an URL pointing to a combination of controller and action. Param $url can be:

Empty - the method will find adress to actuall controller/action.
'/' - the method will find base URL of application.
A combination of controller/action - the method will find url for it.

Parameters

mixed $url optional null: Cake-relative URL, like "/products/edit/92" or "/presidents/elect/4" or an array specifying any of the following: 'controller', 'action', and/or 'plugin', in addition to named arguments (keyed array elements), and standard URL arguments (indexed array elements)
mixed $full optional false: If (bool) true, the full base URL will be prepended to the result. If an array accepts the following keys - escape - used when making urls embedded in html escapes query string '&' - full - if true the full base URL will be prepended.

Returns

string
Full translated URL with base path.

writeRoute() public ¶

writeRoute( string $route , array $default , array $params )

Builds a route regular expression

Parameters

string $route: An empty string, or a route string "/"
array $default: NULL or an array describing the default route
array $params: An array matching the named elements in the route to regular expressions which that element should match.

Returns

array

See

Router::$routes

Methods inherited from Object

Object() public ¶

Object( )

A hack to support __construct() on PHP 4 Hint: descendant classes have no PHP4 class_name() constructors, so this constructor gets called first and calls the top-layer __construct() which (if present) should call parent::__construct()

Returns

Object

__construct() public ¶

__construct( )

Class constructor, overridden in descendant classes.

__openPersistent() public ¶

__openPersistent( string $name , string $type = null )

Open the persistent class file for reading Used by Object::_persist()

Parameters

string $name: Name of persisted class
string $type optional null: Type of persistance (e.g: registry)

_persist() public ¶

_persist( string $name , string $return , $object , $type = null )

Checks for a persistent class file, if found file is opened and true returned If file is not found a file is created and false returned If used in other locations of the model you should choose a unique name for the persistent file There are many uses for this method, see manual for examples

Parameters

string $name: name of the class to persist
string $return: $object the object to persist
$object
$type optional null

Returns

boolean
Success

_savePersistent() public ¶

_savePersistent( string $name , object $object )

You should choose a unique name for the persistent file

There are many uses for this method, see manual for examples

Parameters

string $name: name used for object to cache
object $object: the object to persist

Returns

boolean
true on save, throws error if file can not be created

_set() public ¶

_set( array $properties = array() )

Allows setting of multiple properties of the object in a single line of code.

Parameters

array $properties optional array(): An associative array containing properties and corresponding values.

_stop() public ¶

_stop( $status = 0 )

Stop execution of the current script

Parameters

$status optional 0: http://php.net/exit for values

cakeError() public ¶

cakeError( string $method , array $messages = array() )

Used to report user friendly errors. If there is a file app/error.php or app/app_error.php this file will be loaded error.php is the AppError class it should extend ErrorHandler class.

Parameters

string $method: Method to be called in the error class (AppError or ErrorHandler classes)
array $messages optional array(): Message that is to be displayed by the error class

Returns

error
message

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, and improves performance by using straight method calls in most cases.

Parameters

string $method: Name of the method to call
array $params optional array(): Parameter list to use when calling $method

Returns

mixed
Returns the result of the method call

log() public ¶

log( string $msg , integer $type = LOG_ERROR )

API for logging events.

Parameters

string $msg: Log message
integer $type optional LOG_ERROR: Error type constant. Defined in app/config/core.php.

Returns

boolean
Success of log write

requestAction() public ¶

requestAction( mixed $url , array $extra = array() )

Calls a controller's method from any location.

Parameters

mixed $url: String or array-based url.
array $extra optional array(): if array includes the key "return" it sets the AutoRender to true.

Returns

mixed

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

string
The name of this class

Properties detail

`$__admin` ¶

public array

Caches admin setting from Configure class

null

`$__currentRoute` ¶

public array

The route matching the URL of the current request

array()

`$__defaultsMapped` ¶

public boolean

Keeps Router state to determine if default routes have already been connected

false

`$__headerMap` ¶

public array

HTTP header shortcut map. Used for evaluating header-based route expressions.

array(
    'type'      => 'content_type',
    'method'    => 'request_method',
    'server'    => 'server_name'
)

`$__named` ¶

public array

'Constant' regular expression definitions for named route elements

array(
    'Action'    => 'index|show|add|create|edit|update|remove|del|delete|view|item',
    'Year'      => '[12][0-9]{3}',
    'Month'     => '0[1-9]|1[012]',
    'Day'       => '0[1-9]|[12][0-9]|3[01]',
    'ID'        => '[0-9]+',
    'UUID'      => '[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{12}'
)

`$__params` ¶

public array

Maintains the parameter stack for the current request

array()

`$__parseExtensions` ¶

public boolean

Directive for Router to parse out file extensions for mapping to Content-types.

false

`$__paths` ¶

public array

Maintains the path stack for the current request

array()

`$__prefixes` ¶

public array

List of action prefixes used in connected routes

array()

`$__resourceMap` ¶

public array

Default HTTP request method => controller action map.

array(
    array('action' => 'index',  'method' => 'GET',      'id' => false),
    array('action' => 'view',   'method' => 'GET',      'id' => true),
    array('action' => 'add',    'method' => 'POST',     'id' => false),
    array('action' => 'edit',   'method' => 'PUT',      'id' => true),
    array('action' => 'delete', 'method' => 'DELETE',   'id' => true),
    array('action' => 'edit',   'method' => 'POST',     'id' => true)
)

`$__resourceMapped` ¶

public array

List of resource-mapped controllers

array()

`$__validExtensions` ¶

public array

List of valid extensions to parse from a URL. If null, any extension is allowed.

null

`$named` ¶

public string

Stores all information necessary to decide what named arguments are parsed under what conditions.

array(
    'default' => array('page', 'fields', 'order', 'limit', 'recursive', 'sort', 'direction', 'step'),
    'greedy' => true,
    'separator' => ':',
    'rules' => false,
)

`$routes` ¶

public array

Array of routes

array()

Classes

Functions

Class Router

Properties summary

Inherited Properties

Method Summary

__connectDefaultRoutes() public

__mapRoute() public

__matchRoute() public

__parseExtension() public

compile() public

connect() public

connectNamed() public

currentRoute() public

getArgs() public

getInstance() public

getNamedElements() public

getNamedExpressions() public

getParam() public

getParams() public

getPaths() public

mapResources() public

mapRouteElements() public

matchNamed() public

normalize() public

parse() public

parseExtensions() public

prefixes() public

promote() public

queryString() public

reload() public

requestRoute() public

setRequestInfo() public

stripEscape() public

stripPlugin() public

url() public

writeRoute() public

Method Detail

__connectDefaultRoutes() public ¶

__mapRoute() public ¶

Parameters

Returns

__matchRoute() public ¶

Parameters

Returns

__parseExtension() public ¶

Parameters

Returns

compile() public ¶

Parameters

Returns

connect() public ¶

Parameters

Returns

See

connectNamed() public ¶

Parameters

Returns

currentRoute() public ¶

Returns

getArgs() public ¶

Parameters

Returns

getInstance() public ¶

Returns

getNamedElements() public ¶

Parameters

Returns

getNamedExpressions() public ¶

Returns

See

getParam() public ¶

Parameters

Returns

getParams() public ¶

Parameters

Returns

getPaths() public ¶

Parameters

Returns