2014-10-18 00:28:51 +02:00
|
|
|
|
title: Routing
|
|
|
|
|
summary: A more in depth look at how to map requests to particular controllers and actions.
|
|
|
|
|
|
|
|
|
|
# Routing
|
|
|
|
|
|
|
|
|
|
Routing is the process of mapping URL's to [api:Controllers] and actions. In the introduction we defined a new custom route
|
2016-12-30 00:17:15 +01:00
|
|
|
|
for our `TeamController` mapping any `teams` URL to our `TeamController`
|
2014-10-18 00:28:51 +02:00
|
|
|
|
|
|
|
|
|
<div class="info" markdown="1">
|
|
|
|
|
If you're using the `cms` module with and dealing with `Page` objects then for your custom `Page Type` controllers you
|
2016-12-30 00:17:15 +01:00
|
|
|
|
would extend `ContentController` or `PageController`. You don't need to define the routes value as the `cms` handles
|
2014-10-18 00:28:51 +02:00
|
|
|
|
routing.
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
These routes by standard, go into a `routes.yml` file in your applications `_config` folder alongside your other
|
|
|
|
|
[Configuration](../configuration) information.
|
|
|
|
|
|
|
|
|
|
**mysite/_config/routes.yml**
|
|
|
|
|
|
2016-12-30 00:17:15 +01:00
|
|
|
|
```yml
|
|
|
|
|
---
|
|
|
|
|
Name: mysiteroutes
|
|
|
|
|
After: framework/routes#coreroutes
|
|
|
|
|
---
|
2017-02-03 18:06:02 +01:00
|
|
|
|
SilverStripe\Control\Director:
|
2016-12-30 00:17:15 +01:00
|
|
|
|
rules:
|
|
|
|
|
'teams//$Action/$ID/$Name': 'TeamController'
|
|
|
|
|
'player/': 'PlayerController'
|
|
|
|
|
'': 'HomeController'
|
|
|
|
|
```
|
2014-10-18 00:28:51 +02:00
|
|
|
|
|
|
|
|
|
<div class="notice" markdown="1">
|
|
|
|
|
To understand the syntax for the `routes.yml` file better, read the [Configuration](../configuration) documentation.
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
## Parameters
|
|
|
|
|
|
2016-12-30 00:17:15 +01:00
|
|
|
|
```yml
|
|
|
|
|
'teams//$Action/$ID/$Name': 'TeamController'
|
|
|
|
|
```
|
2014-10-18 00:28:51 +02:00
|
|
|
|
|
|
|
|
|
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
|
2016-09-09 08:43:05 +02:00
|
|
|
|
which will be filled when the user makes their request. Request parameters are available on the `HTTPRequest` object
|
2015-04-30 01:04:08 +02:00
|
|
|
|
and able to be pulled out from a controller using `$this->getRequest()->param($name)`.
|
2014-10-18 00:28:51 +02:00
|
|
|
|
|
|
|
|
|
<div class="info" markdown="1">
|
2015-08-14 02:39:33 +02:00
|
|
|
|
All Controllers have access to `$this->getRequest()` for the request object and `$this->getResponse()` for the response.
|
2014-10-18 00:28:51 +02:00
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
Here is what those parameters would look like for certain requests
|
|
|
|
|
|
2016-12-30 00:17:15 +01:00
|
|
|
|
```php
|
|
|
|
|
// GET /teams/
|
2014-10-18 00:28:51 +02:00
|
|
|
|
|
2016-12-30 00:17:15 +01:00
|
|
|
|
print_r($this->getRequest()->params());
|
2014-10-18 00:28:51 +02:00
|
|
|
|
|
2016-12-30 00:17:15 +01:00
|
|
|
|
// Array
|
|
|
|
|
// (
|
|
|
|
|
// [Action] => null
|
|
|
|
|
// [ID] => null
|
|
|
|
|
// [Name] => null
|
|
|
|
|
// )
|
2014-10-18 00:28:51 +02:00
|
|
|
|
|
2016-12-30 00:17:15 +01:00
|
|
|
|
// GET /teams/players/
|
2014-10-18 00:28:51 +02:00
|
|
|
|
|
2016-12-30 00:17:15 +01:00
|
|
|
|
print_r($this->getRequest()->params());
|
2014-10-18 00:28:51 +02:00
|
|
|
|
|
2016-12-30 00:17:15 +01:00
|
|
|
|
// Array
|
|
|
|
|
// (
|
|
|
|
|
// [Action] => 'players'
|
|
|
|
|
// [ID] => null
|
|
|
|
|
// [Name] => null
|
|
|
|
|
// )
|
2014-10-18 00:28:51 +02:00
|
|
|
|
|
2016-12-30 00:17:15 +01:00
|
|
|
|
// GET /teams/players/1
|
2014-10-18 00:28:51 +02:00
|
|
|
|
|
2016-12-30 00:17:15 +01:00
|
|
|
|
print_r($this->getRequest()->params());
|
2014-10-18 00:28:51 +02:00
|
|
|
|
|
2016-12-30 00:17:15 +01:00
|
|
|
|
// Array
|
|
|
|
|
// (
|
|
|
|
|
// [Action] => 'players'
|
|
|
|
|
// [ID] => 1
|
|
|
|
|
// [Name] => null
|
|
|
|
|
// )
|
|
|
|
|
```
|
2014-10-18 00:28:51 +02:00
|
|
|
|
|
|
|
|
|
You can also fetch one parameter at a time.
|
|
|
|
|
|
2016-12-30 00:17:15 +01:00
|
|
|
|
```php
|
|
|
|
|
// GET /teams/players/1/
|
2014-10-18 00:28:51 +02:00
|
|
|
|
|
2016-12-30 00:17:15 +01:00
|
|
|
|
echo $this->getRequest()->param('ID');
|
|
|
|
|
// returns '1'
|
|
|
|
|
```
|
2014-10-18 00:28:51 +02:00
|
|
|
|
|
|
|
|
|
## URL Patterns
|
|
|
|
|
|
2016-02-17 22:21:59 +01:00
|
|
|
|
The [api:RequestHandler] class will parse all rules you specify against the following patterns. The most specific rule
|
2014-10-18 00:28:51 +02:00
|
|
|
|
will be the one followed for the response.
|
|
|
|
|
|
|
|
|
|
<div class="alert">
|
|
|
|
|
A rule must always start with alphabetical ([A-Za-z]) characters or a $Variable declaration
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
| Pattern | Description |
|
|
|
|
|
| ----------- | --------------- |
|
|
|
|
|
| `$` | **Param Variable** - Starts the name of a paramater variable, it is optional to match this unless ! is used |
|
|
|
|
|
| `!` | **Require Variable** - Placing this after a parameter variable requires data to be present for the rule to match |
|
|
|
|
|
| `//` | **Shift Point** - Declares that only variables denoted with a $ are parsed into the $params AFTER this point in the regex |
|
|
|
|
|
|
2016-12-30 00:17:15 +01:00
|
|
|
|
```yml
|
|
|
|
|
'teams/$Action/$ID/$OtherID': 'TeamController'
|
2014-10-18 00:28:51 +02:00
|
|
|
|
|
2016-12-30 00:17:15 +01:00
|
|
|
|
# /teams/
|
|
|
|
|
# /teams/players/
|
|
|
|
|
# /teams/
|
|
|
|
|
```
|
2014-10-18 00:28:51 +02:00
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2016-12-30 00:17:15 +01:00
|
|
|
|
```yml
|
|
|
|
|
'teams/$Action!/$ID!/': 'TeamController'
|
|
|
|
|
```
|
2014-10-18 00:28:51 +02:00
|
|
|
|
|
|
|
|
|
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`.
|
|
|
|
|
|
2016-12-30 00:17:15 +01:00
|
|
|
|
```yml
|
|
|
|
|
'admin/help//$Action/$ID: 'AdminHelp'
|
|
|
|
|
```
|
2014-10-18 00:28:51 +02:00
|
|
|
|
|
|
|
|
|
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 `//`).
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## URL Handlers
|
|
|
|
|
|
2015-03-05 20:48:31 +01:00
|
|
|
|
<div class="alert" markdown="1">
|
|
|
|
|
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.
|
|
|
|
|
</div>
|
|
|
|
|
|
2014-10-18 00:28:51 +02:00
|
|
|
|
In the above example the URLs were configured using the [api: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
|
|
|
|
|
[api: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**
|
|
|
|
|
|
2016-12-30 00:17:15 +01:00
|
|
|
|
```
|
|
|
|
|
<?php
|
2014-10-18 00:28:51 +02:00
|
|
|
|
|
2016-12-30 00:17:15 +01:00
|
|
|
|
use SilverStripe\Control\Controller;
|
2014-10-18 00:28:51 +02:00
|
|
|
|
|
2016-12-30 00:17:15 +01:00
|
|
|
|
class TeamController extends Controller
|
|
|
|
|
{
|
|
|
|
|
private static $allowed_actions = array(
|
|
|
|
|
'payroll'
|
|
|
|
|
);
|
2014-10-18 00:28:51 +02:00
|
|
|
|
|
2016-12-30 00:17:15 +01:00
|
|
|
|
private static $url_handlers = array(
|
|
|
|
|
'staff/$ID/$Name' => 'payroll',
|
|
|
|
|
'coach/$ID/$Name' => 'payroll'
|
|
|
|
|
);
|
|
|
|
|
```
|
2014-10-18 00:28:51 +02:00
|
|
|
|
|
|
|
|
|
The syntax for the `$url_handlers` array users the same pattern matches as the `YAML` configuration rules.
|
|
|
|
|
|
2015-03-05 20:48:31 +01:00
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
2016-12-30 00:17:15 +01:00
|
|
|
|
```php
|
|
|
|
|
use SilverStripe\CMS\Controllers\ContentController;
|
|
|
|
|
|
|
|
|
|
class FeedController extends ContentController
|
|
|
|
|
{
|
|
|
|
|
private static $allowed_actions = array('go');
|
|
|
|
|
private static $url_handlers = array(
|
|
|
|
|
'go/$UserName/$AuthToken/$Timestamp/$OutputType/$DeleteMode' => 'go'
|
|
|
|
|
);
|
2015-03-05 20:48:31 +01:00
|
|
|
|
|
2016-12-30 00:17:15 +01:00
|
|
|
|
public function go()
|
|
|
|
|
{
|
|
|
|
|
$this->validateUser(
|
|
|
|
|
$this->getRequest()->param('UserName'),
|
|
|
|
|
$this->getRequest()->param('AuthToken')
|
|
|
|
|
);
|
|
|
|
|
/* more processing goes here */
|
|
|
|
|
}
|
|
|
|
|
}
|
2015-03-05 20:48:31 +01:00
|
|
|
|
|
|
|
|
|
The YAML rule, in contrast, is simple. It needs to provide only enough
|
|
|
|
|
information for the framework to choose the desired controller.
|
|
|
|
|
|
2016-12-30 00:17:15 +01:00
|
|
|
|
```yml
|
|
|
|
|
Director:
|
|
|
|
|
rules:
|
|
|
|
|
'feed': 'FeedController'
|
|
|
|
|
```
|
2015-03-05 20:48:31 +01:00
|
|
|
|
|
2014-11-15 04:01:47 +01:00
|
|
|
|
## Links
|
2014-10-18 00:28:51 +02:00
|
|
|
|
|
2014-11-15 04:01:47 +01:00
|
|
|
|
* [api:Controller] API documentation
|
|
|
|
|
* [api:Director] API documentation
|
|
|
|
|
* [Example routes: framework](https://github.com/silverstripe/silverstripe-framework/blob/master/_config/routes.yml)
|
|
|
|
|
* [Example routes: cms](https://github.com/silverstripe/silverstripe-cms/blob/master/_config/routes.yml)
|