Router
Router
Convert a URL to an action
Table of Contents
Introduction
The Router class owns the information and
algorithms that convert URLs to actions. An object of this class
holds a route table containing routes to be
matched to URLs.
In normal operation, a Router object is created by
ActionController::load_router() which reads routes from the
configuration file config/routes.php.
Structure of the Route Table
The route table is an ordered list of routes. A route consists
of a path and a (possibly null) parameter array. The structure of
the table is:
$routes[0]['path'] First route path
['params'] First route parameters
[1]['path'] Second route path
['params'] Second route parameters
...
A route path consists of character strings separated by
forward slash ('/') characters. The route path must not begin
or end with '/', and the character strings in the path must
not contain '/'. There are two kinds of character strings in
route paths:
Keyword strings start with a colon (':') followed by
a keyword consisting of
one or more alphameric characters chosen from "a..z0..9_-". A
keyword string matches any alphameric string in the same
position of a URL. The value of the keyword following ':' is
irrelevant to Router, but certain keywords are meaninful to
ActionController.
Pattern strings start with any character except ':' or
'/' followed by any character except '/'. The contents of
the pattern string are a
Perl regular expression.
The order of routes in the table is significant. When a URL
is to be matched, the route table is searched in order from first
entry to last. The first route entry that matches is
returned.
Router::find_route() guarantees that there will always be
at least one route in the table by inserting
Router::$default_route_path if the table is empty when
find_route() is called.
Constructing the Route Table
To construct a route table, first create a new Router object,
then make multiple calls to Router::connect() to add route
entries to the object's table. The second argument to connect(), if
specified, must be an array, but the array can hold anything (or
nothing).
There is no way to change or delete an existing route table
entry.
Either assure that any path you search for will return some
route, or prepare to deal with a null return from
Router::find_route()
CAUTION: Do not call
Router::find_route() before calling
Router::connect(), unless you want the default route to be
the first entry in the route table.
Searching the Route Table
To look up a URL in the route table, call
Router::find_route() with the URL as argument. A copy of
the first matching route table entry, if any, will be returned. If
none matches, null will be returned.
A URL consisting of a null string '' matches a route
whose path is a null string.
A copy of the last route table entry returned by find_route()
is saved in Router::$selected_route. It can be fetched by
a call to Router::get_selected_route(). The next call to
find_route() overwrites the previous value in
$selected_route.