PHPackages wilaak/radix-router - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [HTTP & Networking](/categories/http) 4. / 5. wilaak/radix-router ActiveLibrary[HTTP & Networking](/categories/http) wilaak/radix-router =================== High-performance radix tree based HTTP request router v3.6.3(1mo ago)612.8k↓86.8%24WTFPLPHPPHP >=8.0CI passing Since Jul 12Pushed 1mo agoCompare [ Source](https://github.com/wilaak/radix-router)[ Packagist](https://packagist.org/packages/wilaak/radix-router)[ Docs](https://github.com/wilaak/radix-router)[ RSS](/packages/wilaak-radix-router/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (10)Dependencies (3)Versions (24)Used By (4) [![RadixRouter](./assets/radx.svg)](./assets/radx.svg) ====================================================== [](#) [![License](https://camo.githubusercontent.com/9320187555fc8804eba9ff702577334f29b1392b81ba4a8890827efcfa4b05a0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f77696c61616b2f72616469782d726f757465722e7376673f7374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/9320187555fc8804eba9ff702577334f29b1392b81ba4a8890827efcfa4b05a0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f77696c61616b2f72616469782d726f757465722e7376673f7374796c653d666c61742d737175617265)[![Downloads](https://camo.githubusercontent.com/d1c5fc55dc5756bd15dcce23131bf63de8ade78652446a742362b8650724f304/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f77696c61616b2f72616469782d726f757465722e7376673f7374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/d1c5fc55dc5756bd15dcce23131bf63de8ade78652446a742362b8650724f304/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f77696c61616b2f72616469782d726f757465722e7376673f7374796c653d666c61742d737175617265) Note As of v3.6.0 RadixRouter is seen as feature complete. No major API changes are planned; only maintenance and bug fixes will be provided. RadixRouter (or RadXRouter) is a lightweight HTTP routing library for PHP focused on providing the essentials while being fast and small. It makes an excellent choice for simple applications or as the foundation for building your own custom more featureful router (see third-party [integrations](#integrations)). It features fast $O(k)$ dynamic route matching ($k$ = segments in path), path parameters (optional, wildcard; one per segment), simple API for listing routes/methods (for OPTIONS support), 405 method not allowed handling and it's all in a package weighing in at only 378 lines of code with no external dependencies. RadixRouter consistently ranks as being one of the fastest (if not *the* fastest) PHP routers out there. To see how this router compares to other implementations in routing performance see the [benchmarks](#benchmarks) section. Install ------- [](#install) ``` composer require wilaak/radix-router ``` Requires PHP 8.0 or newer. Usage ----- [](#usage) Below is an example to get you started using the PHP SAPI. ``` $router = new Wilaak\Http\RadixRouter(); $router->add('GET', '/:name?', function ($name = 'World') { echo "Hello, {$name}!"; }); $method = $_SERVER['REQUEST_METHOD']; $path = rawurldecode(strtok($_SERVER['REQUEST_URI'], '?')); $result = $router->lookup($method, $path); switch ($result['code']) { case 200: $result['handler'](...$result['params']); break; case 404: http_response_code(404); echo '404 Not Found'; break; case 405: $allowedMethods = $result['allowed_methods']; header('Allow: ' . implode(',', $allowedMethods)); http_response_code(405); echo '405 Method Not Allowed'; break; } ``` Route Configuration ------------------- [](#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. Just remember: if you plan to use [route caching](#route-caching), your handlers must be serializable. The router does not support regex patterns and it's recommended that you do this validation in your handlers. Regular expressions allow for highly flexible matching which can make route resolution order less predictable. If you absolutely need this you can use a more suitable router of which there are plenty (e.g., [FastRoute](https://github.com/nikic/FastRoute)). ``` // Simple GET route $router->add('GET', '/about', 'AboutController@show'); // Multiple HTTP methods $router->add(['GET', 'POST'], '/contact', 'ContactController@submit'); // Any allowed HTTP method $router->add($router->allowedMethods, '/maintenance', 'MaintenanceController@handle'); // Special fallback HTTP method (allowed or not) $router->add('*', '/maintenance', 'MaintenanceController@handle'); ``` ### Path Parameters [](#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 [](#required-parameters) Matches only when the segment is present and not empty. ``` // Required parameter $router->add('GET', '/users/:id', 'UserController@profile'); // Example requests: // /users -> no match // /users/123 -> ['id' => '123'] // You can have as many as you want, but keep it sane $router->add('GET', '/users/:id/orders/:order_id', 'OrderController@details'); ``` #### Optional Parameters [](#optional-parameters) These match whether the segment is present or not. 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. ``` // Single optional parameter $router->add('GET', '/blog/:slug?', 'BlogController@view'); // Example requests: // /blog -> [] (no parameters) // /blog/hello -> ['slug' => 'hello'] // Chained optional parameters $router->add('GET', '/archive/:year?/:month?', 'ArchiveController@list'); // Example requests: // /archive -> [] (no parameters) // /archive/2022 -> ['year' => '2022'] // /archive/2022/12 -> ['year' => '2022', 'month' => '12'] // Mixing required and optional parameters $router->add('GET', '/shop/:category/:item?', 'ShopController@view'); // Example requests: // /shop/books -> ['category' => 'books'] // /shop/books/novel -> ['category' => 'books', 'item' => 'novel'] ``` #### Wildcard Parameters [](#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. Note that the router trims trailing slashes from incoming paths, so you won’t see empty segments at the end of your results. 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. ``` // Required wildcard parameter (one or more segments) $router->add('GET', '/assets/:resource+', 'AssetController@show'); // Example requests: // /assets -> no match // /assets/logo.png -> ['resource' => 'logo.png'] // /assets/img/banner.jpg -> ['resource' => 'img/banner.jpg'] // Optional wildcard parameter (zero or more segments) $router->add('GET', '/downloads/:file*', 'DownloadController@show'); // Example requests: // /downloads -> ['file' => ''] (empty string) // /downloads/report.pdf -> ['file' => 'report.pdf'] // /downloads/docs/guide.md -> ['file' => 'docs/guide.md'] ``` ### Route Listing [](#route-listing) Use `list()` to retrieve all registered routes and their associated handlers. Optionally pass a request path to filter results to routes matching that path. ``` // Print a formatted table of all routes function print_routes_table($routes) { printf("%-8s %-24s %s\n", 'METHOD', 'PATTERN', 'HANDLER'); printf("%s\n", str_repeat('-', 60)); foreach ($routes as $route) { printf("%-8s %-24s %s\n", $route['method'], $route['pattern'], $route['handler']); } printf("%s\n", str_repeat('-', 60)); } // List all routes print_routes_table($router->list()); // List routes for a specific path print_routes_table($router->list('/contact')); ``` Example Output: ``` METHOD PATTERN HANDLER ------------------------------------------------------------ GET /about AboutController@show GET /archive/:year?/:month? ArchiveController@list GET /assets/:resource+ AssetController@show GET /blog/:slug? BlogController@view GET /contact ContactController@submit POST /contact ContactController@submit GET /downloads/:file* DownloadController@show * /maintenance MaintenanceController@handle GET /users/:id UserController@profile METHOD PATTERN HANDLER ------------------------------------------------------------ GET /contact ContactController@submit POST /contact ContactController@submit ``` ### Listing Allowed Methods [](#listing-allowed-methods) Use `methods()` to retrieve the allowed HTTP methods for a given request path. Note If the fallback method (`*`) is registered for that path, `methods()` returns `$router->allowedMethods`. ``` if ($method === 'OPTIONS') { $allowedMethods = $router->methods($path); header('Allow: ' . implode(', ', $allowedMethods)); } ``` ### Route Caching [](#route-caching) Route caching can be beneficial for classic 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, significantly reducing script startup time by eliminating the need to recompile route definitions on each request. An additional benefit of storing routes in PHP files is that 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 or FrankenPHP in worker mode, 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, which you may also notice in the [benchmark](#benchmarks) results. Note You must only provide serializable handlers such as strings or arrays. Closures and anonymous functions are not supported for route caching. Warning 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. ``` $cache = __DIR__ . '/radixrouter.cache.php'; if (!file_exists($cache)) { $router->add('GET', '/', 'handler'); // ...add more routes $routes = [ 'tree' => $router->tree, 'static' => $router->static, ]; file_put_contents($cache, '