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())

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

Generate performance

Build and memory

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.