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

Namespace: Cake\Routing

Constants

string

ACTION ¶

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

Regular expression for action names

string

DAY ¶
```
'0[1-9]|[12][0-9]|3[01]'
```
Regular expression for days
string

ID ¶
```
'[0-9]+'
```
Regular expression for auto increment IDs
string

MONTH ¶
```
'0[1-9]|1[012]'
```
Regular expression for months

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

Regular expression for UUIDs

string

YEAR ¶
```
'[12][0-9]{3}'
```
Regular expression for years

Property Summary

$_collection protected static

Cake\Routing\RouteCollection

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

list<string>

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

string

Default route class.
$_fullBaseUrl protected static

string|null

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<string, string>

Named expressions
$_request protected static

Cake\Http\ServerRequest|null

Maintains the request object reference.
$_requestContext protected static

array<string, mixed>

A hash of request context data.
$_routePaths protected static

array<string, mixed>

Cache of parsed route paths
$_urlFilters protected static

array<Closure>

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

Method Summary

_applyUrlFilters() protected static

Applies all the connected URL filters to the URL.
addUrlFilter() public static

Add a URL filter to 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.
getRouteCollection() public static

Get the RouteCollection inside the Router
normalize() public static

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

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

Parse a string route path
pathUrl() public static

Generate URL for route path.
reload() public static

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

Reset routes and related state.
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.
setRequest() public static

Set current request instance.
setRouteCollection() public static

Set the RouteCollection inside the Router
unwrapShortString() protected static

Inject route defaults from _path key
url() public static

Finds URL for specified action.

Method Detail

_applyUrlFilters() ¶ protected static

_applyUrlFilters(array $url): array

Applies all the connected URL filters to the URL.

Parameters

array $url: The URL array being modified.

Returns

array

addUrlFilter() ¶ public static

addUrlFilter(Closure $function): void

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

Closure $function: The function to add

Returns

void

createRouteBuilder() ¶ public static

createRouteBuilder(string $path, array<string, mixed> $options = []): Cake\Routing\RouteBuilder

Create a RouteBuilder for the provided path.

Parameters

string $path: The path to set the builder to.
array<string, mixed> $options optional: The options for the builder

Returns

Cake\Routing\RouteBuilder

defaultRouteClass() ¶ public static

defaultRouteClass(string|null $routeClass = null): string|null

Get or set default route class.

Parameters

string|null $routeClass optional: Class name.

Returns

string|null

extensions() ¶ public static

extensions(array<string>|string|null $extensions = null, bool $merge = true): list<string>

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 content type negotiation 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>|string|null $extensions optional: List of extensions to be added.
bool $merge optional: Whether to merge with or override existing extensions. Defaults to true.

Returns

list<string>

fullBaseUrl() ¶ public static

fullBaseUrl(string|null $base = null): string

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: the prefix for URLs generated containing the domain. For example: http://example.com

Returns

string

getNamedExpressions() ¶ public static

getNamedExpressions(): array<string, string>

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

Returns

array<string, string>

getRequest() ¶ public static

getRequest(): Cake\Http\ServerRequest|null

Get the current request object.

Returns

Cake\Http\ServerRequest|null

getRouteCollection() ¶ public static

getRouteCollection(): Cake\Routing\RouteCollection

Get the RouteCollection inside the Router

Returns

Cake\Routing\RouteCollection

normalize() ¶ public static

normalize(array|string $url = '/'): string

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

parseRequest() ¶ public static

parseRequest(Cake\Http\ServerRequest $request): array

Get the routing parameters for the request is possible.

Parameters

Cake\Http\ServerRequest $request: The request to parse request data from.

Returns

array

Throws

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

parseRoutePath() ¶ public static

parseRoutePath(string $url): array<string|int, string>

Parse a string route path

String examples:

Bookmarks::view
Admin/Bookmarks::view
Cms.Articles::edit
Vendor/Cms.Management/Admin/Articles::view

Parameters

string $url: Route path in [Plugin.][Prefix/]Controller::action format

Returns

array<string|int, string>

pathUrl() ¶ public static

pathUrl(string $path, array $params = [], bool $full = false): string

Generate URL for route path.

Route path examples:

Bookmarks::view
Admin/Bookmarks::view
Cms.Articles::edit
Vendor/Cms.Management/Admin/Articles::view

Parameters

string $path: Route path specifying controller and action, optionally with plugin and prefix.
array $params optional: An array specifying any additional parameters. Can be also any special parameters supported by Router::url().
bool $full optional: If true, the full base URL will be prepended to the result. Default is false.

Returns

string

reload() ¶ public static

