ACTION
ACTION = 'index|show|add|create|edit|update|remove|del|delete|view|item' : string
Regular expression for action names
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().
$_collection : \Cake\Routing\RouteCollection
The route collection routes would be added to.
connect(string $route, array|string $defaults = array(), array $options = array()) : void
Connects a new Route in the router.
Compatibility proxy to \Cake\Routing\RouteBuilder::connect() in the / scope.
| string | $route | A string describing the template of the route |
| array|string | $defaults | 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 | 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. |
redirect(string $route, array|string $url, array $options = array()) : void
Connects a new redirection Route in the router.
Compatibility proxy to \Cake\Routing\RouteBuilder::redirect() in the / scope.
| 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 | 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. |
mapResources(string|array $controller, array $options = array()) : void
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
/posts| string|array | $controller | A controller name or array of controller names (i.e. "Posts" or "ListItems") |
| array | $options | Options to use when generating REST routes |
parse(string $url, string $method = '') : array
Parses given URL string. Returns 'routing' parameters for that URL.
| string | $url | URL to be parsed. |
| string | $method | The HTTP method being used. |
When a route cannot be handled
Parsed elements from URL.
parseRequest(\Psr\Http\Message\ServerRequestInterface $request) : array
Get the routing parameters for the request is possible.
| \Psr\Http\Message\ServerRequestInterface | $request | The request to parse request data from. |
When a route cannot be handled
Parsed elements from URL.
setRequestInfo(\Cake\Http\ServerRequest|array $request) : void
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.
| \Cake\Http\ServerRequest|array | $request | Parameters and path information or a Cake\Http\ServerRequest object. |
pushRequest(\Cake\Http\ServerRequest $request) : void
Push a request onto the request stack. Pushing a request sets the request context used when generating URLs.
| \Cake\Http\ServerRequest | $request | Request instance. |
setRequestContext(\Psr\Http\Message\ServerRequestInterface $request) : void
Store the request context for a given request.
| \Psr\Http\Message\ServerRequestInterface | $request | The request instance. |
When parameter is an incorrect type.
popRequest() : \Cake\Http\ServerRequest
Pops a request off of the request stack. Used when doing requestAction
The request removed from the stack.
getRequest(boolean $current = false) : \Cake\Http\ServerRequest|null
Get the current request object, or the first one.
| boolean | $current | True to get the current request, or false to get the first one. |
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.
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;
});| callable | $function | The function to add |
url(string|array|null $url = null, boolean $full = false) : string
Finds URL for specified action.
Returns a 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.| string|array|null | $url | 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 | If true, the full base URL will be prepended to the result. Default is false. |
When the route name is not found
Full translated URL with base path.
routeExists(string|array|null $url = null, boolean $full = false) : boolean
Finds URL for specified action.
Returns a bool if the url exists
| string|array|null | $url | 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 | If true, the full base URL will be prepended to the result. Default is false. |
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.
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.
| string|null | $base | the prefix for URLs generated containing the domain.
For example: |
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 '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\Http\ServerRequest|array | $params | The params array or Cake\Http\ServerRequest object that needs to be reversed. |
The URL array ready to be used for redirect or HTML link.
reverse(\Cake\Http\ServerRequest|array $params, boolean $full = false) : string
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\Http\ServerRequest|array | $params | The params array or Cake\Http\ServerRequest object that needs to be reversed. |
| boolean | $full | Set to true to include the full URL including the protocol when reversing the URL. |
The string that is the reversed result of the array
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.
| array|string | $url | URL to normalize Either an array or a string URL. |
Normalized URL
extensions(array|string|null $extensions = null, boolean $merge = true) : array
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.
| array|string|null | $extensions | List of extensions to be added. |
| boolean | $merge | Whether to merge with or override existing extensions.
Defaults to |
Array of extensions Router is configured to parse.
parseNamedParams(\Cake\Http\ServerRequest $request, array $options = array()) : \Cake\Http\ServerRequest
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\Http\ServerRequest | $request | The request object to modify. |
| array | $options | The array of options. |
The modified request
createRouteBuilder(string $path, array $options = array()) : \Cake\Routing\RouteBuilder
Create a RouteBuilder for the provided path.
| string | $path | The path to set the builder to. |
| array | $options | The options for the builder |
scope(string $path, array|callable $params = array(), 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.
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()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.
| string | $path | The path prefix for the scope. This path will be prepended to all routes connected in the scoped collection. |
| array|callable | $params | 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 | The callback to invoke with the scoped collection. |
When an invalid callable is provided.
prefix(string $name, array|callable $params = array(), 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 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.
| string | $name | The prefix name to use. |
| array|callable | $params | 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 | The callback to invoke that builds the prefixed routes. |
plugin(string $name, array|callable $options = array(), 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 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.
| string | $name | The plugin name to build routes for |
| array|callable | $options | Either the options to use, or a callback |
| callable|null | $callback | The callback to invoke that builds the plugin routes. Only required when $options is defined |
routes() : array<mixed,\Cake\Routing\Route\Route>
Get the route scopes and their connected routes.
getRouteCollection() : \Cake\Routing\RouteCollection
Get the RouteCollection inside the Router
setRouteCollection(\Cake\Routing\RouteCollection $routeCollection) : void
Set the RouteCollection inside the Router
| \Cake\Routing\RouteCollection | $routeCollection | route collection |