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 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().
_applyUrlFilters( array $url )
Applies all the connected URL filters to the URL.
$url
array
Cake\Routing\Router::url()
Cake\Routing\Router::addUrlFilter()
_setContext( Cake\Network\Request $request )
Store the request context for a given request.
Cake\Network\Request
$request
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.
URL filters allow you to easily implement features like persistent parameters.
Router::addUrlFilter(function ($params, $request) { if (isset($request->params['lang']) && !isset($params['lang'])) { $params['lang'] = $request->params['lang']; } return $params; });
$function
connect( string $route , array $defaults [] , array $options [] )
Connects a new Route in the router.
Compatibility proxy to \Cake\Routing\RouteBuilder::connect() in the /
scope.
$route
$defaults
optional [] $options
optional [] Cake\Core\Exception\Exception
Cake\Routing\RouteBuilder::connect()
Cake\Routing\Router::scope()
defaultRouteClass( string|null $routeClass null )
Get or set default route class.
$routeClass
optional null string|null
extensions( array|string $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->params['_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\Network\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.
$extensions
optional null $merge
optional true true
.array
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 not parameters are passed, the currently configured value is returned.
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.
$base
optional null http://example.com
string
getNamedExpressions( )
Gets the named route patterns for use in config/routes.php
array
Cake\Routing\Router::$_namedExpressions
getRequest( boolean $current false )
Get the current request object, or the first one.
$current
optional false Cake\Network\Request|null.
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)).
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
$controller
$options
optional [] Cake\Routing\RouteBuilder::resources()
normalize( array|string $url '/' )
Normalizes an 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.
$url
optional '/' string
parse( string $url )
Parses given URL string. Returns 'routing' parameters for that URL.
$url
array
Cake\Routing\Exception\MissingRouteException
parseNamedParams( Cake\Network\Request $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'].
separator
The string to use as a separator. Defaults to :
.Cake\Network\Request
$request
$options
optional [] Cake\Network\Request
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.
$name
$options
optional [] $callback
optional null popRequest( )
Pops a request off of the request stack. Used when doing requestAction
Cake\Network\Request
Cake\Routing\Router::pushRequest()
prefix( string $name , array|callable $params [] , callable $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.
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.
$name
$params
optional [] $callback
optional null pushRequest( Cake\Network\Request $request )
Push a request onto the request stack. Pushing a request sets the request context used when generating URLs.
Cake\Network\Request
$request
redirect( string $route , array $url , array $options [] )
Connects a new redirection Route in the router.
Compatibility proxy to \Cake\Routing\RouteBuilder::redirect() in the /
scope.
$route
$url
$options
optional [] Cake\Routing\RouteBuilder::redirect()
reload( )
Reloads default Router settings. Resets all class variables and removes all connected routes.
reverse( Cake\Network\Request|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.
Cake\Network\Request
|array $params
$full
optional false string
routes( )
Get the route scopes and their connected routes.
array
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.
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.
Routing scopes will inherit the globally set extensions configured with Router::extensions(). You can also set valid extensions using $routes->extensions()
in your closure.
$path
$params
optional [] $callback
optional null InvalidArgumentException
setRequestInfo( Cake\Network\Request|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\Network\Request object or an array of arrays. Support for accepting arrays may be removed in the future.
Cake\Network\Request
|array $request
url( string|array $url null , boolean $full false )
Finds URL for specified action.
Returns an URL pointing to a combination of controller and action.
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.$url
optional null $full
optional false string
Cake\Core\Exception\Exception
string | ACTION Regular expression for action names | 'index|show|add|create|edit|update|remove|del|delete|view|item' |
string | DAY Regular expression for days | '0[1-9]|[12][0-9]|3[01]' |
string | ID Regular expression for auto increment IDs | '[0-9]+' |
string | MONTH Regular expression for months | '0[1-9]|1[012]' |
string | UUID Regular expression for UUIDs | '[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 Regular expression for years | '[12][0-9]{3}' |
© 2005–2016 The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
http://api.cakephp.org/3.1/class-Cake.Routing.Router.html