Class Router

Parses the request URL into controller, action, and parameters. Uses the connected routes to match the incoming URL string to parameters that will allow the request to be dispatched. Also handles converting parameter lists into URL strings, using the connected routes. Routing allows you to decouple the way the world interacts with your application (URLs) and the implementation (controllers and actions).

Connecting routes

Connecting routes is done using Router::connect(). When parsing incoming requests or reverse matching parameters, routes are enumerated in the order they were connected. For more information on routes and how to connect them see Router::connect().

Namespace: Cake\Routing
Location: Routing/Router.php

Constants summary

string

ACTION ¶

'index|show|add|create|edit|update|remove|del|delete|view|item'
string

DAY ¶

'0[1-9]|[12][0-9]|3[01]'
string

ID ¶

'[0-9]+'
string

MONTH ¶

'0[1-9]|1[012]'
string

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}'
string

YEAR ¶

'[12][0-9]{3}'

Properties summary

$_collection protected static

Cake\Routing\RouteCollection

The route collection routes would be added to.
$_defaultExtensions protected static

array

Default extensions defined with Router::extensions()
$_defaultRouteClass protected static

string

Default route class.
$_fullBaseUrl protected static

string

Contains the base string that will be applied to all generated URLs For example https://example.com
$_initialState protected static

array

Initial state is populated the first time reload() is called which is at the bottom of this file. This is a cheat as get_class_vars() returns the value of static vars even if they have changed.
$_namedExpressions protected static

array

Named expressions
$_requestContext protected static

array

A hash of request context data.
$_requests protected static

array

Maintains the request object stack for the current request. This will contain more than one request object when requestAction is used.
$_urlFilters protected static

callable[]

The stack of URL filters to apply against routing URLs before passing the parameters to the route collection.
$initialized public static

boolean

Have routes been loaded

Method Summary

_applyUrlFilters() protected static

Applies all the connected URL filters to the URL.
_loadRoutes() protected static deprecated

Loads route configuration
addUrlFilter() public static

Add a URL filter to Router.
connect() public static

Connects a new Route in the router.
createRouteBuilder() public static

Create a RouteBuilder for the provided path.
defaultRouteClass() public static

Get or set default route class.
extensions() public static

Get or set valid extensions for all routes connected later.
fullBaseUrl() public static

Sets the full base URL that will be used as a prefix for generating fully qualified URLs for this application. If no parameters are passed, the currently configured value is returned.
getNamedExpressions() public static

Gets the named route patterns for use in config/routes.php
getRequest() public static

Get the current request object, or the first one.
getRouteCollection() public static

Get the RouteCollection inside the Router
mapResources() public static deprecated

Generate REST resource routes for the given controller(s).
normalize() public static

Normalizes a URL for purposes of comparison.
parse() public static deprecated

Parses given URL string. Returns 'routing' parameters for that URL.
parseNamedParams() public static deprecated

Provides legacy support for named parameters on incoming URLs.
parseRequest() public static

Get the routing parameters for the request is possible.
plugin() public static

Add plugin routes.
popRequest() public static

Pops a request off of the request stack. Used when doing requestAction
prefix() public static

Create prefixed routes.
pushRequest() public static

Push a request onto the request stack. Pushing a request sets the request context used when generating URLs.
redirect() public static deprecated

Connects a new redirection Route in the router.
reload() public static

Reloads default Router settings. Resets all class variables and removes all connected routes.
reverse() public static

Reverses a parsed parameter array into a string.
reverseToArray() public static

Reverses a parsed parameter array into an array.
routeExists() public static

Finds URL for specified action.
routes() public static

Get the route scopes and their connected routes.
scope() public static

Create a routing scope.
setRequestContext() public static

Store the request context for a given request.
setRequestInfo() public static

Takes parameter and path information back from the Dispatcher, sets these parameters as the current request parameters that are merged with URL arrays created later in the request.
setRouteCollection() public static

Set the RouteCollection inside the Router
url() public static

Finds URL for specified action.

Method Detail

_applyUrlFilters() protected static ¶

_applyUrlFilters( array $url )

Applies all the connected URL filters to the URL.

Parameters

array $url: The URL array being modified.

Returns

array
The modified URL.

See

\Cake\Routing\Router::url()
\Cake\Routing\Router::addUrlFilter()

_loadRoutes() protected static deprecated ¶

_loadRoutes( )

Loads route configuration

Deprecated

3.5.0 Routes will be loaded via the Application::routes() hook in 4.0.0

addUrlFilter() public static ¶

addUrlFilter( callable $function )

