PHPonTrax
[ class tree: PHPonTrax ] [ index: PHPonTrax ] [ all elements ]
Prev Next
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.

    Prev   Next
    DateHelper FormOptionsHelper

    Documentation generated on Thu, 04 May 2006 19:46:55 -0600 by phpDocumentor 1.3.0RC4