Download the PHP package crysalead/router without Composer

Router - HTTP Request Router

Complete benchmark results can be found here.

• Compatible with PSR-7
• Named routes
• Reverses routing
• Sub-domain
• Nested routes
• Custom dispatching strategy
• Advanced route pattern syntax

Installation

API

Route patterns

Route pattern are path string with curly brace placeholders. Possible placeholder format are:

• '{name}' - placeholder
• '{name:regex}' - placeholder with regex definition.
• '[{name}]' - optionnal placeholder
• '[{name}]+' - recurring placeholder
• '[{name}]*' - optionnal recurring placeholder

Variable placeholders may contain only word characters (latin letters, digits, and underscore) and must be unique within the pattern. For placeholders without an explicit regex, a variable placeholder matches any number of characters other than '/' (i.e [^/]+).

You can use square brackets (i.e []) to make parts of the pattern optional. For example /foo[bar] will match both /foo and /foobar. Optional parts can be nested and repeatable using the []* or []+ syntax. Example: /{controller}[/{action}[/{args}]*].

Examples:

• '/foo/' - Matches only if the path is exactly '/foo/'. There is no special treatment for trailing slashes, and patterns have to match the entire path, not just a prefix.
• '/user/{id}' - Matches '/user/bob' or '/user/1234!!!' or even '/user/bob/details' but not '/user/' or '/user'.
• '/user/{id:[^/]+}' - Same as the previous example.
• '/user[/{id}]' - Same as the previous example, but also match '/user'.
• '/user[/[{id}]]' - Same as the previous example, but also match '/user/'.
• '/user[/{id}]*' - Match '/user' as well as 'user/12/34/56'.
• '/user/{id:[0-9a-fA-F]{1,8}}' - Only matches if the id parameter consists of 1 to 8 hex digits.
• '/files/{path:.*}' - Matches any URL starting with '/files/' and captures the rest of the path into the parameter 'path'.

Note: the difference between /{controller}[/{action}[/{args}]*] and /{controller}[/{action}[/{args:.*}]] for example is args will be an array using [/{args}]* while a unique "slashed" string using [/{args:.*}].

The Router

The Router instance can be instantiated so:

Optionally, if your project lives in a sub-folder of your web root you'll need to set a base path using basePath(). This base path will be ignored so your routes won't need to be prefixed with it to matches the request path.

Note: If you are using the crysalead/net library you can pass Request::ingoing()->basePath(); directly so you won't need to set it manually.

The Router Public Methods

Route definition

Example of routes definition:

In the above example a route is registered using the ->bind() method and takes as parametters a route pattern, an optionnal options array and the callback handler.

The second parameter is an $options array where possible values are:

• 'scheme': the scheme constraint (default: '*')
• 'host': the host constraint (default: '*')
• 'methods': the method constraint (default: '*')
• 'name': the name of the route (optional)
• 'namespace': the namespace to attach to a route (optional)

The last parameter is the callback handler which contain the dispatching logic to execute when a route matches the request. The callback handler is the called with the matched route as first parameter and the response object as second parameter:

The Route Public Attributes

The Route Mublic Methods

Named Routes And Reverse Routing

To be able to do some reverse routing, route must be named using the following syntax first:

Named routes can be retrieved using the array syntax on the router instance:

Once named, the reverse routing can be done using the ->link() method:

The ->link() method takes as first parameter the name of a route and as second parameter the route's arguments.

Grouping Routes

It's possible to apply a scope to a set of routes all together by grouping them into a dedicated group using the ->group() method.

The above example will be able to route /admin/user/edit on App\Admin\Controller\User::edit(). The fully-namespaced class name of the controller is built using the {controller} variable and it's then instanciated to process the request by running the {action} method.

Sub-Domain And/Or Prefix Routing

To supports some sub-domains routing, the easiest way is to group routes using the ->group() method and setting up the host constraint like so:

The above example will be able to route http://foo.hello.bar/admin/user/edit for example.

Middleware

Middleware functions are functions that have access to the request object, the response object, and the next middleware function in the application’s request-response cycle. Middleware functions provide the same level of control as aspects in AOP. It allows to:

• Execute any code.
• Make changes to the request and the response objects.
• End the request-response cycle.
• Call the next middleware function in the stack.

And it's also possible to apply middleware functions globally on a single route or on a group of them. Adding a middleware to a Route is done using the ->apply() method:

You can also attach middlewares on groups.

Dispatching

Dispatching is the outermost layer of the framework, responsible for both receiving the initial HTTP request and sending back a response at the end of the request's life cycle.

This step has the responsibility to loads and instantiates the correct controller, resource or class to build a response. Since all this logic depends on the application architecture, the dispatching has been splitted in two steps for being as flexible as possible.

Dispatching A Request

The URL dispatching is done in two steps. First the ->route() method is called on the router instance to find a route matching the URL. The route accepts as arguments:

• An instance of Psr\Http\Message\RequestInterface
• An url or path string
• An array containing at least a path entry
• A list of parameters with the following order: path, method, host and scheme

The ->route() method returns a route (or a "not found" route), then the ->dispatch() method will execute the dispatching logic contained in the route handler (or throwing an exception for non valid routes).

Dispatching A Request Using Some PSR-7 Compatible Request/Response

It also possible to use compatible Request/Response instance for the dispatching.

Handling dispatching failures

Setting up a custom dispatching strategy.

To use your own strategy you need to create it using the ->strategy() method.

Bellow an example of a RESTful strategy:

The strategy:

Acknowledgements

• Li3
• FastRoute