RouteCollection
in package
implements
RouteCollectionInterface
Class RouteCollection
Tags
Interfaces, Classes and Traits
- RouteCollectionInterface
- Interface RouteCollectionInterface
Table of Contents
- $autoRoute : bool
- Whether to match URI against Controllers when it doesn't match defined routes.
- $currentOptions : array<string|int, mixed>|null
- Stores copy of current options being applied during creation.
- $currentSubdomain : string|null
- The current subdomain.
- $defaultController : string
- The name of the default controller to use when no other controller is specified.
- $defaultHTTPMethods : array<string|int, mixed>
- The default list of HTTP methods (and CLI for command line usage) that is allowed if no other method is provided.
- $defaultMethod : string
- The name of the default method to use when no other method has been specified.
- $defaultNamespace : string
- The namespace to be added to any Controllers.
- $defaultPlaceholder : string
- The placeholder used when routing 'resources' when no other placeholder has been specified.
- $didDiscover : bool
- A little performance booster.
- $fileLocator : FileLocator
- Handle to the file locator to use.
- $group : string|null
- The name of the current group, if any.
- $HTTPVerb : string
- The current method that the script is being called by.
- $moduleConfig : Modules
- Handle to the modules config.
- $override404 : string|Closure
- A callable that will be shown when the route cannot be matched.
- $placeholders : array<string|int, mixed>
- Defined placeholders that can be used within the
- $prioritize : bool
- Flag for sorting routes by priority.
- $prioritizeDetected : bool
- Route priority detection flag.
- $routes : array<string|int, mixed>
- An array of all routes and their mappings.
- $routesOptions : array<string|int, mixed>
- Array of routes options
- $translateURIDashes : bool
- Whether to convert dashes to underscores in URI.
- __construct() : mixed
- Constructor
- add() : RouteCollectionInterface
- Adds a single route to the collection.
- addPlaceholder() : RouteCollectionInterface
- Registers a new constraint with the system. Constraints are used by the routes as placeholders for regular expressions to make defining the routes more human-friendly.
- addRedirect() : RouteCollection
- Adds a temporary redirect from one route to another. Used for redirecting traffic from old, non-existing routes to the new moved routes.
- cli() : RouteCollectionInterface
- Specifies a route that is only available to command-line requests.
- delete() : RouteCollectionInterface
- Specifies a route that is only available to DELETE requests.
- environment() : RouteCollectionInterface
- Limits the routes to a specified ENVIRONMENT or they won't run.
- get() : RouteCollectionInterface
- Specifies a route that is only available to GET requests.
- get404Override() : string|Closure|null
- Returns the 404 Override setting, which can be null, a closure or the controller/string.
- getDefaultController() : string
- Returns the name of the default controller. With Namespace.
- getDefaultMethod() : string
- Returns the name of the default method to use within the controller.
- getDefaultNamespace() : string
- Returns the default namespace as set in the Routes config file.
- getFilterForRoute() : string
- Returns the filter that should be applied for a single route, along with any parameters it might have. Parameters are found by splitting the parameter name on a colon to separate the filter name from the parameter list, and the splitting the result on commas. So:
- getHTTPVerb() : string
- Returns the current HTTP Verb being used.
- getRedirectCode() : int
- Grabs the HTTP status code from a redirecting Route.
- getRoutes() : array<string|int, mixed>
- Returns the raw array of available routes.
- getRoutesOptions() : array<string|int, mixed>
- Returns one or all routes options
- group() : void
- Group a series of routes under a single URL segment. This is handy for grouping items into an admin area, like:
- head() : RouteCollectionInterface
- Specifies a route that is only available to HEAD requests.
- isFiltered() : bool
- Checks a route (using the "from") to see if it's filtered or not.
- isRedirect() : bool
- Determines if the route is a redirecting route.
- map() : RouteCollectionInterface
- A shortcut method to add a number of routes at a single time.
- match() : RouteCollectionInterface
- Specifies a single route to match for multiple HTTP Verbs.
- options() : RouteCollectionInterface
- Specifies a route that is only available to OPTIONS requests.
- patch() : RouteCollectionInterface
- Specifies a route that is only available to PATCH requests.
- post() : RouteCollectionInterface
- Specifies a route that is only available to POST requests.
- presenter() : RouteCollectionInterface
- Creates a collections of HTTP-verb based routes for a presenter controller.
- put() : RouteCollectionInterface
- Specifies a route that is only available to PUT requests.
- resetRoutes() : mixed
- Reset the routes, so that a test case can provide the explicit ones needed for it.
- resource() : RouteCollectionInterface
- Creates a collections of HTTP-verb based routes for a controller.
- reverseRoute() : string|false
- Attempts to look up a route based on its destination.
- set404Override() : RouteCollectionInterface
- Sets the class/method that should be called if routing doesn't find a match. It can be either a closure or the controller/method name exactly like a route is defined: Users::index
- setAutoRoute() : RouteCollectionInterface
- If TRUE, the system will attempt to match the URI against Controllers by matching each segment against folders/files in APPPATH/Controllers, when a match wasn't found against defined routes.
- setDefaultConstraint() : RouteCollectionInterface
- Sets the default constraint to be used in the system. Typically for use with the 'resource' method.
- setDefaultController() : RouteCollectionInterface
- Sets the default controller to use when no other controller has been specified.
- setDefaultMethod() : RouteCollectionInterface
- Sets the default method to call on the controller when no other method has been set in the route.
- setDefaultNamespace() : RouteCollectionInterface
- Sets the default namespace to use for Controllers when no other namespace has been specified.
- setHTTPVerb() : $this
- Sets the current HTTP verb.
- setPrioritize() : $this
- Enable or Disable sorting routes by priority
- setTranslateURIDashes() : RouteCollectionInterface
- Tells the system whether to convert dashes in URI strings into underscores. In some search engines, including Google, dashes create more meaning and make it easier for the search engine to find words and meaning in the URI for better SEO. But it doesn't work well with PHP method names.
- shouldAutoRoute() : bool
- Returns the flag that tells whether to autoRoute URI against Controllers.
- shouldTranslateURIDashes() : bool
- Returns the current value of the translateURIDashes setting.
- create() : mixed
- Does the heavy lifting of creating an actual route. You must specify the request method(s) that this route will work for. They can be separated by a pipe character "|" if there is more than one.
- discoverRoutes() : mixed
- Will attempt to discover any additional routes, either through the local PSR4 namespaces, or through selected Composer packages.
- fillRouteParams() : string
- Given a
- loadRoutesOptions() : array<string|int, mixed>
- Load routes options based on verb
- localizeRoute() : string
- Replaces the {locale} tag with the current application locale
- checkSubdomains() : bool
- Compares the subdomain(s) passed in against the current subdomain on this page request.
- determineCurrentSubdomain() : mixed
- Examines the HTTP_HOST to get a best match for the subdomain. It won't be perfect, but should work for our needs.
Properties
$autoRoute
Whether to match URI against Controllers when it doesn't match defined routes.
protected
bool
$autoRoute
= true
Not used here. Pass-thru value for Router class.
$currentOptions
Stores copy of current options being applied during creation.
protected
array<string|int, mixed>|null
$currentOptions
$currentSubdomain
The current subdomain.
protected
string|null
$currentSubdomain
$defaultController
The name of the default controller to use when no other controller is specified.
protected
string
$defaultController
= 'Home'
Not used here. Pass-thru value for Router class.
$defaultHTTPMethods
The default list of HTTP methods (and CLI for command line usage) that is allowed if no other method is provided.
protected
array<string|int, mixed>
$defaultHTTPMethods
= ['options', 'get', 'head', 'post', 'put', 'delete', 'trace', 'connect', 'cli']
$defaultMethod
The name of the default method to use when no other method has been specified.
protected
string
$defaultMethod
= 'index'
Not used here. Pass-thru value for Router class.
$defaultNamespace
The namespace to be added to any Controllers.
protected
string
$defaultNamespace
= '\'
Defaults to the global namespaces ()
$defaultPlaceholder
The placeholder used when routing 'resources' when no other placeholder has been specified.
protected
string
$defaultPlaceholder
= 'any'
$didDiscover
A little performance booster.
protected
bool
$didDiscover
= false
$fileLocator
Handle to the file locator to use.
protected
FileLocator
$fileLocator
$group
The name of the current group, if any.
protected
string|null
$group
$HTTPVerb
The current method that the script is being called by.
protected
string
$HTTPVerb
= '*'
$moduleConfig
Handle to the modules config.
protected
Modules
$moduleConfig
$override404
A callable that will be shown when the route cannot be matched.
protected
string|Closure
$override404
$placeholders
Defined placeholders that can be used within the
protected
array<string|int, mixed>
$placeholders
= ['any' => '.*', 'segment' => '[^/]+', 'alphanum' => '[a-zA-Z0-9]+', 'num' => '[0-9]+', 'alpha' => '[a-zA-Z]+', 'hash' => '[^/]+']
$prioritize
Flag for sorting routes by priority.
protected
bool
$prioritize
= false
$prioritizeDetected
Route priority detection flag.
protected
bool
$prioritizeDetected
= false
$routes
An array of all routes and their mappings.
protected
array<string|int, mixed>
$routes
= ['*' => [], 'options' => [], 'get' => [], 'head' => [], 'post' => [], 'put' => [], 'delete' => [], 'trace' => [], 'connect' => [], 'cli' => []]
$routesOptions
Array of routes options
protected
array<string|int, mixed>
$routesOptions
= []
$translateURIDashes
Whether to convert dashes to underscores in URI.
protected
bool
$translateURIDashes
= false
Not used here. Pass-thru value for Router class.
Methods
__construct()
Constructor
public
__construct(FileLocator $locator, Modules $moduleConfig) : mixed
Parameters
- $locator : FileLocator
- $moduleConfig : Modules
Return values
mixed —add()
Adds a single route to the collection.
public
add(string $from, array<string|int, mixed>|string $to[, array<string|int, mixed>|null $options = null ]) : RouteCollectionInterface
Example: $routes->add('news', 'Posts::index');
Parameters
- $from : string
- $to : array<string|int, mixed>|string
- $options : array<string|int, mixed>|null = null
Return values
RouteCollectionInterface —addPlaceholder()
Registers a new constraint with the system. Constraints are used by the routes as placeholders for regular expressions to make defining the routes more human-friendly.
public
addPlaceholder(string|array<string|int, mixed> $placeholder[, string|null $pattern = null ]) : RouteCollectionInterface
You can pass an associative array as $placeholder, and have multiple placeholders added at once.
Parameters
- $placeholder : string|array<string|int, mixed>
- $pattern : string|null = null
Return values
RouteCollectionInterface —addRedirect()
Adds a temporary redirect from one route to another. Used for redirecting traffic from old, non-existing routes to the new moved routes.
public
addRedirect(string $from, string $to[, int $status = 302 ]) : RouteCollection
Parameters
- $from : string
-
The pattern to match against
- $to : string
-
Either a route name or a URI to redirect to
- $status : int = 302
-
The HTTP status code that should be returned with this redirect
Return values
RouteCollection —cli()
Specifies a route that is only available to command-line requests.
public
cli(string $from, string|array<string|int, mixed> $to[, array<string|int, mixed>|null $options = null ]) : RouteCollectionInterface
Parameters
- $from : string
- $to : string|array<string|int, mixed>
- $options : array<string|int, mixed>|null = null
Return values
RouteCollectionInterface —delete()
Specifies a route that is only available to DELETE requests.
public
delete(string $from, string|array<string|int, mixed> $to[, array<string|int, mixed>|null $options = null ]) : RouteCollectionInterface
Parameters
- $from : string
- $to : string|array<string|int, mixed>
- $options : array<string|int, mixed>|null = null
Return values
RouteCollectionInterface —environment()
Limits the routes to a specified ENVIRONMENT or they won't run.
public
environment(string $env, Closure $callback) : RouteCollectionInterface
Parameters
- $env : string
- $callback : Closure
Return values
RouteCollectionInterface —get()
Specifies a route that is only available to GET requests.
public
get(string $from, string|array<string|int, mixed> $to[, array<string|int, mixed>|null $options = null ]) : RouteCollectionInterface
Parameters
- $from : string
- $to : string|array<string|int, mixed>
- $options : array<string|int, mixed>|null = null
Return values
RouteCollectionInterface —get404Override()
Returns the 404 Override setting, which can be null, a closure or the controller/string.
public
get404Override() : string|Closure|null
Return values
string|Closure|null —getDefaultController()
Returns the name of the default controller. With Namespace.
public
getDefaultController() : string
Return values
string —getDefaultMethod()
Returns the name of the default method to use within the controller.
public
getDefaultMethod() : string
Return values
string —getDefaultNamespace()
Returns the default namespace as set in the Routes config file.
public
getDefaultNamespace() : string
Return values
string —getFilterForRoute()
Returns the filter that should be applied for a single route, along with any parameters it might have. Parameters are found by splitting the parameter name on a colon to separate the filter name from the parameter list, and the splitting the result on commas. So:
public
getFilterForRoute(string $search[, string|null $verb = null ]) : string
'role:admin,manager'
has a filter of "role", with parameters of ['admin', 'manager'].
Parameters
- $search : string
- $verb : string|null = null
Return values
string —getHTTPVerb()
Returns the current HTTP Verb being used.
public
getHTTPVerb() : string
Return values
string —getRedirectCode()
Grabs the HTTP status code from a redirecting Route.
public
getRedirectCode(string $from) : int
Parameters
- $from : string
Return values
int —getRoutes()
Returns the raw array of available routes.
public
getRoutes([string|null $verb = null ]) : array<string|int, mixed>
Parameters
- $verb : string|null = null
Return values
array<string|int, mixed> —getRoutesOptions()
Returns one or all routes options
public
getRoutesOptions([string|null $from = null ][, string|null $verb = null ]) : array<string|int, mixed>
Parameters
- $from : string|null = null
- $verb : string|null = null
Return values
array<string|int, mixed> —group()
Group a series of routes under a single URL segment. This is handy for grouping items into an admin area, like:
public
group(string $name, array<string|int, mixed>|callable ...$params) : void
Example: // Creates route: admin/users $route->group('admin', function() { $route->resource('users'); });
Parameters
- $name : string
-
The name to group/prefix the routes with.
- $params : array<string|int, mixed>|callable
Return values
void —head()
Specifies a route that is only available to HEAD requests.
public
head(string $from, string|array<string|int, mixed> $to[, array<string|int, mixed>|null $options = null ]) : RouteCollectionInterface
Parameters
- $from : string
- $to : string|array<string|int, mixed>
- $options : array<string|int, mixed>|null = null
Return values
RouteCollectionInterface —isFiltered()
Checks a route (using the "from") to see if it's filtered or not.
public
isFiltered(string $search[, string|null $verb = null ]) : bool
Parameters
- $search : string
- $verb : string|null = null
Return values
bool —isRedirect()
Determines if the route is a redirecting route.
public
isRedirect(string $from) : bool
Parameters
- $from : string
Return values
bool —map()
A shortcut method to add a number of routes at a single time.
public
map([array<string|int, mixed> $routes = [] ][, array<string|int, mixed>|null $options = null ]) : RouteCollectionInterface
It does not allow any options to be set on the route, or to define the method used.
Parameters
- $routes : array<string|int, mixed> = []
- $options : array<string|int, mixed>|null = null
Return values
RouteCollectionInterface —match()
Specifies a single route to match for multiple HTTP Verbs.
public
match([array<string|int, mixed> $verbs = [] ][, string $from = '' ][, string|array<string|int, mixed> $to = '' ][, array<string|int, mixed>|null $options = null ]) : RouteCollectionInterface
Example: $route->match( ['get', 'post'], 'users/(:num)', 'users/$1);
Parameters
- $verbs : array<string|int, mixed> = []
- $from : string = ''
- $to : string|array<string|int, mixed> = ''
- $options : array<string|int, mixed>|null = null
Return values
RouteCollectionInterface —options()
Specifies a route that is only available to OPTIONS requests.
public
options(string $from, string|array<string|int, mixed> $to[, array<string|int, mixed>|null $options = null ]) : RouteCollectionInterface
Parameters
- $from : string
- $to : string|array<string|int, mixed>
- $options : array<string|int, mixed>|null = null
Return values
RouteCollectionInterface —patch()
Specifies a route that is only available to PATCH requests.
public
patch(string $from, string|array<string|int, mixed> $to[, array<string|int, mixed>|null $options = null ]) : RouteCollectionInterface
Parameters
- $from : string
- $to : string|array<string|int, mixed>
- $options : array<string|int, mixed>|null = null
Return values
RouteCollectionInterface —post()
Specifies a route that is only available to POST requests.
public
post(string $from, string|array<string|int, mixed> $to[, array<string|int, mixed>|null $options = null ]) : RouteCollectionInterface
Parameters
- $from : string
- $to : string|array<string|int, mixed>
- $options : array<string|int, mixed>|null = null
Return values
RouteCollectionInterface —presenter()
Creates a collections of HTTP-verb based routes for a presenter controller.
public
presenter(string $name[, array<string|int, mixed>|null $options = null ]) : RouteCollectionInterface
Possible Options: 'controller' - Customize the name of the controller used in the 'to' route 'placeholder' - The regex used by the Router. Defaults to '(:any)'
Example:
$route->presenter('photos');
// Generates the following routes:
HTTP Verb | Path | Action | Used for...
----------+-------------+---------------+-----------------
GET /photos index showing all array of photo objects
GET /photos/show/{id} show showing a specific photo object, all properties
GET /photos/new new showing a form for an empty photo object, with default properties
POST /photos/create create processing the form for a new photo
GET /photos/edit/{id} edit show an editing form for a specific photo object, editable properties
POST /photos/update/{id} update process the editing form data
GET /photos/remove/{id} remove show a form to confirm deletion of a specific photo object
POST /photos/delete/{id} delete deleting the specified photo object
Parameters
- $name : string
-
The name of the controller to route to.
- $options : array<string|int, mixed>|null = null
-
An list of possible ways to customize the routing.
Return values
RouteCollectionInterface —put()
Specifies a route that is only available to PUT requests.
public
put(string $from, string|array<string|int, mixed> $to[, array<string|int, mixed>|null $options = null ]) : RouteCollectionInterface
Parameters
- $from : string
- $to : string|array<string|int, mixed>
- $options : array<string|int, mixed>|null = null
Return values
RouteCollectionInterface —resetRoutes()
Reset the routes, so that a test case can provide the explicit ones needed for it.
public
resetRoutes() : mixed
Return values
mixed —resource()
Creates a collections of HTTP-verb based routes for a controller.
public
resource(string $name[, array<string|int, mixed>|null $options = null ]) : RouteCollectionInterface
Possible Options: 'controller' - Customize the name of the controller used in the 'to' route 'placeholder' - The regex used by the Router. Defaults to '(:any)' 'websafe' - - '1' if only GET and POST HTTP verbs are supported
Example:
$route->resource('photos');
// Generates the following routes:
HTTP Verb | Path | Action | Used for...
----------+-------------+---------------+-----------------
GET /photos index an array of photo objects
GET /photos/new new an empty photo object, with default properties
GET /photos/{id}/edit edit a specific photo object, editable properties
GET /photos/{id} show a specific photo object, all properties
POST /photos create a new photo object, to add to the resource
DELETE /photos/{id} delete deletes the specified photo object
PUT/PATCH /photos/{id} update replacement properties for existing photo
If 'websafe' option is present, the following paths are also available:
POST /photos/{id}/delete delete
POST /photos/{id} update
Parameters
- $name : string
-
The name of the resource/controller to route to.
- $options : array<string|int, mixed>|null = null
-
An list of possible ways to customize the routing.
Return values
RouteCollectionInterface —reverseRoute()
Attempts to look up a route based on its destination.
public
reverseRoute(string $search, mixed ...$params) : string|false
If a route exists:
'path/(:any)/(:any)' => 'Controller::method/$1/$2'
This method allows you to know the Controller and method and get the route that leads to it.
// Equals 'path/$param1/$param2'
reverseRoute('Controller::method', $param1, $param2);
Parameters
- $search : string
- $params : mixed
Return values
string|false —set404Override()
Sets the class/method that should be called if routing doesn't find a match. It can be either a closure or the controller/method name exactly like a route is defined: Users::index
public
set404Override([callable|null $callable = null ]) : RouteCollectionInterface
This setting is passed to the Router class and handled there.
Parameters
- $callable : callable|null = null
Return values
RouteCollectionInterface —setAutoRoute()
If TRUE, the system will attempt to match the URI against Controllers by matching each segment against folders/files in APPPATH/Controllers, when a match wasn't found against defined routes.
public
setAutoRoute(bool $value) : RouteCollectionInterface
If FALSE, will stop searching and do NO automatic routing.
Parameters
- $value : bool
Return values
RouteCollectionInterface —setDefaultConstraint()
Sets the default constraint to be used in the system. Typically for use with the 'resource' method.
public
setDefaultConstraint(string $placeholder) : RouteCollectionInterface
Parameters
- $placeholder : string
Return values
RouteCollectionInterface —setDefaultController()
Sets the default controller to use when no other controller has been specified.
public
setDefaultController(string $value) : RouteCollectionInterface
Parameters
- $value : string
Return values
RouteCollectionInterface —setDefaultMethod()
Sets the default method to call on the controller when no other method has been set in the route.
public
setDefaultMethod(string $value) : RouteCollectionInterface
Parameters
- $value : string
Return values
RouteCollectionInterface —setDefaultNamespace()
Sets the default namespace to use for Controllers when no other namespace has been specified.
public
setDefaultNamespace(string $value) : RouteCollectionInterface
Parameters
- $value : string
Return values
RouteCollectionInterface —setHTTPVerb()
Sets the current HTTP verb.
public
setHTTPVerb(string $verb) : $this
Used primarily for testing.
Parameters
- $verb : string
Return values
$this —setPrioritize()
Enable or Disable sorting routes by priority
public
setPrioritize([bool $enabled = true ]) : $this
Parameters
- $enabled : bool = true
-
The value status
Return values
$this —setTranslateURIDashes()
Tells the system whether to convert dashes in URI strings into underscores. In some search engines, including Google, dashes create more meaning and make it easier for the search engine to find words and meaning in the URI for better SEO. But it doesn't work well with PHP method names.
public
setTranslateURIDashes(bool $value) : RouteCollectionInterface
...
Parameters
- $value : bool
Return values
RouteCollectionInterface —shouldAutoRoute()
Returns the flag that tells whether to autoRoute URI against Controllers.
public
shouldAutoRoute() : bool
Return values
bool —shouldTranslateURIDashes()
Returns the current value of the translateURIDashes setting.
public
shouldTranslateURIDashes() : bool
Return values
bool —create()
Does the heavy lifting of creating an actual route. You must specify the request method(s) that this route will work for. They can be separated by a pipe character "|" if there is more than one.
protected
create(string $verb, string $from, string|array<string|int, mixed> $to[, array<string|int, mixed>|null $options = null ]) : mixed
Parameters
- $verb : string
- $from : string
- $to : string|array<string|int, mixed>
- $options : array<string|int, mixed>|null = null
Return values
mixed —discoverRoutes()
Will attempt to discover any additional routes, either through the local PSR4 namespaces, or through selected Composer packages.
protected
discoverRoutes() : mixed
Return values
mixed —fillRouteParams()
Given a
protected
fillRouteParams(string $from[, array<string|int, mixed>|null $params = null ]) : string
Parameters
- $from : string
- $params : array<string|int, mixed>|null = null
Tags
Return values
string —loadRoutesOptions()
Load routes options based on verb
protected
loadRoutesOptions([string|null $verb = null ]) : array<string|int, mixed>
Parameters
- $verb : string|null = null
Return values
array<string|int, mixed> —localizeRoute()
Replaces the {locale} tag with the current application locale
protected
localizeRoute(string $route) : string
Parameters
- $route : string
Return values
string —checkSubdomains()
Compares the subdomain(s) passed in against the current subdomain on this page request.
private
checkSubdomains(mixed $subdomains) : bool
Parameters
- $subdomains : mixed
Return values
bool —determineCurrentSubdomain()
Examines the HTTP_HOST to get a best match for the subdomain. It won't be perfect, but should work for our needs.
private
determineCurrentSubdomain() : mixed
It's especially not perfect since it's possible to register a domain with a period (.) as part of the domain name.