CakePHP
  • Documentation
    • Book
    • API
    • Videos
    • Reporting Security Issues
    • Privacy Policy
    • Logos & Trademarks
  • Business Solutions
  • Swag
  • Road Trip
  • Team
  • Community
    • Community
    • Get Involved
    • Issues (Github)
    • Bakery
    • Featured Resources
    • Training
    • Meetups
    • My CakePHP
    • CakeFest
    • Newsletter
    • Linkedin
    • YouTube
    • Facebook
    • Twitter
    • Mastodon
    • Help & Support
    • Forum
    • Stack Overflow
    • IRC
    • Slack
    • Paid Support
CakePHP

C CakePHP 3.2 Red Velvet API

  • Project:
    • CakePHP
      • CakePHP
      • Authentication
      • Authorization
      • Chronos
      • Elastic Search
      • Queue
  • Version:
    • 3.2
      • 5.2
      • 5.1
      • 5.0
      • 4.6
      • 4.5
      • 4.4
      • 4.3
      • 4.2
      • 4.1
      • 4.0
      • 3.10
      • 3.9
      • 3.8
      • 3.7
      • 3.6
      • 3.5
      • 3.4
      • 3.3
      • 3.2
      • 3.1
      • 3.0
      • 2.10
      • 2.9
      • 2.8
      • 2.7
      • 2.6
      • 2.5
      • 2.4
      • 2.3
      • 2.2
      • 2.1
      • 2.0
      • 1.3
      • 1.2

Namespaces

  • Global
  • Cake
    • Auth
    • Cache
    • Collection
    • Console
    • Controller
    • Core
    • Database
    • Datasource
    • Error
    • Event
    • Filesystem
    • Form
    • I18n
    • Log
    • Mailer
    • Network
    • ORM
    • Routing
      • Exception
      • Filter
      • Route
    • Shell
    • TestSuite
    • Utility
    • Validation
    • View

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
    array

    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.

Method Summary

  • __construct() public

    Constructor

  • _makeRoute() protected

    Create a route object, or return the provided object.

  • addExtensions() public

    Add additional extensions to what is already in current scope

  • connect() public

    Connects a new Route.

  • extensions() public

    Get or set the extensions in this route builder's scope.

  • fallbacks() public

    Connect the /:controller and /:controller/:action/* fallback routes.

  • namePrefix() public

    Get/set the name prefix for this scope.

  • params() public

    Get the parameter names/values for this scope.

  • path() public

    Get the path this scope is for.

  • plugin() public

    Add plugin routes.

  • prefix() public

    Add prefixed routes.

  • redirect() public

    Connects a new redirection Route in the router.

  • resources() public

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

  • routeClass() public

    Get or set default route class.

  • scope() public

    Create a new routing scope.

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.
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(string|Cake\Routing\Route\Route $route, array $defaults, array $options): Cake\Routing\Route\Route

Create a route object, or return the provided object.

Parameters
string|Cake\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

addExtensions() ¶ public

addExtensions(string|array $extensions): void

Add additional extensions to what is already in current scope

Parameters
string|array $extensions

One or more extensions to add

Returns
void

connect() ¶ public

connect(string $route, array $defaults = [], array $options = []): void

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']
  • 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 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.

Parameters
string $route

A string describing the template of the route

array $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
void
Throws
InvalidArgumentException

BadMethodCallException

extensions() ¶ public

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.

Parameters
null|string|array $extensions optional

Either the extensions to use or null.

Returns
array|null

fallbacks() ¶ public

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.

Parameters
string|null $routeClass optional

the route class to use, uses the default routeClass if not specified

Returns
void

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

params() ¶ public

params(): string

Get the parameter names/values for this scope.

Returns
string

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

Parameters
string $name

The plugin name to build routes for

array|callable $options optional

Either the options to use, or a callback

callable|null $callback optional

The callback to invoke that builds the plugin routes Only required when $options is defined.

Returns
void

prefix() ¶ public

prefix(string $name, callable $callback): void

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.

Parameters
string $name

The prefix name to use.

callable $callback

The callback to invoke that builds the prefixed routes.

Returns
void

redirect() ¶ public

redirect(string $route, array $url, array $options = []): void

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

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 loose any passed args.
Parameters
string $route

A string describing the template of the route

array $url

An 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
void

resources() ¶ public

resources(string $name, array|callable $options = [], 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)).

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

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 'underscore'.
  • '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.
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
void

routeClass() ¶ public

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

Get or set default route class.

Parameters
string|null $routeClass optional

Class name.

Returns
string|null

scope() ¶ public

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.

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
void
Throws
InvalidArgumentException
when there is no callable parameter.

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
array

$_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
OpenHub
Pingping
Linode
  • Business Solutions
  • Showcase
  • Documentation
  • Book
  • API
  • Videos
  • Reporting Security Issues
  • Privacy Policy
  • Logos & Trademarks
  • Community
  • Get Involved
  • Issues (Github)
  • Bakery
  • Featured Resources
  • Training
  • Meetups
  • My CakePHP
  • CakeFest
  • Newsletter
  • Linkedin
  • YouTube
  • Facebook
  • Twitter
  • Mastodon
  • Help & Support
  • Forum
  • Stack Overflow
  • IRC
  • Slack
  • Paid Support

Generated using CakePHP API Docs