Class Route
A single Route used by the Router to connect requests to parameter maps.
Not normally created as a standalone. Use Router::connect() to create Routes for your application.
Constants
Property Summary
-
$_compiledRoute protected
string|nullThe compiled route regular expression
-
$_extensions protected
array<string>List of connected extensions for this route.
-
$_greedy protected
boolIs this route a greedy route? Greedy routes have a
/*in their template -
$_name protected
string|nullThe name for a route. Fetch with Route::getName();
-
$braceKeys protected
boolTrack whether brace keys
{var}were used. -
$defaults public
arrayDefault parameters for a Route
-
$keys public
arrayAn array of named segments in a Route.
/{controller}/{action}/{id}has 3 key elements -
$middleware protected
arrayList of middleware that should be applied.
-
$options public
arrayAn array of additional parameters for the Route.
-
$template public
stringThe routes template string.
Method Summary
-
__construct() public
Constructor for a Route
-
__set_state() public static
Set state magic method to support var_export
-
_matchMethod() protected
Check whether the URL's HTTP method matches.
-
_parseArgs() protected
Parse passed parameters into a list of passed args.
-
_parseExtension() protected
Removes the extension from $url if it contains a registered extension. If no registered extension is found, no extension is returned and the URL is returned unmodified.
-
_persistParams() protected
Apply persistent parameters to a URL array. Persistent parameters are a special key used during route creation to force route parameters to persist when omitted from a URL array.
-
_writeRoute() protected
Builds a route regular expression.
-
_writeUrl() protected
Converts a matching route array into a URL string.
-
compile() public
Compiles the route's regular expression.
-
compiled() public
Check if a Route has been compiled into a regular expression.
-
getExtensions() public
Get the supported extensions for this route.
-
getMiddleware() public
Get the names of the middleware that should be applied to this route.
-
getName() public
Get the standardized plugin.controller:action name for a route.
-
hostMatches() public
Check to see if the host matches the route requirements
-
match() public
Check if a URL array matches this route instance.
-
normalizeAndValidateMethods() protected
Normalize method names to upper case and validate that they are valid HTTP methods.
-
parse() public
Checks to see if the given URL can be parsed by this route.
-
parseRequest() public
Checks to see if the given URL can be parsed by this route.
-
setExtensions() public
Set the supported extensions for this route.
-
setHost() public
Set host requirement
-
setMethods() public
Set the accepted HTTP methods for this route.
-
setMiddleware() public
Set the names of the middleware that should be applied to this route.
-
setPass() public
Set the names of parameters that will be converted into passed parameters
-
setPatterns() public
Set regexp patterns for routing parameters
-
setPersist() public
Set the names of parameters that will persisted automatically
-
staticPath() public
Get the static path portion for this route.
Method Detail
__construct() ¶ public
__construct(string $template, array $defaults = [], array<string, mixed> $options = [])Constructor for a Route
Options
_ext- Defines the extensions used for this route._middleware- Define the middleware names for this route.pass- Copies the listed parameters into params['pass']._method- Defines the HTTP method(s) the route applies to. It can be a string or array of valid HTTP method name._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.commatches all subdomains onexample.com.- '_port` - Define the port if you want this route to only match specific port number.
- '_urldecode' - Set to
falseto disable URL decoding before route parsing.
Parameters
-
string$template Template string with parameter placeholders
-
array$defaults optional Defaults for the route.
-
array<string, mixed>$options optional Array of additional options for the Route
Throws
InvalidArgumentExceptionWhen `$options['_method']` are not in `VALID_METHODS` list.
__set_state() ¶ public static
__set_state(array<string, mixed> $fields): staticSet state magic method to support var_export
This method helps for applications that want to implement router caching.
Parameters
-
array<string, mixed>$fields Key/Value of object attributes
Returns
static_matchMethod() ¶ protected
_matchMethod(array $url): boolCheck whether the URL's HTTP method matches.
Parameters
-
array$url The array for the URL being generated.
Returns
bool_parseArgs() ¶ protected
_parseArgs(string $args, array $context): array<string>Parse passed parameters into a list of passed args.
Return true if a given named $param's $val matches a given $rule depending on $context. Currently implemented rule types are controller, action and match that can be combined with each other.
Parameters
-
string$args A string with the passed params. eg. /1/foo
-
array$context The current route context, which should contain controller/action keys.
Returns
array<string>_parseExtension() ¶ protected
_parseExtension(string $url): arrayRemoves the extension from $url if it contains a registered extension. If no registered extension is found, no extension is returned and the URL is returned unmodified.
Parameters
-
string$url The url to parse.
Returns
array_persistParams() ¶ protected
_persistParams(array $url, array $params): arrayApply persistent parameters to a URL array. Persistent parameters are a special key used during route creation to force route parameters to persist when omitted from a URL array.
Parameters
-
array$url The array to apply persistent parameters to.
-
array$params An array of persistent values to replace persistent ones.
Returns
array_writeRoute() ¶ protected
_writeRoute(): voidBuilds a route regular expression.
Uses the template, defaults and options properties to compile a regular expression that can be used to parse request strings.
Returns
void_writeUrl() ¶ protected
_writeUrl(array $params, array $pass = [], array $query = []): stringConverts a matching route array into a URL string.
Composes the string URL using the template used to create the route.
Parameters
-
array$params The params to convert to a string url
-
array$pass optional The additional passed arguments
-
array$query optional An array of parameters
Returns
stringcompile() ¶ public
compile(): stringCompiles the route's regular expression.
Modifies defaults property so all necessary keys are set and populates $this->names with the named routing elements.
Returns
stringcompiled() ¶ public
compiled(): boolCheck if a Route has been compiled into a regular expression.
Returns
boolgetExtensions() ¶ public
getExtensions(): array<string>Get the supported extensions for this route.
Returns
array<string>getMiddleware() ¶ public
getMiddleware(): arrayGet the names of the middleware that should be applied to this route.
Returns
arraygetName() ¶ public
getName(): stringGet the standardized plugin.controller:action name for a route.
Returns
stringhostMatches() ¶ public
hostMatches(string $host): boolCheck to see if the host matches the route requirements
Parameters
-
string$host The request's host name
Returns
boolmatch() ¶ public
match(array $url, array $context = []): string|nullCheck if a URL array matches this route instance.
If the URL matches the route parameters and settings, then return a generated string URL. If the URL doesn't match the route parameters, false will be returned. This method handles the reverse routing or conversion of URL arrays into string URLs.
Parameters
-
array$url An array of parameters to check matching with.
-
array$context optional An array of the current request context. Contains information such as the current host, scheme, port, base directory and other url params.
Returns
string|nullnormalizeAndValidateMethods() ¶ protected
normalizeAndValidateMethods(array<string>|string $methods): array<string>|stringNormalize method names to upper case and validate that they are valid HTTP methods.
Parameters
-
array<string>|string$methods Methods.
Returns
array<string>|stringThrows
InvalidArgumentExceptionWhen methods are not in `VALID_METHODS` list.
parse() ¶ public
parse(string $url, string $method): array|nullChecks to see if the given URL can be parsed by this route.
If the route can be parsed an array of parameters will be returned; if not
null will be returned. String URLs are parsed if they match a routes regular expression.
Parameters
-
string$url The URL to attempt to parse.
-
string$method The HTTP method of the request being parsed.
Returns
array|nullThrows
Cake\Http\Exception\BadRequestExceptionWhen method is not an empty string and not in `VALID_METHODS` list.
parseRequest() ¶ public
parseRequest(Psr\Http\Message\ServerRequestInterface $request): array|nullChecks to see if the given URL can be parsed by this route.
If the route can be parsed an array of parameters will be returned; if not
null will be returned.
Parameters
-
Psr\Http\Message\ServerRequestInterface$request The URL to attempt to parse.
Returns
array|nullsetExtensions() ¶ public
setExtensions(array<string> $extensions): $thisSet the supported extensions for this route.
Parameters
-
array<string>$extensions The extensions to set.
Returns
$thissetHost() ¶ public
setHost(string $host): $thisSet host requirement
Parameters
-
string$host The host name this route is bound to
Returns
$thissetMethods() ¶ public
setMethods(array<string> $methods): $thisSet the accepted HTTP methods for this route.
Parameters
-
array<string>$methods The HTTP methods to accept.
Returns
$thisThrows
InvalidArgumentExceptionWhen methods are not in `VALID_METHODS` list.
setMiddleware() ¶ public
setMiddleware(array $middleware): $thisSet the names of the middleware that should be applied to this route.
Parameters
-
array$middleware The list of middleware names to apply to this route. Middleware names will not be checked until the route is matched.
Returns
$thissetPass() ¶ public
setPass(array<string> $names): $thisSet the names of parameters that will be converted into passed parameters
Parameters
-
array<string>$names The names of the parameters that should be passed.
Returns
$thissetPatterns() ¶ public
setPatterns(array<string> $patterns): $thisSet regexp patterns for routing parameters
If any of your patterns contain multibyte values, the multibytePattern
mode will be enabled.
Parameters
-
array<string>$patterns The patterns to apply to routing elements
Returns
$thissetPersist() ¶ public
setPersist(array $names): $thisSet the names of parameters that will persisted automatically
Persistent parameters allow you 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 persistent parameter to false.
// remove a persistent 'date' parameter
Router::url(['date' => false', ...]);Parameters
-
array$names The names of the parameters that should be passed.
Returns
$thisstaticPath() ¶ public
staticPath(): stringGet the static path portion for this route.
Returns
string