Routing

Routing is the process of mapping a URL pattern to a controller method. When that URL pattern is accessed, the request will execute its corresponding controller.

Where are routes defined?

Routes are defined inside the getRoutes() method of a module's configuration file, identified by {moduleName}Config.php. The method returns an array of Route objects. Specialized route objects, which extend the Route object may also be included in the list.

<?php
class UserConfig extends moduleConfig {
    /**
     * Defines all of  the routes relevant to the User module.
     *
     * @return route[]
     */
    public static function getRoutes() {
        return array(
            new route(array(
                'id'            => 'user_list',
                'name'          => 'Our Users',
                'route'         => '/users/list',
                'controller'    => 'UsersController@index',
                'method'        => 'GET',
                'priority'      => route::PRIORITY_HIGH,
                'protected'     => false
             ))
        );
    }
}

Basic Route

Basic routes are defined by the sa\application\route object. These are strictly used for application-facing routing. In other words, this route type is not acceptable for static assets (CSS, JS, Img) or administrative pages.

Route constructor options

Siteadmin Route

Siteadmin routes are defined by the sa\application\saRoute object, which extends the basic route and accepts the same constructor parameters. These routes may only be accessed by users who are logged in as a Siteadmin user. The naming convention of siteadmin routes is similar to the convention for basic routes, with the addition of a sa_ prefix at the beginning of the route id field.

<?php
new saRoute(array(
    'id'            => 'sa_user_list',
    'name'          => 'Our Users',
    'route'         => '/users/list',
    'controller'    => 'UsersController@index',
    'method'        => 'GET',
    'priority'      => route::PRIORITY_HIGH
));

Resource Route

Resource routes respond to requests for CSS, JS, and image assets.

<?php
new resourceRoute(array(
    'id'=>'user_css',
    'name'=>'css',
    'route'=>'^/user/css/[a-zA-Z0-9-_\.]{1,}$',
    'controller'=>'UserResourceController@css'
 ));

URL Parameters & Regular Expressions

Some routes may require dynamic parameters, such as ID's or page titles. The routing system uses regular expressions to restrict the data type and format of theses route parameters.

Numeric ID with variable length

^/user/[0-9]$

Numeric ID with fixed length

^/user/[0-9]{9,9}$

String parameter

^/pages/[a-z0-9-_]$

Multiple Parameters

^/user/[0-9]/invoices/[0-9]$

Optional Parameters

It's worth noting that optional parameters are not supported. The following routes are not valid.

^/user/[0-9]{0,}$
^/user/[0-9]?$

Passing URL Parameters to a Controller

View the controller documentation's Accessing URL Parameters section.

Find route object by ID

While the URL utility is useful for parsing and building URLs, sometimes it is necessary to access the raw route object. The global app context provides a helper function to achieve this.

Consider the following route...

new route(array(
    'id'            => 'user_list',
    'name'          => 'Our Users',
    'route'         => '/users/list',
    'controller'    => 'UsersController@index',
    'method'        => 'GET',
    'priority'      => route::PRIORITY_HIGH,
    'protected'     => false
))

You can retrieve this object by referencing its ID with the line below.

app::get()->findRouteById('user_list')

Last updated