Class Router

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

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

Namespace: Cake\Routing

Constants summary

  • string
    ACTION
    'index|show|add|create|edit|update|remove|del|delete|view|item'
  • string
    DAY
    '0[1-9]|[12][0-9]|3[01]'
  • string
    ID
    '[0-9]+'
  • string
    MONTH
    '0[1-9]|1[012]'
  • 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}'
  • string
    YEAR
    '[12][0-9]{3}'

Properties summary

  • $_collection protected static
    \Cake\Routing\RouteCollection

    The route collection routes would be added to.

  • $_defaultExtensions protected static
    string[]

    Default extensions defined with Router::extensions()

  • $_defaultRouteClass protected static
    string

    Default route class.

  • $_fullBaseUrl protected static
    string|null

    Contains the base string that will be applied to all generated URLs For example https://example.com

  • $_initialState protected static
    array

    Initial state is populated the first time reload() is called which is at the bottom of this file. This is a cheat as get_class_vars() returns the value of static vars even if they have changed.

  • $_namedExpressions protected static
    array

    Named expressions

  • $_request protected static
    \Cake\Http\ServerRequest

    Maintains the request object reference.

  • $_requestContext protected static
    array

    A hash of request context data.

  • $_routePaths protected static
    array

    Cache of parsed route paths

  • $_urlFilters protected static
    callable[]

    The stack of URL filters to apply against routing URLs before passing the parameters to the route collection.

Method Summary

  • _applyUrlFilters() protected static

    Applies all the connected URL filters to the URL.

  • addUrlFilter() public static

    Add a URL filter to Router.

  • connect() public static

    Connects a new Route in the router.

  • createRouteBuilder() public static

    Create a RouteBuilder for the provided path.

  • defaultRouteClass() public static

    Get or set default route class.

  • extensions() public static

    Get or set valid extensions for all routes connected later.

  • fullBaseUrl() public static

    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.

  • getNamedExpressions() public static

    Gets the named route patterns for use in config/routes.php

  • getRequest() public static

    Get the current request object.

  • getRouteCollection() public static

    Get the RouteCollection inside the Router

  • normalize() public static

    Normalizes a URL for purposes of comparison.

  • parseRequest() public static

    Get the routing parameters for the request is possible.

  • parseRoutePath() public static

    Parse a string route path

  • pathUrl() public static

    Generate URL for route path.

  • plugin() public static

    Add plugin routes.

  • prefix() public static

    Create prefixed routes.

  • reload() public static

    Reloads default Router settings. Resets all class variables and removes all connected routes.

  • resetRoutes() public static

    Reset routes and related state.

  • reverse() public static

    Reverses a parsed parameter array into a string.

  • reverseToArray() public static

    Reverses a parsed parameter array into an array.

  • routeExists() public static

    Finds URL for specified action.

  • routes() public static

    Get the route scopes and their connected routes.

  • scope() public static

    Create a routing scope.

  • setRequest() public static

    Set current request instance.

  • setRouteCollection() public static

    Set the RouteCollection inside the Router

  • unwrapShortString() protected static

    Inject route defaults from _path key

  • url() public static

    Finds URL for specified action.

Method Detail

_applyUrlFilters() protected static 

_applyUrlFilters(array $url)

Applies all the connected URL filters to the URL.

Parameters

array $url

The URL array being modified.

Returns

array

The modified URL.

See Also

\Cake\Routing\Router::url()

\Cake\Routing\Router::addUrlFilter()

addUrlFilter() public static 

addUrlFilter(callable $function)

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.

Usage

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

Parameters

callable $function

The function to add

connect() public static 

connect(mixed $route, mixed $defaults, mixed $options)

Connects a new Route in the router.

Compatibility proxy to \Cake\Routing\RouteBuilder::connect() in the / scope.

Parameters

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

Throws

Cake\Core\Exception\Exception

See Also

\Cake\Routing\RouteBuilder::connect()

\Cake\Routing\Router::scope()

createRouteBuilder() public static 

createRouteBuilder(string $path, array $options)

Create a RouteBuilder for the provided path.

Parameters

string $path

The path to set the builder to.

array $options optional

The options for the builder

Returns

\Cake\Routing\RouteBuilder

defaultRouteClass() public static 

defaultRouteClass(?string $routeClass)

Get or set default route class.

Parameters

string|null $routeClass optional

Class name.

Returns

string|null

extensions() public static 

extensions(mixed $extensions, mixed $merge)

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.

Parameters

string[]|string|null $extensions optional

List of extensions to be added.

bool $merge optional

Whether to merge with or override existing extensions. Defaults to true.

Returns

string[]

Array of extensions Router is configured to parse.

fullBaseUrl() public static 

fullBaseUrl(?string $base)

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.

Note:

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.

Parameters

string|null $base optional

the prefix for URLs generated containing the domain. For example: http://example.com

Returns

string

getNamedExpressions() public static 

getNamedExpressions()

Gets the named route patterns for use in config/routes.php

Returns

array

Named route elements

See Also

\Cake\Routing\Router::$_namedExpressions

getRequest() public static 

getRequest()

Get the current request object.

Returns

\Cake\Http\ServerRequest|null

getRouteCollection() public static 

getRouteCollection()

Get the RouteCollection inside the Router

Returns

\Cake\Routing\RouteCollection

normalize() public static 

normalize(mixed $url)

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.

Parameters

array|string $url optional

URL to normalize Either an array or a string URL.

Returns

string

Normalized URL

parseRequest() public static 

parseRequest(\Cake\Http\ServerRequest $request)

Get the routing parameters for the request is possible.

Parameters

