Brickhouse Routing

This library is a regex-based routing mechanism for PHP applications. It is heavily based on nikic' FastRoute project.

Installation

To install the library, you need to require the package via composer:

composer require brickhouse/routing

Usage

To add routes to the dispatcher, you can create a RouteCollector like so:

use Brickhouse\Routing;

$collector = new RouteCollector();
$collector->addRoute('GET', '/', fn() => 'Hello World!');
$collector->addRoute('GET', '/posts/:id', fn() => render_post());
$collector->addRoute('POST', '/posts', fn() => create_post());

The collector can then be passed to a dispatcher, which can match the routes:

$dispatcher = new Dispatcher($collector);

$route = $dispatcher->dispatch('GET', '/');

When a route is matched, $route will be an array of the route handler, as well as the parameters in the route. If no route was matched, $route is null.

Defining routes

Required parameters

Parameters can be defined by adding a colon to the beginning of a route segment, like so:

$collector->addRoute('GET', '/posts/:id', '...');

When the route is matched, the captured parameter value will be returned in the dispatched route:

[$handler, $parameters] = $dispatcher->dispatch('GET', '/posts/routing');

echo $parameters;

// ['id' => 'routing']

You may define as many parameters in a single route as required:

$collector->addRoute('GET', '/users/:user/posts/:post', '...');

Route parameters names consist of alphanumeric ([A-Za-z0-9]) characters and underscores (_).

Optional parameters

Parameters can also be marked as optional, allowing the route to be dispatched by multiple routes. Optional parameters are defined by placing a ?-mark after the colon:

$collector->addRoute('GET', '/user/:?id', '...');

When the parameter is omitted from the matched, it will be set as null in the matched route:

[$handler, $parameters] = $dispatcher->dispatch('GET', '/user');

echo $parameters;

// ['id' => null]

Catch-all parameters

Parameters can be extended to catch all subsequent segments in the path. Catch-all parameters are defined by replacing the colon with an asterisk (*):

$collector->addRoute('GET', '/posts/*slug', '...');

When using a catch-all parameter, all subsequent segments are returned as a single string.

$dispatcher->dispatch('GET', '/posts/a');
// $parameters => ['slug' => 'a']

$dispatcher->dispatch('GET', '/posts/a/b');
// $parameters => ['slug' => 'a/b']

$dispatcher->dispatch('GET', '/posts/a/b/c');
// $parameters => ['slug' => 'a/b/c']

Catch-all parameters also require a value to be given before matching:

$route = $dispatcher->dispatch('GET', '/posts');
// $route => null

To allow the catch-all to match routes without giving the parameter, you can mark it as optional:

$collector->addRoute('GET', '/posts/*?slug', '...');

// ...

$dispatcher->dispatch('GET', '/posts');
// $parameters => ['slug' => null]

$dispatcher->dispatch('GET', '/posts/a');
// $parameters => ['slug' => 'a']

Custom pattern constraints

You may write your own constraints for route parameters using regular expressions. Constraints are defined per-argument and can be written like so:

$collector->addRoute('GET', '/user/:user_id', '...', ['user_id' => '\d+']);

This limits which values can be matched with the route. If the route doesn't match, it'll continue looking for one that does.

$route = $dispatcher->dispatch('GET', '/user/423');
// $route => ['...', ['user_id' => '423']]

$route = $dispatcher->dispatch('GET', '/user/admin');
// $route => null

Performance

Performance is measured using PHPBench, running the benchmarks in bench.

All setups are different, but this bench was run on a Mac Mini M4 (16GB, Sequoia 15.3), with PHP 8.4.1 where both XDebug and OPCache disabled.

benchmark	subject	mean	revs	total
MicroDynamicBenchmark	benchDispatchFirst	0.652μs	20000	0.013s
MicroDynamicBenchmark	benchDispatchLast	6.322μs	20000	0.126s
MicroDynamicBenchmark	benchDispatchUnknown	5.530μs	20000	0.111s
MicroStaticBenchmark	benchDispatchFirst	0.307μs	30000	0.009s
MicroStaticBenchmark	benchDispatchLast	4.394μs	30000	0.132s
MicroStaticBenchmark	benchDispatchUnknown	4.724μs	30000	0.142s

License

Brickhouse Routing is open-sourced software licensed under the MIT license.