Add a URL filter to Router.

URL filter functions are applied to every array $url provided to Router::url() before the URLs are sent to the route collection.

Callback functions should expect the following parameters:

$params The URL params being processed.
$request The current request.

The URL filter function should always return the params even if unmodified.

Usage

URL filters allow you to easily implement features like persistent parameters.

Router::addUrlFilter(function ($params, $request) {
 if ($request->getParam('lang') && !isset($params['lang'])) {
   $params['lang'] = $request->getParam('lang');
 }
 return $params;
});

Parameters

callable $function: The function to add

connect() public static ¶

connect( string $route , array|string $defaults = [] , array $options = [] )

Connects a new Route in the router.

Compatibility proxy to \Cake\Routing\RouteBuilder::connect() in the / scope.

Parameters

string $route: A string describing the template of the route
array|string $defaults optional []: An array describing the default route parameters. These parameters will be used by default and can supply routing parameters that are not dynamic. See above.
array $options optional []: An array matching the named elements in the route to regular expressions which that element should match. Also contains additional parameters such as which routed parameters should be shifted into the passed arguments, supplying patterns for routing parameters and supplying the name of a custom routing class.

Throws

Cake\Core\Exception\Exception

See

\Cake\Routing\RouteBuilder::connect()
\Cake\Routing\Router::scope()

createRouteBuilder() public static ¶

createRouteBuilder( string $path , array $options = [] )

Create a RouteBuilder for the provided path.

Parameters

string $path: The path to set the builder to.
array $options optional []: The options for the builder

Returns

Cake\Routing\RouteBuilder

defaultRouteClass() public static ¶

defaultRouteClass( string|null $routeClass = null )

Get or set default route class.

Parameters

string|null $routeClass optional null: Class name.

Returns

string|null

extensions() public static ¶

extensions( array|string|null $extensions = null , boolean $merge = true )

Get or set valid extensions for all routes connected later.

Instructs the router to parse out file extensions from the URL. For example, http://example.com/posts.rss would yield a file extension of "rss". The file extension itself is made available in the controller as $this->request->getParam('_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. Switching layouts and helpers requires that the chosen extension has a defined mime type in Cake\Http\Response.

A string or an array of valid extensions can be passed to this method. If called without any parameters it will return current list of set extensions.

Parameters

array|string|null $extensions optional null: List of extensions to be added.
boolean $merge optional true: Whether to merge with or override existing extensions. Defaults to true.

Returns

array
Array of extensions Router is configured to parse.

fullBaseUrl() public static ¶

fullBaseUrl( string|null $base = null )

Sets the full base URL that will be used as a prefix for generating fully qualified URLs for this application. If no parameters are passed, the currently configured value is returned.

Note:

If you change the configuration value App.fullBaseUrl during runtime and expect the router to produce links using the new setting, you are required to call this method passing such value again.

Parameters

string|null $base optional null: the prefix for URLs generated containing the domain. For example: http://example.com

Returns

string

getNamedExpressions() public static ¶

getNamedExpressions( )

Gets the named route patterns for use in config/routes.php

Returns

array
Named route elements

See

\Cake\Routing\Router::$_namedExpressions

getRequest() public static ¶

getRequest( boolean $current = false )

Get the current request object, or the first one.

Parameters

boolean $current optional false: True to get the current request, or false to get the first one.

Returns

Cake\Http\ServerRequest|null

getRouteCollection() public static ¶

getRouteCollection( )

Get the RouteCollection inside the Router

Returns

Cake\Routing\RouteCollection

mapResources() public static deprecated ¶

mapResources( string|array $controller , array $options = [] )

Generate REST resource routes for the given controller(s).

Compatibility proxy to \Cake\Routing\RouteBuilder::resources(). Additional, compatibility around prefixes and plugins and prefixes is handled by this method.

A quick way to generate a default routes to a set of REST resources (controller(s)).

Usage

Connect resource routes for an app controller:

Router::mapResources('Posts');

Connect resource routes for the Comment controller in the Comments plugin:

Router::mapResources('Comments.Comment');

Plugins will create lower_case underscored resource routes. e.g /comments/comment

Connect resource routes for the Posts controller in the Admin prefix:

Router::mapResources('Posts', ['prefix' => 'admin']);

Prefixes will create lower_case underscored resource routes. e.g /admin/posts

Options:

