Class RouteBuilder

Provides features for building routes inside scopes.

Gives an easy to use way to build routes and append them into a route collection.

Namespace: Cake\Routing

Constants

string

ID ¶
```
'[0-9]+'
```
Regular expression for auto increment IDs

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

Property Summary

$_collection protected

Cake\Routing\RouteCollection

The route collection routes should be added to.
$_extensions protected

string[]

The extensions that should be set into the routes connected.
$_namePrefix protected

string

Name prefix for connected routes.
$_params protected

array

The scope parameters if there are any.
$_path protected

string

The path prefix scope that this collection uses.
$_resourceMap protected static

array

Default HTTP request method => controller action map.
$_routeClass protected

string

Default route class to use if none is provided in connect() options.
$middleware protected

string[]

The list of middleware that routes in this builder get added during construction.

Method Summary

__construct() public

Constructor
_makeRoute() protected

Create a route object, or return the provided object.
_methodRoute() protected

Helper to create routes that only respond to a single HTTP method.
addExtensions() public

Add additional extensions to what is already in current scope
applyMiddleware() public

Apply a middleware to the current route scope.
connect() public

Connects a new Route.
delete() public

Create a route that only responds to DELETE requests.
fallbacks() public

Connect the /{controller} and /{controller}/{action}/* fallback routes.
get() public

Create a route that only responds to GET requests.
getExtensions() public

Get the extensions in this route builder's scope.
getMiddleware() public

Get the middleware that this builder will apply to routes.
getRouteClass() public

Get default route class.
head() public

Create a route that only responds to HEAD requests.
loadPlugin() public

Load routes from a plugin.
middlewareGroup() public

Apply a set of middleware to a group
nameExists() public

Checks if there is already a route with a given name.
namePrefix() public

Get/set the name prefix for this scope.
options() public

Create a route that only responds to OPTIONS requests.
params() public

Get the parameter names/values for this scope.
parseDefaults() protected

Parse the defaults if they're a string
patch() public

Create a route that only responds to PATCH requests.
path() public

Get the path this scope is for.
plugin() public

Add plugin routes.
post() public

Create a route that only responds to POST requests.
prefix() public

Add prefixed routes.
put() public

Create a route that only responds to PUT requests.
redirect() public

Connects a new redirection Route in the router.
registerMiddleware() public

Register a middleware with the RouteCollection.
resources() public

Generate REST resource routes for the given controller(s).
scope() public

Create a new routing scope.
setExtensions() public

Set the extensions in this route builder's scope.
setRouteClass() public

Set default route class.

Method Detail

__construct() ¶ public

__construct(Cake\Routing\RouteCollection $collection, string $path, array $params = [], array $options = [])

Constructor

Options

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.

Parameters

Cake\Routing\RouteCollection $collection: The route collection to append routes into.
string $path: The path prefix the scope is for.
array $params optional: The scope's routing parameters.
array $options optional: Options list.

_makeRoute() ¶ protected

_makeRoute(stringCake\Routing\Route\Route $route, array $defaults, array $options): Cake\Routing\Route\Route

Create a route object, or return the provided object.

Parameters

stringCake\Routing\Route\Route $route: The route template or route object.
array $defaults: Default parameters.
array $options: Additional options parameters.

Returns

Cake\Routing\Route\Route

Throws

InvalidArgumentException
when route class or route object is invalid.
BadMethodCallException
when the route to make conflicts with the current scope

_methodRoute() ¶ protected

_methodRoute(string $method, string $template, array|string $target, string|null $name): Cake\Routing\Route\Route

Helper to create routes that only respond to a single HTTP method.

Parameters

string $method: The HTTP method name to match.
string $template: The URL template to use.
array|string $target: An array describing the target route parameters. These parameters should indicate the plugin, prefix, controller, and action that this route points to.
string|null $name: The name of the route.

Returns

Cake\Routing\Route\Route

addExtensions() ¶ public

addExtensions(string|string[] $extensions): $this

Add additional extensions to what is already in current scope

Parameters

string|string[] $extensions: One or more extensions to add

Returns

$this

applyMiddleware() ¶ public

applyMiddleware(string ...$names): $this

Apply a middleware to the current route scope.

Requires middleware to be registered via registerMiddleware()

Parameters

string ...$names: The names of the middleware to apply to the current scope.

Returns

$this

Throws

RuntimeException

connect() ¶ public

connect(stringCake\Routing\Route\Route $route, array|string $defaults = [], array $options = []): 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 {@link \Cake\Routing\RouteCollection::setExtensions()}.
_method Only match requests with specific HTTP verbs.
_host - Define the host name pattern if you want this route to only match specific host names. You can use .* and to create wildcard subdomains/hosts e.g. *.example.com matches all subdomains on example.com.
'_port` - Define the port if you want this route to only match specific port number.

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.

Parameters

stringCake\Routing\Route\Route $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 $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

Cake\Routing\Route\Route

Throws

InvalidArgumentException

BadMethodCallException

delete() ¶ public

delete(string $template, array|string $target, string|null $name = null): Cake\Routing\Route\Route

Create a route that only responds to DELETE requests.

Parameters

string $template: The URL template to use.
array|string $target: An array describing the target route parameters. These parameters should indicate the plugin, prefix, controller, and action that this route points to.
string|null $name optional: The name of the route.

Returns

Cake\Routing\Route\Route

fallbacks() ¶ public

fallbacks(string|null $routeClass = null): $this

Connect the /{controller} and /{controller}/{action}/* fallback routes.

This is a shortcut method for connecting fallback routes in a given scope.

Parameters

string|null $routeClass optional: the route class to use, uses the default routeClass if not specified

Returns

$this

get() ¶ public

get(string $template, array|string $target, string|null $name = null): Cake\Routing\Route\Route

Create a route that only responds to GET requests.

Parameters

string $template: The URL template to use.
array|string $target: An array describing the target route parameters. These parameters should indicate the plugin, prefix, controller, and action that this route points to.
string|null $name optional: The name of the route.

Returns

Cake\Routing\Route\Route

getExtensions() ¶ public

getExtensions(): string[]

Get the extensions in this route builder's scope.

Returns

string[]

getMiddleware() ¶ public

getMiddleware(): array

Get the middleware that this builder will apply to routes.

Returns

array

getRouteClass() ¶ public

getRouteClass(): string

Get default route class.

Returns

string

head() ¶ public

head(string $template, array|string $target, string|null $name = null): Cake\Routing\Route\Route

Create a route that only responds to HEAD requests.

Parameters

string $template: The URL template to use.
array|string $target: An array describing the target route parameters. These parameters should indicate the plugin, prefix, controller, and action that this route points to.
string|null $name optional: The name of the route.

Returns

Cake\Routing\Route\Route

loadPlugin() ¶ public

loadPlugin(string $name): $this

Load routes from a plugin.

The routes file will have a local variable named $routes made available which contains the current RouteBuilder instance.

Parameters

string $name: The plugin name

Returns

$this

Throws

Cake\Core\Exception\MissingPluginException
When the plugin has not been loaded.
InvalidArgumentException
When the plugin does not have a routes file.

middlewareGroup() ¶ public

middlewareGroup(string $name, string[] $middlewareNames): $this

Apply a set of middleware to a group

Parameters

string $name: Name of the middleware group
string[] $middlewareNames: Names of the middleware

Returns

$this

nameExists() ¶ public

nameExists(string $name): bool

Checks if there is already a route with a given name.

Parameters

string $name: Name.

Returns

bool

namePrefix() ¶ public

namePrefix(string|null $value = null): string

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.

Parameters

string|null $value optional: Either the value to set or null.

Returns

string

options() ¶ public

options(string $template, array|string $target, string|null $name = null): Cake\Routing\Route\Route

Create a route that only responds to OPTIONS requests.

Parameters

string $template: The URL template to use.
array|string $target: An array describing the target route parameters. These parameters should indicate the plugin, prefix, controller, and action that this route points to.
string|null $name optional: The name of the route.

Returns

Cake\Routing\Route\Route

params() ¶ public

params(): array

Get the parameter names/values for this scope.

Returns

array

parseDefaults() ¶ protected

parseDefaults(string|array $defaults): array

Parse the defaults if they're a string

Parameters

string|array $defaults: Defaults array from the connect() method.

Returns

array

patch() ¶ public

patch(string $template, array|string $target, string|null $name = null): Cake\Routing\Route\Route

Create a route that only responds to PATCH requests.

Parameters

string $template: The URL template to use.
array|string $target: An array describing the target route parameters. These parameters should indicate the plugin, prefix, controller, and action that this route points to.
string|null $name optional: The name of the route.

Returns

Cake\Routing\Route\Route

path() ¶ public

path(): string

Get the path this scope is for.

Returns

string

plugin() ¶ public

plugin(string $name, array|callable $options = [], callable|null $callback = null): $this

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.

Options

path The path prefix to use. Defaults to Inflector::dasherize($name).
_namePrefix Set a prefix used for named routes. The prefix is prepended to the name of any route created in a scope callback.

Parameters

string $name: The plugin name to build routes for
array|callable $options optional: Either the options to use, or a callback to build routes.
callable|null $callback optional: The callback to invoke that builds the plugin routes Only required when $options is defined.

Returns

$this

post() ¶ public

post(string $template, array|string $target, string|null $name = null): Cake\Routing\Route\Route

Create a route that only responds to POST requests.

Parameters

string $template: The URL template to use.
array|string $target: An array describing the target route parameters. These parameters should indicate the plugin, prefix, controller, and action that this route points to.
string|null $name optional: The name of the route.

Returns

Cake\Routing\Route\Route

prefix() ¶ public

prefix(string $name, array|callable $params = [], callable|null $callback = null): $this

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
    });
});

Parameters

string $name: The prefix name to use.
array|callable $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

$this

Throws

InvalidArgumentException
If a valid callback is not passed

put() ¶ public

put(string $template, array|string $target, string|null $name = null): Cake\Routing\Route\Route

Create a route that only responds to PUT requests.

Parameters

string $template: The URL template to use.
array|string $target: An array describing the target route parameters. These parameters should indicate the plugin, prefix, controller, and action that this route points to.
string|null $name optional: The name of the route.

Returns

Cake\Routing\Route\Route

redirect() ¶ public

redirect(string $route, array|string $url, array $options = []): Cake\Routing\Route\RouteCake\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

Options:

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.

Parameters

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 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. As well as supplying patterns for routing parameters.

Returns

Cake\Routing\Route\RouteCake\Routing\Route\RedirectRoute

registerMiddleware() ¶ public

registerMiddleware(string $name, stringClosurePsr\Http\Server\MiddlewareInterface $middleware): $this

Once middleware has been registered, it can be applied to the current routing scope or any child scopes that share the same RouteCollection.

Parameters

string $name: The name of the middleware. Used when applying middleware to a scope.
stringClosurePsr\Http\Server\MiddlewareInterface $middleware: The middleware to register.

Returns

$this

resources() ¶ public

resources(string $name, array|callable $options = [], callable|null $callback = null): $this

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)).

Usage

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 lowercase dasherized 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 lowercase dasherized 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' => 'underscore']);

Will generate routes like /payment-types instead of /payment_types

Options:

'id' - The regular expression fragment to use when matching IDs. By default, matches integer values and UUIDs.
'inflect' - Choose the inflection method used on the resource name. Defaults to 'dasherize'.
'only' - Only connect the specific list of actions.
'actions' - Override the method names used for connecting actions.
'map' - Additional resource routes that should be connected. If you define 'only' and 'map', make sure that your mapped methods are also in the 'only' list.
'prefix' - Define a routing prefix for the resource controller. If the current scope defines a prefix, this prefix will be appended to it.
'connectOptions' - Custom options for connecting the routes.
'path' - Change the path so it doesn't match the resource name. E.g ArticlesController is available at /posts

Parameters

string $name: A controller name to connect resource routes for.
array|callable $options optional: Options to use when generating REST routes, or a callback.
callable|null $callback optional: An optional callback to be executed in a nested scope. Nested scopes inherit the existing path and 'id' parameter.

Returns

$this

scope() ¶ public

scope(string $path, array|callable $params, callable|null $callback = null): $this

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.

Special Keys in $params

_namePrefix Set a prefix used for named routes. The prefix is prepended to the name of any route created in a scope callback.

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 optional: The callback to invoke that builds the plugin routes. Only required when $params is defined.

Returns

$this

Throws

InvalidArgumentException
when there is no callable parameter.

setExtensions() ¶ public

setExtensions(string|string[] $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.

Parameters

string|string[] $extensions: The extensions to set.

Returns

$this

setRouteClass() ¶ public

setRouteClass(string $routeClass): $this

Set default route class.

Parameters

string $routeClass: Class name.

Returns

$this

Property Detail

`$_collection` ¶ protected

The route collection routes should be added to.

Type

Cake\Routing\RouteCollection

`$_extensions` ¶ protected

The extensions that should be set into the routes connected.

Type

string[]

`$_namePrefix` ¶ protected

Name prefix for connected routes.

Type

string

`$_params` ¶ protected

The scope parameters if there are any.

Type

array

`$_path` ¶ protected

The path prefix scope that this collection uses.

Type

string

`$_resourceMap` ¶ protected static

Default HTTP request method => controller action map.

Type

array

`$_routeClass` ¶ protected

Default route class to use if none is provided in connect() options.

Type

string

`$middleware` ¶ protected

The list of middleware that routes in this builder get added during construction.

Type

string[]

Namespaces

Class RouteBuilder

Constants

Property Summary

Method Summary

__construct() public

_makeRoute() protected

_methodRoute() protected

addExtensions() public

applyMiddleware() public

connect() public

delete() public

fallbacks() public

get() public

getExtensions() public

getMiddleware() public

getRouteClass() public

head() public

loadPlugin() public

middlewareGroup() public

nameExists() public

namePrefix() public

options() public

params() public

parseDefaults() protected

patch() public

path() public

plugin() public

post() public

prefix() public

put() public

redirect() public

registerMiddleware() public

resources() public

scope() public

setExtensions() public

setRouteClass() public

Method Detail

__construct() ¶ public

Options

Parameters

_makeRoute() ¶ protected

Parameters

Returns

Throws

_methodRoute() ¶ protected

Parameters

Returns

addExtensions() ¶ public

Parameters

Returns

applyMiddleware() ¶ public

Parameters

Returns

Throws

See Also

connect() ¶ public

Parameters

Returns

Throws

delete() ¶ public

Parameters

Returns

fallbacks() ¶ public

Parameters

Returns

get() ¶ public

Parameters

Returns

getExtensions() ¶ public

Returns

getMiddleware() ¶ public

Returns

getRouteClass() ¶ public

Returns

head() ¶ public

Parameters

Returns

loadPlugin() ¶ public

Parameters

`$_collection` ¶ protected

`$_extensions` ¶ protected