Provides features for building routes inside scopes.
Gives an easy to use way to build routes and append them into a route collection.
__construct( Cake\Routing\RouteCollection $collection , string $path , array $params [] , array $options [] )
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.$collection
$path
$params
optional [] $options
optional [] _makeRoute( string|Cake\Routing\Route\Route $route , array $defaults , array $options )
Create a route object, or return the provided object.
Cake\Routing\Route\Route
$route
$defaults
$options
Cake\Routing\Route\Route
InvalidArgumentException
BadMethodCallException
addExtensions( string|array $extensions )
Add additional extensions to what is already in current scope
$extensions
connect( string $route , array $defaults [] , array $options [] )
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.
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']
.routeClass
is used to extend and change how individual routes parse requests and handle reverse routing, via a custom routing class. Ex. 'routeClass' => 'SlugRoute'
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']
_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 ScopedRouteCollection::extensions()._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.
$route
$defaults
optional [] $options
optional [] InvalidArgumentException
BadMethodCallException
extensions( null|string|array $extensions 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.
$extensions
optional null array|null
fallbacks( string|null $routeClass null )
Connect the /:controller
and /:controller/:action/*
fallback routes.
This is a shortcut method for connecting fallback routes in a given scope.
$routeClass
optional null namePrefix( string|null $value null )
Get/set the name prefix for this scope.
Modifying the name prefix will only change the prefix used for routes connected after the prefix is changed.
$value
optional null string
plugin( string $name , array|callable $options [] , callable|null $callback null )
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.
$name
$options
optional [] $callback
optional null prefix( string $name , callable $callback )
Add 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
$callback
redirect( string $route , array $url , array $options [] )
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 an 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 loose any passed args.$route
$url
$options
optional [] resources( string $name , array|callable $options [] , callable|null $callback null )
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.
$name
$options
optional [] $callback
optional null routeClass( string|null $routeClass null )
Get or set default route class.
$routeClass
optional null string|null
scope( string $path , array|callable $params , callable|null $callback null )
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.
$path
$params
$callback
optional null InvalidArgumentException
string | ID Regular expression for auto increment IDs | '[0-9]+' |
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}' |
© 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.RouteBuilder.html