Download the PHP package wilaak/radix-router without Composer

A very simple radix tree based HTTP router for PHP. Use it directly, or as a base for your own router (see integrations).

• Path parameters: optional and wildcard (one per segment)
• API for listing routes/methods (useful for OPTIONS)
• Automatic 405 Method Not Allowed handling
• Zero dependencies and only 377 lines of code

See benchmarks for how it compares to others.

Install

Requires PHP 8.0 or newer.

Usage

Below is an example to get you started using the PHP SAPI.

Route Configuration

Routes are matched in a predictable order, always favoring the most specific pattern. Handlers can be any value you choose. In these examples, we use strings for simplicity, but you’re free to use arrays with extra details like middleware or other metadata.

If you plan to cache your routes your handlers must be exportable (see route caching). This router does not support regex patterns and it's recommended that you handle this logic in your handlers instead.

Path Parameters

Path parameters let you capture segments of the request path by specifying named placeholders in your route pattern. The router extracts these values and returns them as a map, with each value bound to its corresponding parameter name.

Required Parameters

Matches only when the segment is present and not empty.

Optional Parameters

These match regardless of whether the segment is present, and are only allowed at the end of the path.

[!TIP]
Use sparingly! In most cases you’re probably better off using query parameters instead of restricting yourself to a single filtering option in the path.

Wildcard Parameters

Also known as catch-all, splat, greedy, rest, or path remainder parameters; wildcards capture everything after their position in the path, including slashes. Because of this they must be used as the final segment.

[!CAUTION]
Never use captured path segments directly in filesystem operations. Path traversal attacks can expose sensitive files or directories. Use functions like realpath() and restrict access to a safe base directory.

Route Listing

Retrieve registered routes and their associated handlers. Optionally pass a request path to filter results to routes matching that path.

Example Output:

Allowed Methods

Retrieve the allowed HTTP methods for a given request path.

Route Caching

Route caching improves performance for traditional PHP deployments where scripts are reloaded on every request. In these environments, caching routes in a PHP file allows OPcache to keep them in shared memory, reducing script startup time by eliminating the need to recompile route definitions on each request.

PHP’s engine automatically interns identical string literals at compile time. This means that when multiple routes share the same pattern, method or handler name, only a single instance of each unique string is stored in memory, reducing memory usage and access latency.

For persistent environments such as Swoole, where the application and its routes remain in memory between requests, route caching is generally unnecessary. However you may still gain some performance uplift from the aforementioned interning.

Custom HTTP methods

You can add custom HTTP methods to the router, just make sure the method names are uppercase.

If you want a route to match any HTTP method (including custom ones), use the fallback method:

Trailing Slashes in URLs

This router does not perform any automatic trailing slash redirects. Trailing slashes at the end of the request path are automatically trimmed before route matching, so both /about and /about/ will match the same route.

When a route is successfully matched, the lookup method returns the canonical pattern of the matched route, allowing you to implement your own logic to enforce a specific URL format or redirect as needed.

Important note on HEAD requests

By specification, servers must support the HEAD method for any GET resource, but without returning an entity body. In this router HEAD requests will automatically fall back to a GET route if you haven’t defined a specific HEAD route.

If you’re using PHP’s built-in web SAPI, the entity body is removed for HEAD responses automatically. If you’re implementing a custom server outside the web SAPI be sure not to send any entity body in response to HEAD requests.

Integrations

If this router is a bit too minimalistic, you might try one of the following more high-level integrations. These are third-party so evaluate and use them at your own discretion.

Benchmarks

Each path gets 1-3 HTTP methods, lookups follow a Zipf-like distribution, so a few hot routes dominate traffic.

• PHP 8.5.4
• AMD Ryzen AI 7 PRO 350 w/ Radeon 860M
• Seed: 42

License

This library is licensed under the MIT License.