Routing#

Routing is the process of mapping URL's to Controller and actions. In the introduction we defined a new custom route for our TeamController mapping any teams URL to our TeamController

These routes by standard, go into a routes.yml file in your applications _config folder alongside your other Configuration information.

app/_config/routes.yml

---
Name: approutes
After:
  - '#rootroutes'
  - '#coreroutes'
---
SilverStripe\Control\Director:
  rules:
    'teams//$Action/$ID/$Name': 'TeamController'
    'player/': 'PlayerController'
    '': 'HomeController'

Parameters#

'teams//$Action/$ID/$Name': 'TeamController'

This route has defined that any URL beginning with team should create, and be handled by a TeamController instance.

It also contains 3 parameters or params for short. $Action, $ID and $Name. These variables are placeholders which will be filled when the user makes their request. Request parameters are available on the HTTPRequest object and able to be pulled out from a controller using $this->getRequest()->param($name).

Here is what those parameters would look like for certain requests

// GET /teams/

print_r($this->getRequest()->params());

// Array
// (
//   [Action] => null
//   [ID] => null
//   [Name] => null
// )

// GET /teams/players/

print_r($this->getRequest()->params());

// Array
// (
//   [Action] => 'players'
//   [ID] => null
//   [Name] => null
// )

// GET /teams/players/1

print_r($this->getRequest()->params());

// Array
// (
//   [Action] => 'players'
//   [ID] => 1
//   [Name] => null
// )

You can also fetch one parameter at a time.

// GET /teams/players/1/

echo $this->getRequest()->param('ID');
// returns '1'

URL Patterns#

The RequestHandler class will parse all rules you specify against the following patterns. The most specific rule will be the one followed for the response.

'teams/$Action/$ID/$OtherID': 'TeamController' 

# /teams/
# /teams/players/
# /teams/

Standard URL handler syntax. For any URL that contains 'team' this rule will match and hand over execution to the matching controller. The TeamsController is passed an optional action, id and other id parameters to do any more decision making.

'teams/$Action!/$ID!/': 'TeamController'

This does the same matching as the previous example, any URL starting with teams will look at this rule but both $Action and $ID are required. Any requests to team/ will result in a 404 error rather than being handed off to the TeamController.

'admin/help//$Action/$ID: 'AdminHelp'

Match an url starting with /admin/help/, but don't include /help/ as part of the action (the shift point is set to start parsing variables and the appropriate controller action AFTER the //).

Wildcard URL Patterns#

As of Silverstripe CMS 4.6 there are two wildcard patterns that can be used. $@ and $*. These parameters can only be used at the end of a URL pattern, any further rules are ignored.

Inspired by bash variadic variable syntax there are two ways to capture all URL parameters without having to explicitly specify them in the URL rule.

Using $@ will split the URL into numbered parameters ($1, $2, ..., $n). For example:

<?php
class StaffController extends \SilverStripe\Control\Controller
{
    private static $url_handlers = [
        'staff/$@' => 'index',
    ];

    public function index($request)
    {
        // GET /staff/managers/bob
        $request->latestParam('$1'); // managers
        $request->latestParam('$2'); // bob
    }
}

Alternatively, if access to the parameters is not required in this way then it is possible to use $* to match all URL parameters but not collect them in the same way:

<?php
class StaffController extends \SilverStripe\Control\Controller
{
    private static $url_handlers = [
        'staff/$*' => 'index',
    ];

    public function index($request)
    {
        // GET /staff/managers/bob
        $request->remaining(); // managers/bob
    }
}

URL Handlers#

In the above example the URLs were configured using the Director rules in the routes.yml file. Alternatively you can specify these in your Controller class via the $url_handlers static array. This array is processed by the RequestHandler at runtime once the Controller has been matched.

This is useful when you want to provide custom actions for the mapping of teams/*. Say for instance we want to respond coaches, and staff to the one controller action payroll.

app/src/controllers/TeamController.php

use SilverStripe\Control\Controller;

class TeamController extends Controller
{
    private static $allowed_actions = [
        'payroll'
    ];

    private static $url_handlers = [
        'staff/$ID/$Name' => 'payroll',
        'coach/$ID/$Name' => 'payroll'
    ];

The syntax for the $url_handlers array users the same pattern matches as the YAML configuration rules.

Now let’s consider a more complex example from a real project, where using $url_handlers is mandatory. In this example, the URLs are of the form http://example.org/feed/go/, followed by 5 parameters. The PHP controller class specifies the URL pattern in $url_handlers. Notice that it defines 5 parameters.

use SilverStripe\CMS\Controllers\ContentController;

class FeedController extends ContentController
{
    private static $allowed_actions = ['go'];
    private static $url_handlers = [
        'go/$UserName/$AuthToken/$Timestamp/$OutputType/$DeleteMode' => 'go'
    ];

    public function go()
    {
        $this->validateUser(
            $this->getRequest()->param('UserName'),
            $this->getRequest()->param('AuthToken')
        );
        /* more processing goes here */
    }
}

The YAML rule, in contrast, is simple. It needs to provide only enough information for the framework to choose the desired controller.

SilverStripe\Control\Director:
  rules:
    'feed': 'FeedController'

Root URL Handlers#

In some cases, the Director rule covers the entire URL you intend to match, and you simply want the controller to respond to a 'root' request. This request will automatically direct to an index() method if it exists on the controller, but you can also set a custom method to use in $url_handlers with the '/' key:

use SilverStripe\Control\Controller;

class BreadAPIController extends Controller
{
    private static $allowed_actions = [
        'getBreads',
        'createBread',
    ];

    private static $url_handlers = [
        'GET /' => 'getBreads',
        'POST /' => 'createBread',
    ];

Related Lessons#

• Creating filtered views
• Controller actions / DataObjects as pages

Links#

• Controller API documentation
• Director API documentation
• Example routes: framework
• Example routes: cms