ashpants / altorouter

PHP5.3+ Routing Class. Lightweight yet extremely flexible. Supports REST, dynamic and reversed routing.

AltoRouter

AltoRouter is a small but powerful routing class for PHP 5.3+, heavily inspired by klein.php.

• Dynamic routing with named parameters
• Reversed routing
• Flexible regular expression routing (inspired by Sinatra)
• Custom regexes

Getting started

1. PHP 5.3.x is required
2. Install AltoRouter using Composer or manually
3. Setup URL rewriting so that all requests are handled by index.php
4. Create an instance of AltoRouter, map your routes and match a request.
5. Have a look at the basic example in the examples directory for a better understanding on how to use AltoRouter.

Routing

$router = new AltoRouter();
$router->setBasePath('/AltoRouter'); // (optional) the subdir AltoRouter lives in

// mapping routes
$router->map('GET|POST','/', 'home#index', 'home');
$router->map('GET','/users', array('c' => 'UserController', 'a' => 'ListAction'));
$router->map('GET','/users/[i:id]', 'users#show', 'users_show');
$router->map('POST','/users/[i:id]/[delete|update:action]', 'usersController#doAction', 'users_do');

// reversed routing
$router->generate('users_show', array('id' => 5));

You can use the following limits on your named parameters. AltoRouter will create the correct regexes for you.

*                    // Match all request URIs
[i]                  // Match an integer
[i:id]               // Match an integer as 'id'
[a:action]           // Match alphanumeric characters as 'action'
[h:key]              // Match hexadecimal characters as 'key'
[:action]            // Match anything up to the next / or end of the URI as 'action'
[create|edit:action] // Match either 'create' or 'edit' as 'action'
[*]                  // Catch all (lazy, stops at the next trailing slash)
[*:trailing]         // Catch all as 'trailing' (lazy)
[**:trailing]        // Catch all (possessive - will match the rest of the URI)
.[:format]?          // Match an optional parameter 'format' - a / or . before the block is also optional

Some more complicated examples

@/(?[A-Za-z]{2}_[A-Za-z]{2})$ // custom regex, matches language codes like "en_us" etc.
/posts/[*:title][i:id]        // Matches "/posts/this-is-a-title-123"
/output.[xml|json:format]?    // Matches "/output", "output.xml", "output.json"
/[:controller]?/[:action]?    // Matches the typical /controller/action format

The character before the colon (the 'match type') is a shortcut for one of the following regular expressions

'i'  => '[0-9]++'
'a'  => '[0-9A-Za-z]++'
'h'  => '[0-9A-Fa-f]++'
'*'  => '.+?'
'**' => '.++'
''   => '[^/\.]++'

New match types can be added using the addMatchTypes() method

$router->addMatchTypes(array('cId' => '[a-zA-Z]{2}[0-9](?:_[0-9]++)?'));

Matching

Simply call the match() method like this :

// perform a match against the current request url
$match = $router->match();

// perform a match against a given url
$match = $router->match($url);

Structure

Match return an associative array containing :

• target : the value of the third argument of the map() call
• params : if you have params in your match pattern, an associative array with param name as key
• name : the name of the matched route

Example

• Map : 'GET', '/user/[i:id]/', array('c' => 'UserController', 'a' => 'Profile'), 'userProfile'
• Url : /users/group/list/123/

will give :

Array
(
    [target] => Array
        (
            [c] => UserController
            [a] => Profile
        )

    [params] => Array
        (
            [id] => 123
        )

    [name] => userProfile
)

Contributors

• Danny van Kooten
• Koen Punt
• John Long
• Niahoo Osef

License

(MIT License)

Copyright (c) 2012-2013 Danny van Kooten [email protected]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.