'id' - The regular expression fragment to use when matching IDs. By default, matches integer values and UUIDs.
'prefix' - Routing prefix to use for the generated routes. Defaults to ''. Using this option will create prefixed routes, similar to using Routing.prefixes.
'only' - Only connect the specific list of actions.
'actions' - Override the method names used for connecting actions.
'map' - Additional resource routes that should be connected. If you define 'only' and 'map', make sure that your mapped methods are also in the 'only' list.
'path' - Change the path so it doesn't match the resource name. E.g ArticlesController is available at /posts

Deprecated

3.3.0 Use Router::scope() and RouteBuilder::resources() instead.

Parameters

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

See

\Cake\Routing\RouteBuilder::resources()

normalize() public static ¶

normalize( array|string $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

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

Returns

string
Normalized URL

parse() public static deprecated ¶

parse( string $url , string $method = '' )

Parses given URL string. Returns 'routing' parameters for that URL.

Deprecated

3.4.0 Use Router::parseRequest() instead.

Parameters

string $url: URL to be parsed.
string $method optional '': The HTTP method being used.

Returns

array
Parsed elements from URL.

Throws

Cake\Routing\Exception\MissingRouteException
When a route cannot be handled

parseNamedParams() public static deprecated ¶

parseNamedParams( Cake\Http\ServerRequest $request , array $options = [] )

Provides legacy support for named parameters on incoming URLs.

Checks the passed parameters for elements containing $options['separator'] Those parameters are split and parsed as if they were old style named parameters.

The parsed parameters will be moved from params['pass'] to params['named'].

Options

separator The string to use as a separator. Defaults to :.

Deprecated

3.3.0 Named parameter backwards compatibility will be removed in 4.0.

Parameters

Cake\Http\ServerRequest $request: The request object to modify.
array $options optional []: The array of options.

Returns

Cake\Http\ServerRequest
The modified request

parseRequest() public static ¶

parseRequest( Psr\Http\Message\ServerRequestInterface $request )

Get the routing parameters for the request is possible.

Parameters

Psr\Http\Message\ServerRequestInterface $request: The request to parse request data from.

Returns

array
Parsed elements from URL.

Throws

Cake\Routing\Exception\MissingRouteException
When a route cannot be handled

plugin() public static ¶

plugin( string $name , array|callable $options = [] , callable|null $callback = null )

Add plugin routes.

This method creates a scoped route collection that includes relevant plugin information.

The plugin name will be inflected to the underscore version to create the routing path. If you want a custom path name, use the path option.

Routes connected in the scoped collection will have the correct path segment prepended, and have a matching plugin routing key set.

Parameters

string $name: The plugin name to build routes for
array|callable $options optional []: Either the options to use, or a callback
callable|null $callback optional null: The callback to invoke that builds the plugin routes. Only required when $options is defined

popRequest() public static ¶

popRequest( )

Pops a request off of the request stack. Used when doing requestAction

Returns

Cake\Http\ServerRequest
The request removed from the stack.

See

\Cake\Routing\Router::pushRequest()
\Cake\Routing\RequestActionTrait::requestAction()

prefix() public static ¶

prefix( string $name , array|callable $params = [] , callable|null $callback = null )

Create prefixed routes.

This method creates a scoped route collection that includes relevant prefix information.

The path parameter is used to generate the routing parameter name. For example a path of admin would result in 'prefix' => 'admin' being applied to all connected routes.

The prefix name will be inflected to the underscore version to create the routing path. If you want a custom path name, use the path option.

You can re-open a prefix as many times as necessary, as well as nest prefixes. Nested prefixes will result in prefix values like admin/api which translates to the Controller\Admin\Api\ namespace.

Parameters

string $name: The prefix name to use.
array|callable $params optional []: An array of routing defaults to add to each connected route. If you have no parameters, this argument can be a callable.
callable|null $callback optional null: The callback to invoke that builds the prefixed routes.

pushRequest() public static ¶

pushRequest( Cake\Http\ServerRequest $request )

Push a request onto the request stack. Pushing a request sets the request context used when generating URLs.

Parameters

Cake\Http\ServerRequest $request: Request instance.

redirect() public static deprecated ¶

redirect( string $route , array|string $url , array $options = [] )

Connects a new redirection Route in the router.

Compatibility proxy to \Cake\Routing\RouteBuilder::redirect() in the / scope.

Deprecated

3.3.0 Use Router::scope() and RouteBuilder::redirect() instead.

Parameters

string $route: A string describing the template of the route
array|string $url: A URL to redirect to. Can be a string or a Cake array-based URL
array $options optional []: An array matching the named elements in the route to regular expressions which that element should match. Also contains additional parameters such as which routed parameters should be shifted into the passed arguments. As well as supplying patterns for routing parameters.

See

\Cake\Routing\RouteBuilder::redirect()

reload() public static ¶

reload( )

Reloads default Router settings. Resets all class variables and removes all connected routes.

reverse() public static ¶

reverse( Cake\Http\ServerRequest|array $params , boolean $full = false )

Reverses a parsed parameter array into a string.

Works similarly to Router::url(), but since parsed URL's contain additional 'pass' as well as 'url.url' keys. Those keys need to be specially handled in order to reverse a params array into a string URL.

This will strip out 'autoRender', 'bare', 'requested', and 'return' param names as those are used for CakePHP internals and should not normally be part of an output URL.

Parameters

Cake\Http\ServerRequest|array $params: The params array or Cake\Http\ServerRequest object that needs to be reversed.
boolean $full optional false: Set to true to include the full URL including the protocol when reversing the URL.

Returns

string
The string that is the reversed result of the array

reverseToArray() public static ¶

reverseToArray( Cake\Http\ServerRequest|array $params )

Reverses a parsed parameter array into an array.

This will strip out 'autoRender', 'bare', 'requested', and 'return' param names as those are used for CakePHP internals and should not normally be part of an output URL.

Parameters

Cake\Http\ServerRequest|array $params: The params array or Cake\Http\ServerRequest object that needs to be reversed.

Returns

array
The URL array ready to be used for redirect or HTML link.

routeExists() public static ¶

routeExists( string|array|null $url = null , boolean $full = false )

Finds URL for specified action.

Returns a bool if the url exists

Usage

Parameters

string|array|null $url optional null: An array specifying any of the following: 'controller', 'action', 'plugin' additionally, you can provide routed elements or query string parameters. If string it can be name any valid url string.
boolean $full optional false: If true, the full base URL will be prepended to the result. Default is false.

Returns

boolean

See

Router::url()

routes() public static ¶

routes( )

Get the route scopes and their connected routes.

Returns

Cake\Routing\Route\Route[]

scope() public static ¶

scope( string $path , array|callable $params = [] , callable|null $callback = null )

Create a routing scope.

Routing scopes allow you to keep your routes DRY and avoid repeating common path prefixes, and or parameter sets.

Scoped collections will be indexed by path for faster route parsing. If you re-open or re-use a scope the connected routes will be merged with the existing ones.

Options

The $params array allows you to define options for the routing scope. The options listed below are not available to be used as routing defaults

routeClass The route class to use in this scope. Defaults to Router::defaultRouteClass()
extensions The extensions to enable in this scope. Defaults to the globally enabled extensions set with Router::extensions()

Example

Router::scope('/blog', ['plugin' => 'Blog'], function ($routes) {
   $routes->connect('/', ['controller' => 'Articles']);
});

The above would result in a /blog/ route being created, with both the plugin & controller default parameters set.

You can use Router::plugin() and Router::prefix() as shortcuts to creating specific kinds of scopes.

Parameters

string $path: The path prefix for the scope. This path will be prepended to all routes connected in the scoped collection.
array|callable $params optional []: An array of routing defaults to add to each connected route. If you have no parameters, this argument can be a callable.
callable|null $callback optional null: The callback to invoke with the scoped collection.

Throws

InvalidArgumentException
When an invalid callable is provided.

setRequestContext() public static ¶

setRequestContext( Psr\Http\Message\ServerRequestInterface $request )

Store the request context for a given request.

Parameters

Psr\Http\Message\ServerRequestInterface $request: The request instance.

Throws

InvalidArgumentException
When parameter is an incorrect type.

setRequestInfo() public static ¶

setRequestInfo( Cake\Http\ServerRequest|array $request )

Takes parameter and path information back from the Dispatcher, sets these parameters as the current request parameters that are merged with URL arrays created later in the request.

Nested requests will create a stack of requests. You can remove requests using Router::popRequest(). This is done automatically when using Object::requestAction().

Will accept either a Cake\Http\ServerRequest object or an array of arrays. Support for accepting arrays may be removed in the future.

Parameters

Cake\Http\ServerRequest|array $request: Parameters and path information or a Cake\Http\ServerRequest object.

Deprecatd

3.6.0 Support for arrays will be removed in 4.0.0

setRouteCollection() public static ¶

setRouteCollection( RouteCollection $routeCollection )

Set the RouteCollection inside the Router

Parameters

RouteCollection $routeCollection: route collection

url() public static ¶

url( string|array|null $url = null , boolean $full = false )

Finds URL for specified action.

Returns a URL pointing to a combination of controller and action.

Usage

Router::url('/posts/edit/1'); Returns the string with the base dir prepended. This usage does not use reverser routing.
Router::url(['controller' => 'posts', 'action' => 'edit']); Returns a URL generated through reverse routing.
Router::url(['_name' => 'custom-name', ...]); Returns a URL generated through reverse routing. This form allows you to leverage named routes.

There are a few 'special' parameters that can change the final URL string that is generated

_base - Set to false to remove the base path from the generated URL. If your application is not in the root directory, this can be used to generate URLs that are 'cake relative'. cake relative URLs are required when using requestAction.
_scheme - Set to create links on different schemes like webcal or ftp. Defaults to the current scheme.
_host - Set the host to use for the link. Defaults to the current host.
_port - Set the port if you need to create links on non-standard ports.
_full - If true output of Router::fullBaseUrl() will be prepended to generated URLs.
# - Allows you to set URL hash fragments.
_ssl - Set to true to convert the generated URL to https, or false to force http.
_name - Name of route. If you have setup named routes you can use this key to specify it.

Parameters

string|array|null $url optional null: An array specifying any of the following: 'controller', 'action', 'plugin' additionally, you can provide routed elements or query string parameters. If string it can be name any valid url string.
boolean $full optional false: If true, the full base URL will be prepended to the result. Default is false.

Returns

string
Full translated URL with base path.

Throws

Cake\Core\Exception\Exception
When the route name is not found

Properties detail

`$_collection` ¶

protected static Cake\Routing\RouteCollection

The route collection routes would be added to.

`$_defaultExtensions` ¶

protected static array

Default extensions defined with Router::extensions()

[]

`$_defaultRouteClass` ¶

protected static string

Default route class.

'Cake\Routing\Route\Route'

`$_fullBaseUrl` ¶

protected static string

Contains the base string that will be applied to all generated URLs For example https://example.com

`$_initialState` ¶

protected static array

Initial state is populated the first time reload() is called which is at the bottom of this file. This is a cheat as get_class_vars() returns the value of static vars even if they have changed.

[]

`$_namedExpressions` ¶

protected static array

Named expressions

[
    'Action' => Router::ACTION,
    'Year' => Router::YEAR,
    'Month' => Router::MONTH,
    'Day' => Router::DAY,
    'ID' => Router::ID,
    'UUID' => Router::UUID
]

`$_requestContext` ¶

protected static array

A hash of request context data.

[]

`$_requests` ¶

protected static array

Maintains the request object stack for the current request. This will contain more than one request object when requestAction is used.

[]

`$_urlFilters` ¶

protected static callable[]

The stack of URL filters to apply against routing URLs before passing the parameters to the route collection.

[]

`$initialized` ¶

public static boolean

Have routes been loaded

Deprecated

3.5.0 Routes will be loaded via the Application::routes() hook in 4.0.0

false

Namespaces

Classes

Traits

Class Router

Connecting routes

Constants summary

Properties summary

Method Summary

_applyUrlFilters() protected static

_loadRoutes() protected static deprecated

addUrlFilter() public static

connect() public static

createRouteBuilder() public static

defaultRouteClass() public static

extensions() public static

fullBaseUrl() public static

getNamedExpressions() public static

getRequest() public static

getRouteCollection() public static

mapResources() public static deprecated

normalize() public static

parse() public static deprecated

parseNamedParams() public static deprecated

parseRequest() public static

plugin() public static

popRequest() public static

prefix() public static

pushRequest() public static

redirect() public static deprecated

reload() public static

reverse() public static

reverseToArray() public static

routeExists() public static

routes() public static

scope() public static

setRequestContext() public static

setRequestInfo() public static

setRouteCollection() public static

url() public static

Method Detail

_applyUrlFilters() protected static ¶

Parameters

Returns

See

_loadRoutes() protected static deprecated ¶

Deprecated

addUrlFilter() public static ¶

Usage

Parameters

connect() public static ¶

Parameters

Throws

See

createRouteBuilder() public static ¶

Parameters

Returns

defaultRouteClass() public static ¶

Parameters

Returns

extensions() public static ¶

Parameters

Returns

fullBaseUrl() public static ¶

Note:

Parameters

Returns

getNamedExpressions() public static ¶

Returns

See

getRequest() public static ¶

Parameters

Returns

getRouteCollection() public static ¶

Returns

mapResources() public static deprecated ¶

Usage

Options:

Deprecated

Parameters

See

`$_collection` ¶

`$_defaultExtensions` ¶

`$_defaultRouteClass` ¶

`$_fullBaseUrl` ¶