Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/nikic/FastRoute

Fast request router for PHP
https://github.com/nikic/FastRoute

Last synced: about 1 month ago
JSON representation

Fast request router for PHP

Awesome Lists containing this project

README 

        
FastRoute - Fast request router for PHP

=======================================



[![Build Status](https://img.shields.io/github/actions/workflow/status/nikic/FastRoute/phpunit.yml?branch=master&style=flat-square)](https://github.com/nikic/FastRoute/actions?query=workflow%3A%22PHPUnit%20Tests%22+branch%3Amaster)



This library provides a fast implementation of a regular expression based router. [Blog post explaining how the

implementation works and why it is fast.][blog_post]



Install

-------



To install with composer:



```sh

composer require nikic/fast-route

```



Requires PHP 8.1 or newer.



Usage

-----



Here's a basic usage example:



```php

addRoute('GET', '/users', 'get_all_users_handler');

    // {id} must be a number (\d+)

    $r->addRoute('GET', '/user/{id:\d+}', 'get_user_handler');

    // The /{title} suffix is optional

    $r->addRoute('GET', '/articles/{id:\d+}[/{title}]', 'get_article_handler');

});



// Fetch method and URI from somewhere

$httpMethod = $_SERVER['REQUEST_METHOD'];

$uri = $_SERVER['REQUEST_URI'];



// Strip query string (?foo=bar) and decode URI

if (false !== $pos = strpos($uri, '?')) {

    $uri = substr($uri, 0, $pos);

}

$uri = rawurldecode($uri);



$routeInfo = $dispatcher->dispatch($httpMethod, $uri);

switch ($routeInfo[0]) {

    case FastRoute\Dispatcher::NOT_FOUND:

        // ... 404 Not Found

        break;

    case FastRoute\Dispatcher::METHOD_NOT_ALLOWED:

        $allowedMethods = $routeInfo[1];

        // ... 405 Method Not Allowed

        break;

    case FastRoute\Dispatcher::FOUND:

        $handler = $routeInfo[1];

        $vars = $routeInfo[2];

        // ... call $handler with $vars

        break;

}

```



### Defining routes



The routes are defined by calling the `FastRoute\simpleDispatcher()` function, which accepts

a callable taking a `FastRoute\ConfigureRoutes` instance. The routes are added by calling

`addRoute()` on the collector instance:



```php

$r->addRoute($method, $routePattern, $handler);

```



The `$method` is an uppercase HTTP method string for which a certain route should match. It

is possible to specify multiple valid methods using an array:



```php

// These two calls

$r->addRoute('GET', '/test', 'handler');

$r->addRoute('POST', '/test', 'handler');

// Are equivalent to this one call

$r->addRoute(['GET', 'POST'], '/test', 'handler');

```



By default, the `$routePattern` uses a syntax where `{foo}` specifies a placeholder with name `foo`

and matching the regex `[^/]+`. To adjust the pattern the placeholder matches, you can specify

a custom pattern by writing `{bar:[0-9]+}`. Some examples:



```php

// Matches /user/42, but not /user/xyz

$r->addRoute('GET', '/user/{id:\d+}', 'handler');



// Matches /user/foobar, but not /user/foo/bar

$r->addRoute('GET', '/user/{name}', 'handler');



// Matches /user/foo/bar as well

$r->addRoute('GET', '/user/{name:.+}', 'handler');

```



Custom patterns for route placeholders cannot use capturing groups. For example `{lang:(en|de)}`

is not a valid placeholder, because `()` is a capturing group. Instead you can use either

`{lang:en|de}` or `{lang:(?:en|de)}`.



Furthermore, parts of the route enclosed in `[...]` are considered optional, so that `/foo[bar]`

will match both `/foo` and `/foobar`. Optional parts are only supported in a trailing position,

not in the middle of a route.



```php

// This route

$r->addRoute('GET', '/user/{id:\d+}[/{name}]', 'handler');

// Is equivalent to these two routes

$r->addRoute('GET', '/user/{id:\d+}', 'handler');

$r->addRoute('GET', '/user/{id:\d+}/{name}', 'handler');



// Multiple nested optional parts are possible as well

$r->addRoute('GET', '/user[/{id:\d+}[/{name}]]', 'handler');



// This route is NOT valid, because optional parts can only occur at the end

$r->addRoute('GET', '/user[/{id:\d+}]/{name}', 'handler');

```



The `$handler` parameter does not necessarily have to be a callback, it could also be a controller

class name or any other kind of data you wish to associate with the route. FastRoute only tells you

which handler corresponds to your URI, how you interpret it is up to you.



#### Shortcut methods for common request methods



For the `GET`, `POST`, `PUT`, `PATCH`, `DELETE` and `HEAD` request methods shortcut methods are available. For example:



```php

$r->get('/get-route', 'get_handler');

$r->post('/post-route', 'post_handler');

```



Is equivalent to:



```php

$r->addRoute('GET', '/get-route', 'get_handler');

$r->addRoute('POST', '/post-route', 'post_handler');

```



#### Route Groups



Additionally, you can specify routes inside a group. All routes defined inside a group will have a common prefix.



For example, defining your routes as:



```php

$r->addGroup('/admin', function (FastRoute\ConfigureRoutes $r) {

    $r->addRoute('GET', '/do-something', 'handler');

    $r->addRoute('GET', '/do-another-thing', 'handler');

    $r->addRoute('GET', '/do-something-else', 'handler');

});

```



Will have the same result as:



 ```php

$r->addRoute('GET', '/admin/do-something', 'handler');

$r->addRoute('GET', '/admin/do-another-thing', 'handler');

$r->addRoute('GET', '/admin/do-something-else', 'handler');

 ```



Nested groups are also supported, in which case the prefixes of all the nested groups are combined.



### Caching



The reason `simpleDispatcher` accepts a callback for defining the routes is to allow seamless

caching. By using `cachedDispatcher` instead of `simpleDispatcher` you can cache the generated

routing data and construct the dispatcher from the cached information:



```php

addRoute('GET', '/user/{name}/{id:[0-9]+}', 'handler0');

    $r->addRoute('GET', '/user/{id:[0-9]+}', 'handler1');

    $r->addRoute('GET', '/user/{name}', 'handler2');

}, [

    'cacheKey' => __DIR__ . '/route.cache', /* required */

    // 'cacheFile' => __DIR__ . '/route.cache', /* will still work for v1 compatibility */

    'cacheDisabled' => IS_DEBUG_ENABLED,     /* optional, enabled by default */

    'cacheDriver' => FastRoute\Cache\FileCache::class, /* optional, class name or instance of the cache driver - defaults to file cache */

]);

```



The second parameter to the function is an options array, which can be used to specify the cache

key (e.g. file location when using files for caching), caching driver, among other things.



### Dispatching a URI



A URI is dispatched by calling the `dispatch()` method of the created dispatcher. This method

accepts the HTTP method and a URI. Getting those two bits of information (and normalizing them

appropriately) is your job - this library is not bound to the PHP web SAPIs.



The `dispatch()` method returns an array whose first element contains a status code. It is one

of `Dispatcher::NOT_FOUND`, `Dispatcher::METHOD_NOT_ALLOWED` and `Dispatcher::FOUND`. For the

method not allowed status the second array element contains a list of HTTP methods allowed for

the supplied URI. For example:



    [FastRoute\Dispatcher::METHOD_NOT_ALLOWED, ['GET', 'POST']]



> **NOTE:** The HTTP specification requires that a `405 Method Not Allowed` response include the

`Allow:` header to detail available methods for the requested resource. Applications using FastRoute

should use the second array element to add this header when relaying a 405 response.



For the found status the second array element is the handler that was associated with the route

and the third array element is a dictionary of placeholder names to their values. For example:



    /* Routing against GET /user/nikic/42 */



    [FastRoute\Dispatcher::FOUND, 'handler0', ['name' => 'nikic', 'id' => '42']]



### Overriding the route parser and dispatcher



The routing process makes use of three components: A route parser, a data generator and a

dispatcher. The three components adhere to the following interfaces:



```php

 'FastRoute\\RouteParser\\Std',

    'dataGenerator' => 'FastRoute\\DataGenerator\\MarkBased',

    'dispatcher' => 'FastRoute\\Dispatcher\\MarkBased',

]);

```



The above options array corresponds to the defaults. By replacing `MarkBased` with

`GroupCountBased` you could switch to a different dispatching strategy.



### A Note on HEAD Requests



The HTTP spec requires servers to [support both GET and HEAD methods][2616-511]:



> The methods GET and HEAD MUST be supported by all general-purpose servers



To avoid forcing users to manually register HEAD routes for each resource we fallback to matching an

available GET route for a given resource. The PHP web SAPI transparently removes the entity body

from HEAD responses so this behavior has no effect on the vast majority of users.



However, implementers using FastRoute outside the web SAPI environment (e.g. a custom server) MUST

NOT send entity bodies generated in response to HEAD requests. If you are a non-SAPI user this is

*your responsibility*; FastRoute has no purview to prevent you from breaking HTTP in such cases.



Finally, note that applications MAY always specify their own HEAD method route for a given

resource to bypass this behavior entirely.



### Credits



This library is based on a router that [Levi Morrison][levi] implemented for the Aerys server.



A large number of tests, as well as HTTP compliance considerations, were provided by [Daniel Lowrey][rdlowrey].



[2616-511]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html#sec5.1.1 "RFC 2616 Section 5.1.1"

[blog_post]: http://nikic.github.io/2014/02/18/Fast-request-routing-using-regular-expressions.html

[levi]: https://github.com/morrisonlevi

[rdlowrey]: https://github.com/rdlowrey