Routing

Typically, a URI will map to a controller class and method on a one-to-one basis and provide arguments where necessary. For example,

http://www.example.com/class/function/arg1/arg2

The first segment refers to the controller class, the second to a method in that class and any other segments become that method's arguments.

There are cases, however, where you might want to change this behaviour. For example, you may want to use URIs like this: www.example.com/article/22. Here, the second segment of the URI is an article number, which is an argument, not a controller method. The routing feature of Kohana allows you to change how URIs are mapped to controllers and methods.

In order to alter routing you have to have a copy of routes.php in your application/config directory. If it is not already there copy the one from the system/config directory.

The default routes.php will have one entry:

$config['_default'] = 'welcome';

$config['_default'] specifies the default route. It is used to indicate which controller should be used when a URI contains no segments. For example, if your web application is at www.example.com and you visit this address with a web browser, the welcome controller would be used even though it wasn't specified in the URI. The result would be the same as if the browser had gone to www.example.com/welcome.

In addition to the default route above, you can also specify your own routes. The basic format for a routing rule is:

$config['route'] = 'class/method';

where route is the URI you want to route, and class/method would replace it.

So, for example, if your Kohana web application were installed at www.example.com and you had the following routing rule:

$config['test'] = 'foo/bar';

and you visited www.example.com/test in a web browser, you would see the page at www.example.com/foo/bar.

The route part of a routing rule is actually a regular expression. If you are unfamiliar with regular expressions you can read more about them at the PHP website. Using regular expressions, you can be more selective about which URIs will match your routing rules, and you can make use of the sub-pattern back referencing technique to re-use parts of the URI in it's replacement.

This is best described with an example. Suppose we wanted to make the URL www.example.com/article/22 work, we might use a routing rule like this:

$config['article/([0-9]+)'] = 'news/show/$1';

which would match URIs starting with “article/” followed by some numeric digits. If the URI takes this form, we will use the news controller and call it's show() method passing in the article number as the first argument. In the www.example.com/article/22 example, it is as if the URL www.example.com/news/show/22 had been visited.

There are several public properties of the Router-class, which are available after routing has occurred.

Returns the part of the URL which is used for routing. For example, if the URL http://localhost/welcome/index/var1?var2=2 is requested, this property will contain

welcome/index/var1

If the URL http://localhost/ is requested, this property will contain the default route.

Returns the query part of the requested URL, including the question mark.

For example, for the URL http://localhost/welcome?var1=1&var2=2, this property would contain the string

?var1=1&var2=2

Returns Router::$current_uri appended with Router::$query_string.

Returns the URI which is determined by routing Router::$current_uri.

With default routing configuration, $routed_uri will match $current_uri. If you configure the route

$config['test'] = 'foo/bar';

and request the URL http://localhost/test, this property will contain the string

foo/bar

Returns the suffix of the requested URL if it is BOTH configured in config.php AND used in the current request.

For example, if you configure the url suffix .php and request the URL http://localhost/welcome.php, this property will contain the string

.php

Returns Router::$current_uri split up into segments.

For example, if Router::$current_uri contains

welcome/index

, this property will contain the array

array('welcome', 'index');

Returns Router::$routed_uri split up into segments.

For example, if Router::$routed_uri contains

welcome/index

, this property will contain the array

array('welcome', 'index');

Returns the name of the controller to which the request is routed.

For example, when a method of the controller welcome (class name: Welcome_Controller) is called, regardless of how the request was routed there, this property would contain the string

welcome

It does not include any subdirectories in which the controller file might reside, only the name of the controller itself.

Returns the absolute path of the controller script file. For example, if a fresh Kohana-installation would be setup inside the directory /var/www/ and a method of the controller welcome would be called, this property would contain the string

/var/www/application/controllers/welcome.php

Returns the name of the method to which the request is routed.

For example, when the method index of the controller welcome is called, regardless of how the request was routed there, this property would contain the string

index

Returns the segments of the URL which are not needed for determining the controller and the method. These segments are also passed to the controller method as method arguments.

For example, with default routing configuration, when the URL http://localhost/welcome/index/var1/var2?var3=3&var4=4 would be requested, this property would contain the array

array('var1', 'var2');