Download the PHP package wilaak/radix-router without Composer

RadixRouter

Simple radix tree based HTTP request router for PHP. Lightweight and high-performance (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 PHP-FPM (FastCGI) 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.

Note: Trailing slashes are ignored. For example, both /about and /about/ are treated as the same route.

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

How to Cache Routes

Rebuilding the route tree on every request or application startup can slow down performance.

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.

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.

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. Do whatever you want with it.