Download the PHP package chani/wajha without Composer

Safi/Wajha Router

A fast, lightweight HTTP router for PHP 8.3+ combining $O(1)$ static hash map lookups with first-character bucketed PCRE2 regex evaluation for dynamic routes.

Technical Features

• O(1) Static Fast-Path: Direct 2D array lookup ($staticRoutes[$method][$uri]) bypassing the PCRE2 engine entirely.
• First-Character Path Bucketing: Dynamic routes are partitioned by URI prefix to avoid evaluating unrelated regex chunks.
• PCRE2 Positional Branch-Reset Matching: Dynamic paths are evaluated in 30-route chunks using PCRE2 branch-reset groups (?|...) with positional capture extraction ($matches[1]) and (*MARK:N) identifiers to eliminate C-level named subpattern lookup overhead.
• Zero-Stack Dispatching: Inlined execution path without VM function frame call stack overhead during dispatching.
• Compile-Time Transformations: Type shorthands, enum constraints, and route groups compile down to raw PCRE2 patterns with no runtime overhead.

Requirements

• PHP 8.3 or higher
• pcre2 extension enabled

Installation

Usage Examples

1. Basic Setup & Dispatching

Routes are registered via WajhaCompiler and evaluated via WajhaDispatcher.

2. Type Shorthands

Pattern aliases expand during compilation into native PCRE2 patterns.

Supported shorthands:

• {var:int} $\rightarrow$ \d+
• {var:uuid} $\rightarrow$ [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}
• {var:slug} $\rightarrow$ [a-z0-9-]+
• {var:alpha} $\rightarrow$ [a-zA-Z]+

3. Backed Enum Matching

String-backed PHP 8.1+ Enums translate into regex alternation groups (case1|case2) at compile time.

4. Route Grouping

Prefix concatenation occurs strictly during compilation.

5. Optional Path Segments

Optional segments marked with square brackets ([/...]) expand recursively at compile time.

6. Reverse Routing (URL Generation)

Route names can be attached during definition via the name argument. URL synthesis is handled by the standalone WajhaUrlGenerator class, keeping the inbound dispatcher completely unencumbered by reverse-mapping overhead.

7. Twig Template Integration

To expose reverse URL generation within Twig templates, register a custom path() function with your Twig environment:

You can then generate URLs directly inside your .twig files:

Benchmarks

Evaluated on PHP 8.5 over 100,000 request dispatch iterations against a 1,000 route dataset (70% valid routes, 15% method mismatches, 15% 404 targets):

For detailed insights into the architecture, Zend VM micro-benchmarks, and real-world scenario trade-offs, see the write-up: Writing a PHP 8.5 Router Faster Than FastRoute

Running Benchmarks & Tests

License

MIT License. See LICENSE.md for details.