boxuk/boxuk-routing

Routing library for PHP front controller based applications

Box UK Routing

This library provides an easy way to add highly configurable routing support to your Front Controller based application. It comes with an input router to pass control to your application classes, and an output filter that transforms HTML to use these routes automatically. All of this is then configured through one easy to read routing file.

Requirements

• PHP 5.3

The Routing File

The routing file is designed to be as easy to read as possible, and simply maps URLs on the left side, to the controller to handle them on the right. Here's a simple example...

/user/:num = user:show( id )

The format for route definitions is as follows:

METHOD URL = CONTROLLER:ACTION( PARAMS )

The method allows you to limit certain routes to certain HTTP request methods. If the action is not specified then it defaults to 'index'.

URLs

The left hand side specifies the URL for the route. You specify your dynamic parameters with a colon (eg. :num), by default these are...

• :num
• :word
• :file
• :any

Additional Types

You can specify additional types using regular expressions.

:num = ID\d\d\w+

Controller Blocks

As a shorthand (and a neat way of keeping related specs together) you can use controller blocks to eliminate the need to specify the controller in your routes.

[foo]
/this/:word = show( name )
/some/:num = ( id )
[*]

The above example shows two routes defined for a controller called 'foo'. As you can see it's no longer required to specify foo for each route. The controller block is then ended with a star (indicating any controller can now be used in routes)

Base Paths

You can also specify a base path for a controller block which means all routes have that as their prefix. This is useful when all of a controllers routes have the same prefix, for example:

[admin:/private/admin]
/:word = ( action )
/ = ()
[*]

This would then send URLs like /private/admin/home to the admin controller, with the action home.

Default Values

You can also have parameters with default, or static, values.

/foo = bar( id:1 )

This route will always pass a parameter called id of value 1.

The Helper

You are free to instantiate and set up all the objects manually if you want, but the easiest way to do it is through the helper class provided (BoxUK\Routing) by supplying a configuration object. This is used in all the examples.

The Router

The router forms the input part of the system. You instantiate the router using the configured helper, then pass it the requested URL along with a request object to populate with the data extracted from the matched route.

<?php
$req = new BoxUK\Routing\Input\StandardRequest();
$url = '/some/url';

$config = new BoxUK\Routing\Config;
$config->setRoutesFile( '/path/to/routes.txt' );

$routing = new BoxUK\Routing( $config );

$router = $routing->getRouter();
$router->process( $req, $url )

When the process method has completed the request object will contain the information from the route (eg. controller = 'foo')

The example above uses a default request object provided with this library, but you will most likely want to provide your own if you already have a request object abstraction in your application (just implement BoxUK\Routing\Input\Request)

The Filter

The output filter allows us to transform our output using the routing information provided in our routes file. This is done dynamically so the URLs in your output should be the raw versions pointing to your front controller script.

<?php
$html = '<a href="server.php?controller=cars&action=show&brand=ford">Show Ford</a>';

$filter = $routing->getFilter();
$filter->process( $html );

Given the route /cars/:word = cars:show( brand ), the $html variable will be transformed to...

<a href="/cars/ford">Show Ford</a>

This provides a flexible, unobtrusive way to handle generating your clean URLs.

Forms

Forms actions can also be transformed by using hidden input fields to specify your routing parameters.

<form action="server.php">
    <input type="hidden" name="controller" value="cars" />
    <input type="hidden" name="action" value="show" />
    etc...
</form>

The Rewriter

Internally, the output filter uses a rewriting object to transform raw URLs into clean URLs. We can fetch this from the helper or instantiate it ourselves to use it alone. This will be handy if you would just like to rewrite URLs individually (when redirecting the user for example).

Unit Tests

The library is fully unit tested. To run these tests just use phing or phpunit...

phing test
# or
phpunit tests/php

boxuk-routing's Issues

Custom types not available in Request

Custom types are not available as parameters in the updated Request object after a route has been matched and processed.