Routes

Routes are the things which translate a URL into a controller? and action?. They can also define parameters that are available to the controller, such as an ID or other identifier.

Definitions

Routes are defined in the file config/routes.php.

The default routes map a URL directly to a controller and action. For example: http://example.com/foo/bar maps to the bar action of the FooController. If no action is specified in the route, the Router will assume the action is index.

Creating Routes

NB: This area is under active development and will change! Also, I'm sorry about how I did this initially.

Routes are (currently) defined as regular expressions and matching route information. The regular expression is the key of the global array $routes, and the route information is the value, stored as an array.

<?php
// config/routes.php

$routes['RegExp'] = array('controller/action', 'param1', 'param2', ...);

The regular expressions are bounded with hash marks (#) so forward slashes (/) can be used without escaping. As always, periods (.) and other special characters must be escaped.

Most routes should end in the dollar sign ($) character, to prevent the a short route from matching a longer URL. However, since there are conceivable reasons not to do this, it is not automatically implemented.

Routes with no RegExp subpatterns are essentially static routes, meaning that the controller and action must be explicitly defined. The controller and/or action may also be extracted from subpatterns in the regular expression:

<?php
// config/routes.php

$routes['([a-z]\w+)/([a-z]\w+)/?$'] = array('$1/$2');

// Test URL: http://example.com/foo/bar
// controller = FooController;
// action = bar;

The $1 and $2 are the subpattern identifiers. $0, which would match the whole URL, is not implemented. Any other identifiers may be used, such as:

<?php
// config/routes.php

$routes['articles/([0-9]+)(?:/(\w+))?$'] = array('article/$3', 'id');

// Test URL: http://example.com/articles/23/print
// controller = ArticleController; action = print()

// Test URL: http://example.com/articles/42
// controller = ArticleController; action = index() (the default)

Shorthand

The following "shorthand" codes are defined. They are essentially an easy way to create a shorter, somewhat more readable route. The shorthand on the left will be replaced with the subpattern on the right before the regular expression is compiled:

Code	Subpattern	Meaning
:controller	([a-zA-Z][_a-zA-Z0-9]*)	A valid name for a PHP class
:action	([_a-zA-Z][_a-zA-Z0-9]*)	A valid name for a PHP class method
:id	(\d+)	A number
:format	(\w+)	A valid document extension

The default routes are defined somewhat like:

<?php
// config/routes.php

$routes[':controller(?:/:action(?:/:id)?)?(?:\.:format)?$') = array('$1/$2', 'id', 'format');
// Test URL: http://example.com/foo/bar/23.htm
// Controller: FooController
// Action:     FooController->bar()
// FooController->params['id'] = 23;
// FooController->params['format'] = 'htm';

Cascading

Importantly, routes are checked in order. That is, if the first defined route matches the current URL, no other routes are checked. That means static routes must come first, and more liberal routes must come last. The default route must be the last route defined.

Default Route

The default route has a special regular expression: _default. It must be the last route defined. If no other route matches, the default route will be used.

Rather than making the default map to your index page, consider mapping _default to a 404 page, perhaps returning a 404 header, and mapping the empty route ('$') to the index.

Examples

<?php

// A static route:
$routes['about'] = array('default/about');
// maps the URL http://example.com/about to DefaultController->about()

// An ID-based user profile page:
$routes['user/:id'] = array('user/profile', 'id');
// maps http://example.com/user/24 to UserController->profile()
// UserController->params['id'] = 24

// A name-based user profile page:
$routes['user/([a-z]\w{2,})/?'] = array('user/profile', 'name');
// maps http://example.com/user/examplename to UserController->profile()
// UserController->params['name'] = 'examplename';