= Routes =

'''Routes''' are the things which translate a URL into a [wiki:Controllers controller] and [wiki:Actions 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 [source:trunk/config/routes.php 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 [source:trunk/system/Router.php 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
<?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
<?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
<?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
<?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
<?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';

}}}