This library determines a route for a web request. It is built to be easy to use and fast.
For the most basic of routing needs, an array can simply be passed to the
Router class constructor. Each route array should consist of a type,
pattern, and either an action or array of sub-routes called routes.
While action has no meaning to the router itself, its purpose is for use
after matching.
$r = new PageMill\Router\Router(
[
[
"type" => "exact",
"pattern" => "/foo",
"action" => "Foo"
],
[
"type" => "exact",
"pattern" => "/foo/bar",
"action" => "FooBar"
],
]
);
$route = $r->match("/foo");You can also add routes using the add method.
$r = new PageMill\Router\Router();
$r->add("exact", "/foo", "Foo");
$r->add("exact", "/foo/bar/", "FooBar");
$route = $r->match("/foo");If performance is important, it is suggested to pass the routes into the constructor.
There are three matching types supported plus a default route.
exact - The request path must match pattern exactly.
starts_with - Matches when the request path begins with the exact value of pattern.
regex - Uses a regular expression to match against the reqeust path.
default - A default route to use if no other route is matched. A default
route does not require a pattern. There must only be one
default route defined.
Optionally, a route can include an array of tokens that allow for using values
from the request path to fill a named array in the return value of the match
method. This is only valid for starts_with and exact match types.
For starts_with matches, the tokens will be filled in based on values that
appear in the request path between slashes (/) that are not part of the pattern.
$r = new PageMill\Router\Router(
[
[
"type" => "starts_with",
"pattern" => "/foo/",
"action" => "Foo",
"tokens" = [
"group",
"id"
]
]
]
);
$route = $r->match("/foo/1/2/");The value of $route would be:
array(
"type" => "starts_with",
"pattern" => "/foo/",
"action" => "Foo",
"tokens" = [
"group" => 1,
"id" => 2
]
)For regex matches, the tokens will be filled based on back references used
in the regular expression.
$r = new PageMill\Router\Router(
[
[
"type" => "regex",
"pattern" => "/foo/(\d+)/(\d+)/",
"action" => "Foo",
"tokens" = [
"group",
"id"
]
]
]
);
$route = $r->match("/foo/1/2/");The value of $route would be:
[
"type" => "regex",
"pattern" => "/foo/",
"action" => "Foo",
"tokens" = [
"group" => 1,
"id" => 2
]
]It is also possible to match on hostname, request method, Accept header, and other HTTP headers by adding these settings to the route array.
host - Matches the HTTP Host header.
method - Matches the HTTP request method (GET, POST, etc.)
accept - Validates the Accept header contains one of a list of mime types.
headers - An array of headers and the patterns to match them.
To match on hostname, add host to the route config. To only match GET
requests, add method.
$r = new PageMill\Router\Router(
[
[
"type" => "regex",
"pattern" => "/foo/(\d+)/(\d+)/",
"action" => "Foo",
"host" => "www.example.com",
"method" => "GET"
]
]
);
$route = $r->match("/foo/1/2/");The value of $route would be:
[
"type" => "starts_with",
"pattern" => "/foo/",
"action" => "Foo",
"tokens" = [
"group" => 1,
"id" => 2
]
"host" => "www.example.com",
"method" => "GET"
]By default, this is treated as an exact match. You can do more complex
matching by providing an array with type and pattern set. This is true
of host, method and the patterns in the headers array.
$r = new PageMill\Router\Router(
[
[
"type" => "regex",
"pattern" => "/foo/(\d+)/(\d+)/",
"action" => "Foo",
"host" => [
"type" => "regex",
"pattern" => '/\.example\.com$/'
],
"method" => "GET"
]
]
);
$route = $r->match("/foo/1/2/");The matched values of these settings will be returned in the matched route
array. The value of $route would be:
[
"type" => "starts_with",
"pattern" => "/foo/",
"action" => "Foo",
"tokens" = [
"group" => 1,
"id" => 2
]
"host" => "www.example.com",
"method" => "GET"
]To validate the Accept header against a list of mime types, this route config
could be used. For this example, assume the Accept header from the client contains text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8.
NOTE: Unlike other options, the accept option only accepts a single string
mime type or an array of mime types.
$r = new PageMill\Router\Router(
[
[
"type" => "regex",
"pattern" => "/foo/(\d+)/(\d+)/",
"action" => "Foo",
"accept" => [
"text/html"
]
]
]
);
$route = $r->match("/foo/1/2/");The value of $route would be:
[
"type" => "starts_with",
"pattern" => "/foo/",
"action" => "Foo",
"tokens" = [
"group" => 1,
"id" => 2
]
"accept" => "text/html"
]Router will honor the clients quality scores from the Accept header. For an explination of the quality score used in HTTP client Accept headers, see https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html. If the quality scores for the matching mime types is equal, the order they are defined in the configuration will be honored.
$r = new PageMill\Router\Router(
[
[
"type" => "regex",
"pattern" => "/foo/(\d+)/(\d+)/",
"action" => "Foo",
"accept" => [
"application/json"
"text/html"
]
]
]
);
$route = $r->match("/foo/1/2/");Because the quality score for text/html is not defined in the Accept header,
it is assumed to be 1. The value of $route would be:
[
"type" => "starts_with",
"pattern" => "/foo/",
"action" => "Foo",
"tokens" = [
"group" => 1,
"id" => 2
]
"accept" => "text/html"
]To match an arbitrary HTTP header, add headers to the route config.
This example will ensure that the Authorization header contains 12345678.
$r = new PageMill\Router\Router(
[
[
"type" => "regex",
"pattern" => "/foo/(\d+)/(\d+)/",
"action" => "Foo",
"headers" => [
"Authorization" => [
"type" => "exact",
"pattern" => '12345678'
]
]
]
]
);
$route = $r->match("/foo/1/2/");The value of $route would be:
[
"type" => "starts_with",
"pattern" => "/foo/",
"action" => "Foo",
"tokens" = [
"group" => 1,
"id" => 2
]
"headers" => [
"Authorization" => "12345678"
]
]$r = new PageMill\Router\Router(
[
[
"type" => "exact",
"pattern" => "/foo/",
"action" => "Foo",
],
[
"type" => "default",
"action" => "Default",
]
]
);
$route = $r->match("/foo/1/2/");The value of $route would be:
[
"type" => "default",
"action" => "Default",
]Note: No tokens will be returned and no pattern matching is performed on the path for the default route.
Only one default route is allowed. An InvalidRoute exception will be thrown
if more than one default route is defined.
If you have several routes that all have the same prefix or match the same
pattern, it can be beneficial to group those routes as sub-routes under a
more general route. For example, if we have multiple routes that fall under
the /foo path, we could configure our routes like this:
$r = new PageMill\Router\Router(
[
[
"type" => "starts_with",
"pattern" => "/foo",
"routes" => [
[
"type" => "exact",
"pattern" => "/foo/bar",
"action" => "FooBar"
],
[
"type" => "exact",
"pattern" => "/foo/baz",
"action" => "FooBaz"
],
]
]
]
);
$route = $r->match("/foo/bar");The value of $route would be:
[
"type" => "exact",
"pattern" => "/foo/bar",
"action" => "FooBar"
]If you would like to save the route list for reuse, you can call the
getRoutes() method.
$r = new PageMill\Router\Router(
[
[
"type" => "exact",
"pattern" => "/foo/",
"action" => "Foo",
],
[
"type" => "default",
"action" => "Default",
]
]
);
$routes = $r->get_routes();