reload(): void

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

Returns

void

resetRoutes() ¶ public static

resetRoutes(): void

Reset routes and related state.

Similar to reload() except that this doesn't reset all global state, as that leads to incorrect behavior in some plugin test case scenarios.

This method will reset:

routes
URL Filters
the initialized property

Extensions and default route classes will not be modified

Returns

void

reverse() ¶ public static

reverse(Cake\Http\ServerRequest|array $params, bool $full = false): string

Reverses a parsed parameter array into a string.

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

Parameters

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

Returns

string

reverseToArray() ¶ public static

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

Reverses a parsed parameter array into an array.

Parameters

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

Returns

array

routeExists() ¶ public static

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

Finds URL for specified action.

Returns a bool if the url exists

Usage

Parameters

array|string|null $url optional: 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.
bool $full optional: If true, the full base URL will be prepended to the result. Default is false.

Returns

bool

routes() ¶ public static

routes(): array<Cake\Routing\Route\Route>

Get the route scopes and their connected routes.

Returns

array<Cake\Routing\Route\Route>

setRequest() ¶ public static

setRequest(Cake\Http\ServerRequest $request): void

Set current request instance.

Parameters

Cake\Http\ServerRequest $request: request object.

Returns

void

setRouteCollection() ¶ public static

setRouteCollection(Cake\Routing\RouteCollection $routeCollection): void

Set the RouteCollection inside the Router

Parameters

Cake\Routing\RouteCollection $routeCollection: route collection

Returns

void

unwrapShortString() ¶ protected static

unwrapShortString(array $url): array

Inject route defaults from _path key

Parameters

array $url: Route array with _path key

Returns

array

url() ¶ public static

url(Psr\Http\Message\UriInterface|array|string|null $url = null, bool $full = false): string

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

Psr\Http\Message\UriInterface|array|string|null $url optional: 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 or it can be an UriInterface instance.
bool $full optional: If true, the full base URL will be prepended to the result. Default is false.

Returns

string

Throws

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

Property Detail

`$_collection` ¶ protected static

The route collection routes would be added to.

Type

Cake\Routing\RouteCollection

`$_defaultExtensions` ¶ protected static

Default extensions defined with Router::extensions()

Type

list<string>

`$_defaultRouteClass` ¶ protected static

Default route class.

Type

string

`$_fullBaseUrl` ¶ protected static

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

Type

string|null

`$_initialState` ¶ protected static

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.

Type

array

`$_namedExpressions` ¶ protected static

Named expressions

Type

array<string, string>

`$_request` ¶ protected static

Maintains the request object reference.

Type

Cake\Http\ServerRequest|null

`$_requestContext` ¶ protected static

A hash of request context data.

Type

array<string, mixed>

`$_routePaths` ¶ protected static

Cache of parsed route paths

Type

array<string, mixed>

`$_urlFilters` ¶ protected static

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

Type

array<Closure>

Namespaces

Class Router

Constants

Property Summary

Method Summary

_applyUrlFilters() protected static

addUrlFilter() public static

createRouteBuilder() public static

defaultRouteClass() public static

extensions() public static

fullBaseUrl() public static

getNamedExpressions() public static

getRequest() public static

getRouteCollection() public static

normalize() public static

parseRequest() public static

parseRoutePath() public static

pathUrl() public static

reload() public static

resetRoutes() public static

reverse() public static

reverseToArray() public static

routeExists() public static

routes() public static

setRequest() public static

setRouteCollection() public static

unwrapShortString() protected static

url() public static

Method Detail

_applyUrlFilters() ¶ protected static

Parameters

Returns

See Also

addUrlFilter() ¶ public static

Usage

Parameters

Returns

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 Also

getRequest() ¶ public static

Returns

getRouteCollection() ¶ public static

Returns

normalize() ¶ public static

Parameters

Returns

parseRequest() ¶ public static

Parameters

Returns

Throws

parseRoutePath() ¶ public static

Parameters

Returns

pathUrl() ¶ public static

Parameters

Returns

reload() ¶ public static

Returns

resetRoutes() ¶ public static

Returns

reverse() ¶ public static

Parameters

Returns

reverseToArray() ¶ public static

Parameters

Returns

`$_collection` ¶ protected static

`$_defaultExtensions` ¶ protected static

`$_defaultRouteClass` ¶ protected static

`$_fullBaseUrl` ¶ protected static

`$_initialState` ¶ protected static

`$_namedExpressions` ¶ protected static

`$_request` ¶ protected static

`$_requestContext` ¶ protected static

`$_routePaths` ¶ protected static

`$_urlFilters` ¶ protected static