\Cake\Http\ServerRequest $request

The request to parse request data from.

Returns

array

Parsed elements from URL.

Throws

Cake\Routing\Exception\MissingRouteException
When a route cannot be handled

parseRoutePath() public static 

parseRoutePath(string $url)

Parse a string route path

String examples:

  • Bookmarks::view
  • Admin/Bookmarks::view
  • Cms.Articles::edit
  • Vendor/Cms.Management/Admin/Articles::view

Parameters

string $url

Route path in [Plugin.][Prefix/]Controller::action format

Returns

string[]

pathUrl() public static 

pathUrl(string $path, array $params, bool $full)

Generate URL for route path.

Route path examples:

  • Bookmarks::view
  • Admin/Bookmarks::view
  • Cms.Articles::edit
  • Vendor/Cms.Management/Admin/Articles::view

Parameters

string $path

Route path specifying controller and action, optionally with plugin and prefix.

array $params optional

An array specifying any additional parameters. Can be also any special parameters supported by Router::url().

bool $full optional

If true, the full base URL will be prepended to the result. Default is false.

Returns

string

Full translated URL with base path.

plugin() public static 

plugin(string $name, mixed $options, mixed $callback)

Add plugin routes.

This method creates a scoped route collection that includes relevant plugin information.

The plugin name will be inflected to the dasherized 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

prefix() public static 

prefix(string $name, mixed $params, mixed $callback)

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

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.

reload() public static 

reload()

Reloads default Router settings. Resets all class variables and removes all connected routes.

resetRoutes() public static 

resetRoutes()

Reset routes and related state.

Similar to reload() except that this doesn't reset all global state, as that leads to incorrect behavior in some plugin test case scenarios.

This method will reset:

  • routes
  • URL Filters
  • the initialized property

Extensions and default route classes will not be modified

reverse() public static 

reverse(mixed $params, mixed $full)

Reverses a parsed parameter array into a string.

Works similarly to Router::url(), but since parsed URL's contain additional keys like 'pass', '_matchedRoute' etc. those keys need to be specially handled in order to reverse a params array into a string URL.

Parameters

\Cake\Http\ServerRequest|array $params

The params array or Cake\Http\ServerRequest object that needs to be reversed.

bool $full optional

Set to true to include the full URL including the protocol when reversing the URL.

Returns

string

The string that is the reversed result of the array

reverseToArray() public static 

reverseToArray(mixed $params)

Reverses a parsed parameter array into an array.

Works similarly to Router::url(), but since parsed URL's contain additional keys like 'pass', '_matchedRoute' etc. those keys need to be specially handled in order to reverse a params array into a string URL.

Parameters

\Cake\Http\ServerRequest|array $params

The params array or Cake\Http\ServerRequest object that needs to be reversed.

Returns

array

The URL array ready to be used for redirect or HTML link.

routeExists() public static 

routeExists(mixed $url, bool $full)

Finds URL for specified action.

Returns a bool if the url exists

Usage

Parameters

string|array|null $url optional

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.

bool $full optional

If true, the full base URL will be prepended to the result. Default is false.

Returns

bool

See Also

\Cake\Routing\Router::url()

routes() public static 

routes()

Get the route scopes and their connected routes.

Returns

\Cake\Routing\Route\Route[]

scope() public static 

scope(string $path, mixed $params, mixed $callback)

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.

Options

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

Example

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.

Parameters

string $path

The path prefix for the scope. This path will be prepended to all routes connected in the scoped collection.

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 with the scoped collection.

Throws

InvalidArgumentException
When an invalid callable is provided.

setRequest() public static 

setRequest(\Cake\Http\ServerRequest $request)

Set current request instance.

Parameters

\Cake\Http\ServerRequest $request

request object.

setRouteCollection() public static 

setRouteCollection(\Cake\Routing\RouteCollection $routeCollection)

Set the RouteCollection inside the Router

Parameters

\Cake\Routing\RouteCollection $routeCollection

route collection

unwrapShortString() protected static 

unwrapShortString(array $url)

Inject route defaults from _path key

Parameters

array $url

Route array with _path key

Returns

array

url() public static 

url(mixed $url, bool $full)

Finds URL for specified action.

Returns a URL pointing to a combination of controller and action.

Usage

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

Parameters

string|array|\Psr\Http\Message\UriInterface|null $url optional

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 or it can be an UriInterface instance.

bool $full optional

If true, the full base URL will be prepended to the result. Default is false.

Returns

string

Full translated URL with base path.

Throws

Cake\Core\Exception\Exception
When the route name is not found

Property Detail

$_collection protected static

The route collection routes would be added to.

Type

\Cake\Routing\RouteCollection

$_defaultExtensions protected static

Default extensions defined with Router::extensions()

Type

string[]

$_defaultRouteClass protected static

Default route class.

Type

string

$_fullBaseUrl protected static

Contains the base string that will be applied to all generated URLs For example https://example.com

Type

string|null

$_initialState protected static

Initial state is populated the first time reload() is called which is at the bottom of this file. This is a cheat as get_class_vars() returns the value of static vars even if they have changed.

Type

array

$_namedExpressions protected static

Named expressions

Type

array

$_request protected static

Maintains the request object reference.

Type

\Cake\Http\ServerRequest

$_requestContext protected static

A hash of request context data.

Type

array

$_routePaths protected static

Cache of parsed route paths

Type

array

$_urlFilters protected static

The stack of URL filters to apply against routing URLs before passing the parameters to the route collection.

Type

callable[]

© 2005–present 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.
https://api.cakephp.org/4.0/class-Cake.Routing.Router.html