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().
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
array<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
Maintains the request object reference.
-
$_requestContext protected static
array
A hash of request context data.
-
$_routePaths protected static
array
Cache of parsed route paths
-
$_urlFilters protected static
array<callable>
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.
-
connect() public static deprecated
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.
-
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.
-
plugin() public static deprecated
Add plugin routes.
-
prefix() public static deprecated
Create prefixed routes.
-
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.
-
scope() public static deprecated
Create a routing scope.
-
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
See Also
\Cake\Routing\Router::addUrlFilter()
addUrlFilter() ¶ public static
addUrlFilter(callable $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
-
callable
$function The function to add
Returns
void
connect() ¶ public static
connect(Cake\Routing\Route\Route|string $route, array|string $defaults = [], array<string, mixed> $options = []): void
Connects a new Route in the router.
Compatibility proxy to \Cake\Routing\RouteBuilder::connect() in the /
scope.
Parameters
-
Cake\Routing\Route\Route|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<string, mixed>
$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.
Returns
void
Throws
Cake\Core\Exception\CakeException
See Also
\Cake\Routing\Router::scope()
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): array<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 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>|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
array<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>
See Also
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, 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, 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
plugin() ¶ public static
plugin(string $name, callable|array $options = [], callable|null $callback = null): void
Add plugin routes.
This method creates a scoped route collection that includes relevant plugin information.
The plugin name will be inflected to the dasherized 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
-
callable|array
$options optional Either the options to use, or a callback
-
callable|null
$callback optional The callback to invoke that builds the plugin routes. Only required when $options is defined
Returns
void
prefix() ¶ public static
prefix(string $name, callable|array $params = [], callable|null $callback = null): void
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 dasherized 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.
-
callable|array
$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 The callback to invoke that builds the prefixed routes.
Returns
void
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 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.
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 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
See Also
routes() ¶ public static
routes(): array<Cake\Routing\Route\Route>
Get the route scopes and their connected routes.
Returns
array<Cake\Routing\Route\Route>
scope() ¶ public static
scope(string $path, callable|array $params = [], callable|null $callback = null): void
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 toRouter::defaultRouteClass()
extensions
The extensions to enable in this scope. Defaults to the globally enabled extensions set withRouter::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.
-
callable|array
$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 The callback to invoke with the scoped collection.
Returns
void
Throws
InvalidArgumentException
When an invalid callable is provided.
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 likewebcal
orftp
. 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 ofRouter::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
-
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
array<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
$_urlFilters ¶ protected static
The stack of URL filters to apply against routing URLs before passing the parameters to the route collection.
Type
array<callable>