library route66

leeoniya/route66

PHP micro-router

Route66.php

PHP micro-router (MIT Licensed), _(*1)

• Concise, simple syntax wrapping a full feature set
• Easy install; Composer or single file include (~200 SLOC)
• Low routing overhead (< 1ms)*

Route66 was written to add some features to the minimalist Macaw router without bloating it., _(*2)

Nginx config example

server {
    index index.html index.htm index.php;

    location / {
        try_files $uri $uri/ /index.php?/$uri;
    }

    location ~ \.php$ {
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

Install (require or Composer)

require 'Route66.php';

https://packagist.org/packages/leeoniya/route66, _(*3)

{
    "require": {
        "leeoniya/route66": "dev-master"
    }
}

Basic example

// front controller (index.php)
require 'Route66.php';

use Route66 as R;

R::get('/', function() {
    echo 'Hello world!';
});

R::dispatch();

HTTP methods

// any HTTP method can be bound via static invocation using its name
R::post('/topics', function() {});

// multiple methods
R::match('post|put', '/comment', function() {});

// equivalent to R::match('get|post|put|patch|delete|head|options',..)
R::any('/', function() {};)

Named params & validation

// basic param (all characters except '/')
R::get('/posts/@id',       function($id) {});

// param validated by regex alias
R::get('/posts/@id:alpha', function($id) {});

// aliases and regexs can be broken out for readability
R::get('/posts/@id',       function($id) {}, ['id' => ':alpha']);
R::get('/posts/@id',       function($id) {}, ['id' => '\w{12}']);

// define a custom alias
R::alias(':date', '[0-9]{4}-[0-9]{2}-[0-9]{2}');

Optional segments & params

// optional params with defaults (set in handler)
R::get('/posts(/@year(/@month(/@day)))', function($year = 2015, $month = 6, $day = 15) {});

// regex alias without a param (non-capturing)
R::get('/posts(/:slug)', function() {});

// optional trailing slash (though rtrim-ing it from REQUEST_URI before dispatch is faster)
R::get('/blog/?', function() {});

Un-named params

// un-named params via regex capture groups
R::get('/posts/(\w{12})', function($id) {});

Route prefixing (base path)

R::base('/blog');
R::get('/posts', function() {});    // maps to /blog/posts

R::base('/admin');
R::get('/login', function() {});    // maps to /admin/login

Before pre-filter (fall-through)

// before all /admin* routes
R::get('/admin(/:all)', function() {
    // verify valid session, etc...
    return R::NOHALT;       // fall through to additional routes
});

R::get('/admin/dashboard', function() {
    // show dashboard...
});

Custom catch-all (no route found)

R::nomatch(function($meth, $uri) {
    header($_SERVER["SERVER_PROTOCOL"] . " 404 Not Found");
    exit('404 Not Found.');
});

Custom dispatch (e.g. internal redirects)

R::dispatch('get', '/blog');

Route caching

// example of storing compiled routes in session
session_start();

if ($routes = @$_SESSION['routes'])
    R::import($routes);

// define all routes here

R::dispatch();

if (!isset($_SESSION['routes']))
    $_SESSION['routes'] = R::export();

Named routes & reverse routing

// un-named
R::get('/users/@id', function($id) {}, ['id'=>':alpha']);

// named (the trailing 2 args can be passed in any order. all below are equivalent.)
R::get('/users/@id', function($id) {}, 'named1');
R::get('/users/@id', function($id) {}, ['id'=>':alpha'], 'named1');
R::get('/users/@id', function($id) {}, 'named1', ['id'=>':alpha']);

// dispatch a named route
R::dispatch('get', 'named1', ['id' => 'abc123']);

Util methods

R::is_ajax();
R::is_https();
R::redirect($location, $code = 301);

New features (relative to Macaw)

• Named params (e.g. @user:alpha)
• Optional route segments and params, param defaults
• Route-group prefixing
• Param regex & aliases can be broken out for readability
• Short defs for multi-method routes
• Named routes and reverse routing, custom dispatch
• Per-route fall-through control (Macaw has only global)
• Route compilation cache, import/export
• Utility methods for is_ajax, is_https and redirect
• Modified and added regex aliases

Other PHP routers

• Macaw - https://github.com/NoahBuscher/Macaw
• Phroute - https://github.com/mrjgreen/phroute
• Klein - https://github.com/chriso/klein.php
• FastRoute - https://github.com/nikic/FastRoute
• Pux - https://github.com/c9s/Pux
• AltoRouter - https://github.com/dannyvankooten/AltoRouter
• Aura - https://github.com/auraphp/Aura.Router
• mu - https://github.com/lastguest/mu

* As with any router, speed will depend on: route quantity & complexity, numbers of params, whether caching is used, server hardware, PHP version, opcode caching., _(*4)