ID
ID = '[0-9]+' : string
Regular expression for auto increment IDs
Provides features for building routes inside scopes.
Gives an easy to use way to build routes and append them into a route collection.
$_collection : \Cake\Routing\RouteCollection
The route collection routes should be added to.
__construct(\Cake\Routing\RouteCollection $collection, string $path, array $params = array(), array $options = array())
Constructor
routeClass - The default route class to use when adding routes.extensions - The extensions to connect when adding routes.namePrefix - The prefix to prepend to all route names.middleware - The names of the middleware routes should have applied.| \Cake\Routing\RouteCollection | $collection | The route collection to append routes into. |
| string | $path | The path prefix the scope is for. |
| array | $params | The scope's routing parameters. |
| array | $options | Options list. |
extensions(null|string|array $extensions = null) : array|null
Get or set the extensions in this route builder's scope.
Future routes connected in through this builder will have the connected extensions applied. However, setting extensions does not modify existing routes.
| null|string|array | $extensions | Either the extensions to use or null. |
setExtensions(string|array $extensions) : $this
Set the extensions in this route builder's scope.
Future routes connected in through this builder will have the connected extensions applied. However, setting extensions does not modify existing routes.
| string|array | $extensions | The extensions to set. |
resources(string $name, array|callable $options = array(), callable|null $callback = null) : void
Generate REST resource routes for the given controller(s).
A quick way to generate a default routes to a set of REST resources (controller(s)).
Connect resource routes for an app controller:
$routes->resources('Posts');Connect resource routes for the Comments controller in the Comments plugin:
Router::plugin('Comments', function ($routes) {
$routes->resources('Comments');
});Plugins will create lower_case underscored resource routes. e.g
/comments/comments
Connect resource routes for the Articles controller in the Admin prefix:
Router::prefix('admin', function ($routes) {
$routes->resources('Articles');
});Prefixes will create lower_case underscored resource routes. e.g
/admin/posts
You can create nested resources by passing a callback in:
$routes->resources('Articles', function ($routes) {
$routes->resources('Comments');
});The above would generate both resource routes for /articles, and /articles/:article_id/comments.
You can use the map option to connect additional resource methods:
$routes->resources('Articles', [
'map' => ['deleteAll' => ['action' => 'deleteAll', 'method' => 'DELETE']]
]);In addition to the default routes, this would also connect a route for /articles/delete_all.
By default the path segment will match the key name. You can use the 'path' key inside the resource
definition to customize the path name.
You can use the inflect option to change how path segments are generated:
$routes->resources('PaymentTypes', ['inflect' => 'dasherize']);Will generate routes like /payment-types instead of /payment_types
/posts| string | $name | A controller name to connect resource routes for. |
| array|callable | $options | Options to use when generating REST routes, or a callback. |
| callable|null | $callback | An optional callback to be executed in a nested scope. Nested scopes inherit the existing path and 'id' parameter. |
get(string $template, array $target, string $name = null) : \Cake\Routing\Route\Route
Create a route that only responds to GET requests.
| string | $template | The URL template to use. |
| array | $target | An array describing the target route parameters. These parameters should indicate the plugin, prefix, controller, and action that this route points to. |
| string | $name | The name of the route. |
post(string $template, array $target, string $name = null) : \Cake\Routing\Route\Route
Create a route that only responds to POST requests.
| string | $template | The URL template to use. |
| array | $target | An array describing the target route parameters. These parameters should indicate the plugin, prefix, controller, and action that this route points to. |
| string | $name | The name of the route. |
put(string $template, array $target, string $name = null) : \Cake\Routing\Route\Route
Create a route that only responds to PUT requests.
| string | $template | The URL template to use. |
| array | $target | An array describing the target route parameters. These parameters should indicate the plugin, prefix, controller, and action that this route points to. |
| string | $name | The name of the route. |
patch(string $template, array $target, string $name = null) : \Cake\Routing\Route\Route
Create a route that only responds to PATCH requests.
| string | $template | The URL template to use. |
| array | $target | An array describing the target route parameters. These parameters should indicate the plugin, prefix, controller, and action that this route points to. |
| string | $name | The name of the route. |
delete(string $template, array $target, string $name = null) : \Cake\Routing\Route\Route
Create a route that only responds to DELETE requests.
| string | $template | The URL template to use. |
| array | $target | An array describing the target route parameters. These parameters should indicate the plugin, prefix, controller, and action that this route points to. |
| string | $name | The name of the route. |
head(string $template, array $target, string $name = null) : \Cake\Routing\Route\Route
Create a route that only responds to HEAD requests.
| string | $template | The URL template to use. |
| array | $target | An array describing the target route parameters. These parameters should indicate the plugin, prefix, controller, and action that this route points to. |
| string | $name | The name of the route. |
options(string $template, array $target, string $name = null) : \Cake\Routing\Route\Route
Create a route that only responds to OPTIONS requests.
| string | $template | The URL template to use. |
| array | $target | An array describing the target route parameters. These parameters should indicate the plugin, prefix, controller, and action that this route points to. |
| string | $name | The name of the route. |
loadPlugin(string $name, string $file = 'routes.php') : void
Load routes from a plugin.
The routes file will have a local variable named $routes made available which contains
the current RouteBuilder instance.
| string | $name | The plugin name |
| string | $file | The routes file to load. Defaults to |
When the plugin has not been loaded.
When the plugin does not have a routes file.
connect(string $route, array|string $defaults = array(), array $options = array()) : \Cake\Routing\Route\Route
Connects a new Route.
Routes are a way of connecting request URLs to objects in your application. At their core routes are a set or regular expressions that are used to match requests to destinations.
Examples:
$routes->connect('/:controller/:action/*');The first parameter will be used as a controller name while the second is
used as the action name. The '/*' syntax makes this route greedy in that
it will match requests like /posts/index as well as requests
like /posts/edit/1/foo/bar.
$routes->connect('/home-page', ['controller' => 'Pages', 'action' => 'display', 'home']);The above shows the use of route parameter defaults. And providing routing parameters for a static route.
$routes->connect(
'/:lang/:controller/:action/:id',
[],
['id' => '[0-9]+', 'lang' => '[a-z]{3}']
);Shows connecting a route with custom route parameters as well as providing patterns for those parameters. Patterns for routing parameters do not need capturing groups, as one will be added for each route params.
$options offers several 'special' keys that have special meaning in the $options array.
routeClass is used to extend and change how individual routes parse requests
and handle reverse routing, via a custom routing class.
Ex. 'routeClass' => 'SlugRoute'pass is used to define which of the routed parameters should be shifted
into the pass array. Adding a parameter to pass will remove it from the
regular route array. Ex. 'pass' => ['slug'].persist is used to define which route parameters should be automatically
included when generating new URLs. You can override persistent parameters
by redefining them in a URL or remove them by setting the parameter to false.
Ex. 'persist' => ['lang']multibytePattern Set to true to enable multibyte pattern support in route
parameter patterns._name is used to define a specific name for routes. This can be used to optimize
reverse routing lookups. If undefined a name will be generated for each
connected route._ext is an array of filename extensions that will be parsed out of the url if present.
See \Cake\Routing\RouteCollection::setExtensions()._method Only match requests with specific HTTP verbs.Example of using the _method condition:
$routes->connect('/tasks', ['controller' => 'Tasks', 'action' => 'index', '_method' => 'GET']);The above route will only be matched for GET requests. POST requests will fail to match this route.
| 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()) : \Cake\Routing\Route\Route|\Cake\Routing\Route\RedirectRoute
Connects a new redirection Route in the router.
Redirection routes are different from normal routes as they perform an actual header redirection if a match is found. The redirection can occur within your application or redirect to an outside location.
Examples:
$routes->redirect('/home/*', ['controller' => 'posts', 'action' => 'view']);Redirects /home/* to /posts/view and passes the parameters to /posts/view. Using an array as the redirect destination allows you to use other routes to define where a URL string should be redirected to.
$routes->redirect('/posts/*', 'http://google.com', ['status' => 302]);Redirects /posts/* to http://google.com with a HTTP status of 302
status Sets the HTTP status (default 301)persist Passes the params to the redirected route, if it can. This is useful with greedy routes,
routes that end in * are greedy. As you can remap URLs and not lose any passed args.| 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. |
prefix(string $name, array|callable $params = array(), callable|null $callback = null) : void
Add prefixed routes.
This method creates a scoped route collection that includes relevant prefix information.
The $name 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.
If you need to have prefix with dots, eg: '/api/v1.0', use 'path' key for $params argument:
$route->prefix('api', function($route) {
$route->prefix('v10', ['path' => '/v1.0'], function($route) {
// Translates to `Controller\Api\V10\` 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. |
If a valid callback is not passed
plugin(string $name, array|callable $options = array(), callable|null $callback = null) : void
Add plugin routes.
This method creates a new 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. |
scope(string $path, array|callable $params, callable|null $callback = null) : void
Create a new routing scope.
Scopes created with this method will inherit the properties of the scope they are added to. This means that both the current path and parameters will be appended to the supplied parameters.
| string | $path | The path to create a scope for. |
| array|callable | $params | Either the parameters to add to routes, or a callback. |
| callable|null | $callback | The callback to invoke that builds the plugin routes. Only required when $params is defined. |
when there is no callable parameter.
fallbacks(string|null $routeClass = null) : void
Connect the `/:controller` and `/:controller/:action/*` fallback routes.
This is a shortcut method for connecting fallback routes in a given scope.
| string|null | $routeClass | the route class to use, uses the default routeClass if not specified |
registerMiddleware(string $name, callable|string $middleware) : $this
Register a middleware with the RouteCollection.
Once middleware has been registered, it can be applied to the current routing scope or any child scopes that share the same RouteCollection.
| string | $name | The name of the middleware. Used when applying middleware to a scope. |
| callable|string | $middleware | The middleware callable or class name to register. |
_methodRoute(string $method, string $template, array $target, string $name) : \Cake\Routing\Route\Route
Helper to create routes that only respond to a single HTTP method.
| string | $method | The HTTP method name to match. |
| string | $template | The URL template to use. |
| array | $target | An array describing the target route parameters. These parameters should indicate the plugin, prefix, controller, and action that this route points to. |
| string | $name | The name of the route. |
_makeRoute(string|\Cake\Routing\Route\Route $route, array $defaults, array $options) : \Cake\Routing\Route\Route
Create a route object, or return the provided object.
| string|\Cake\Routing\Route\Route | $route | The route template or route object. |
| array | $defaults | Default parameters. |
| array | $options | Additional options parameters. |
when route class or route object is invalid.
when the route to make conflicts with the current scope