Routing#

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

[info] If you're using the cms module with and dealing with Page objects then for your custom Page Type controllers you would extend ContentController or Page_Controller. You don't need to define the routes value as the cms handles routing. [/info]

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

mysite/_config/routes.yml

	Name: mysiteroutes
	After: framework/routes#coreroutes

	Director:
	  rules:
	    'teams//$Action/$ID/$Name': 'TeamController'
	    'player/': 'PlayerController'
	    '': 'HomeController'

To understand the syntax for the routes.yml file better, read the Configuration documentation. [/notice]

Parameters#

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

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 SS_HTTPRequest object and able to be pulled out from a controller using $this->getRequest()->param($name).

[info] All Controllers have access to $this->getRequest() for the request object and $this->getResponse() for the response. [/info]

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

	// 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.

[alert] A rule must always start with alphabetical ([A-Za-z]) characters or a $Variable declaration [/alert]

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

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

matching controller. The TeamsController is passed an optional action, id and other id parameters to do any more decision making.

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

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

start parsing variables and the appropriate controller action AFTER the //).

URL Handlers#

[alert] You must use the $url_handlers static array described here if your URL pattern does not use the Controller class's default pattern of $Action//$ID/$OtherID. If you fail to do so, and your pattern has more than 2 parameters, your controller will throw the error "I can't handle sub-URLs of a class name object" with HTTP status 404. [/alert]

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.

mysite/code/controllers/TeamController.php

	<?php

	class TeamController extends Controller {

		private static $allowed_actions = array(
			'payroll'
		);

	    private static $url_handlers = array(
			'staff/$ID/$Name' => 'payroll',
			'coach/$ID/$Name' => 'payroll'
	    );

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.

	class FeedController extends ContentController {

		private static $allowed_actions = array('go');
		private static $url_handlers = array(
			'go/$UserName/$AuthToken/$Timestamp/$OutputType/$DeleteMode' => 'go'
		);
		public function go() {
			$this->validateUser(
				$this->getRequest()->param('UserName'),
				$this->getRequest()->param('AuthToken')
			);
			/* more processing goes here */
		}

information for the framework to choose the desired controller.

	Director:
	  rules:
	    'feed': 'FeedController'

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