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

Field	Required	Type	Description
id	required	string	An identifier that is unique to this route. The naming convention for route Ids is {moduleName}_{action}. The Id should only contain lowercase alphabetic characters with underscores delimiting each word.
name	required	string	A user friendly name for the route. This is generally used for the page heading, if applicable.
route	required	string	The URL pattern that is mapped to the controller. There are two ways to define a route pattern. 1. A static URL, such as /users/list 2. A regular expression to capture dynamic URLS (/users/edit/1).
controller	required	string	The controller method to be executed when the route is accessed. The controller and method are delimited by a '@'. For example: UsersController@editUser, where the controller is UsersController and the method to be executed is editUser.
method	optional	string	The HTTP verb that is allowed to access this route. Valid values are GET and POST. If not specified, the route will except all HTTP verbs.
priority	optional	constant	If a route with the same name is already defined, you can give your route a higher priority so it will execute instead of the other duplicate route.Valid values: route::PRIORITY_EXTREMLY_HIGH,route::PRIORITY_HIGH, route::RIORITY_ABOVENORMAL, route::PRIORITY_NORMAL, route::PRIORITY_BELOWNORMAL, route::PRIORITY_LOW
protected	optional	boolean	If true, the route will require users to be logged in to access it. If not specified, the default value is false.

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')