Download the PHP package wilaak/radix-router without Composer

RadixRouter

Minimal high-performance radix tree based HTTP request router for PHP (see benchmarks)

Overview

• High-performance O(k) dynamic route matching, where k is the number of segments in the path.
• Supports parameters, including wildcard and optional segments for flexible route definitions.
• Static routes are stored in a hash map providing fast minimal allocation lookups for exact matches.

How does it work?

The router splits the path into segments and walks the tree, matching each segment in order. Because the tree only branches where routes differ, the router can quickly skip irrelevant routes and find the correct handler with minimal comparisons.

Install

Install with composer:

composer require wilaak/radix-router

Or simply include it in your project:

Requires PHP 8.0 or newer. (PHP 8.3 for tests)

Usage Example

Here's a basic usage example using the typical SAPI web environment:

Registering Routes

Routes are registered using the add() method. You can assign any value as the handler. The order of route matching is: static > parameter > wildcard.

Note: Paths are normalized by removing trailing slashes. For example, both /about and /about/ will be treated as the same route.

Below is an example showing the different ways to define routes:

Note on HEAD Requests

According to the HTTP specification, any route that handles a GET request should also support HEAD requests. RadixRouter does not automatically add this behavior. If you are running outside a standard web server environment (such as in a custom server), ensure that your GET routes also respond appropriately to HEAD requests. Responses to HEAD requests must not include a message body.

How to Cache Routes

You can most likely ignore this section. Most SAPI environments are generally limited by I/O due to their synchronous nature, so the time spent reconstructing routes is gonna be minimal compared to the overall I/O wait time.

Note: Anonymous functions (closures) are not supported for route caching because they cannot be serialized. When caching routes, only use handlers that can be safely represented as strings, arrays, or serializable objects.

Note: When implementing route caching, care should be taken to avoid race conditions when rebuilding the cache file. Ensure that the cache is written atomically so that each request can always fully load a valid cache file without errors or partial data.

Here is a simple cache implementation:

By storing your routes in a PHP file, you let PHP’s OPcache handle the heavy lifting, making startup times nearly instantaneous.

Benchmarks

Single-threaded benchmark (Xeon E-2136, PHP 8.4.8 cli OPcache enabled):

Simple App (33 Routes)

Avatax API (256 Routes)

Bitbucket API (178 Routes)

License

This library is licensed under the WTFPL-2.0 license. Do whatever you want with it.