pathforge/icrouter

Tree-based URL router for PHP. Efficient matching via node tree instead of regex iteration.

dev-master 2026-04-06 15:16 UTC

Requires (Dev)

• phpunit/phpunit: ^9.0

MIT

• route
• routing
• tree
• url
• router

README

A tree-based URL router for PHP. Instead of iterating over a list of regular expressions, PathForge Router builds a matching tree from registered routes, providing efficient O(depth) lookups.

Requires PHP 5.5 or later.

Installation

composer require pathforge/icrouter

Usage

Setup

use PathForge\icRouter\Router;
use PathForge\icRouter\Route;
use PathForge\icRouter\Interfaces\DefImpl\DefaultNodeBuilder;

$router = new Router(new DefaultNodeBuilder());

Define routes

$router->setRoutes([
    new Route('simple', '/simple',
              array('module' => 'simple')),
    new Route('simple_param', '/param/:a',
              array('module' => 'simple_param', 'a' => 10),
              array('a' => '\d+')),
    new Route('two_params', '/param/hello/:a/some/:b',
              array('module' => 'two_params', 'a' => 10, 'onemore' => 'time')),
    new Route('two_params_any', '/home/hello/:a/:b/*',
              array('module' => 'two_params_any', 'a' => 10, 'b' => '10'),
              array('b' => '[01]+')),
    new Route('complex_param', '/complex/id_:id',
              array('module' => 'complex_param'),
              array('id' => '\d+')),
    new Route('home', '/*',
              array('module' => 'home')),
]);

$router->build();

Match a URL

$result = $router->match('/param/20');
// Returns: array('module' => 'simple_param', 'a' => '20')

$result = $router->match('/nonexistent');
// Returns: false

match() returns an associative array of parameters on success, or false if no route matches.

Generate a URL

$result = $router->generate('two_params', array('b' => 'aabb'));
// Returns: '/param/hello/10/some/aabb'

The first argument is the route name, the second is an array of parameters. Missing parameters are filled from defaults.

Route constructor

new Route($name, $pattern, $defaults = array(), $parameters = array())

Argument	Description
$name	Unique route name, used for URL generation
$pattern	URL pattern with optional parameters and wildcard
$defaults	Default values for parameters (key-value pairs)
$parameters	Regex constraints for named parameters

Pattern syntax

• Static segments match literally: /account/list
• Named parameters are prefixed with : and match a single segment: /account/:id
• Named parameters can be embedded in a segment: /account/id_:id
• A trailing * captures remaining segments as key-value pairs: /account/:id/*
• Parameter names must match [A-Za-z0-9]+
• Only one named parameter is allowed per segment

Parameter constraints

Regex patterns (without delimiters) can be specified per parameter:

array('id' => '\d+')            // id must be an integer
array('type' => 'car|boat|plane') // type must be one of these values

Route ordering

Routes are matched in registration order. When multiple routes could match a URL, the first registered route wins. Place more specific routes before general ones:

$router->setRoutes([
    new Route('specific', '/param/:a', ...),  // checked first
    new Route('catchall', '/*', ...),          // fallback
]);

HTTP methods

icRouter matches URL paths only and does not handle HTTP methods (GET, POST, PUT, DELETE, etc.). Method dispatch can be handled by your application code, for example by including the method in the route defaults:

$router->setRoutes([
    new Route('create_user', '/user/create',
              array('module' => 'user', 'action' => 'create', 'method' => 'POST')),
]);

$result = $router->match('/user/create');
if ($result && $result['method'] !== $_SERVER['REQUEST_METHOD']) {
    // return 405 Method Not Allowed
}

Performance tip

$router->build() constructs the matching tree and is relatively expensive. In production, cache the built router instance (e.g. via serialize(), APC, or similar) to avoid rebuilding on every request.

Unit testing

vendor/bin/phpunit test/RouterTest.php

Benchmarks

Run benchmarks:

php test/benchmark.php

Results on PHP 8.1 (100,000 iterations per test):

Match performance

Scenario	Small router (7 routes)	Large router (500+ routes)
Static route	~695K ops/sec	~386K ops/sec
Param with regex	~324K ops/sec	~242K ops/sec
Two params, deep path	~175K ops/sec	~167K ops/sec
Wildcard with key/value pairs	~170K ops/sec	~242K ops/sec
Catchall (/*)	~466K ops/sec	~599K ops/sec
No match	~313K ops/sec	—

Generate performance

Scenario	Small router	Large router
Static route	~1.3M ops/sec	—
Single param	~468K ops/sec	~408K ops/sec
Two params	~516K ops/sec	~244K ops/sec
Wildcard with params	~317K ops/sec	~592K ops/sec

Build and memory

Metric	Small (7 routes)	Large (500+ routes)
Build speed	~21K ops/sec	~327 ops/sec
Memory footprint	—	~744 KB

The tree structure scales well: matching with 500+ routes is only 30–50% slower than with 7 routes, since lookup depends on tree depth rather than total route count. At ~170K+ ops/sec in the worst case, routing takes roughly 6 microseconds per request.