Download the PHP package stratify/router without Composer

Routers implemented as a PSR-7 middleware.

This package provides 3 routers:

• a "classic" router for web applications
• a REST router for building REST APIs
• a "prefix" router that routes to sub-middlewares based on URL prefixes

Everything is a middleware

Each router is a middleware, which means it can be used as many times as needed in a middleware stack. That also means that if a router doesn't match the request to a route, it's not an error: it will simply call the $next middleware.

Additionally, controllers (aka route handlers) are also middlewares. Routers are simply routing the flow of the request to a sub-branch of middlewares. That allows to remove the specific concept of "route middlewares".

Here is an example of using several routers in one application, as well as using middlewares in routes:

Please keep in mind this example is over-simplified. It's perfectly possible to benefit from dependency injection, lazy instantiation of controllers/middlewares as well as a simpler API for configuring the application; that's what the Stratify framework brings on top of the router.

Installation

Classic router

This "classic" router is very similar to other PHP routers. It is built on top of Aura.Router.

The router takes a map of URLs to callables, for example:

By default only the HTTP GET method will be allowed.

Placeholders can be used in route paths and fetched from request attributes or injected as parameters:

Routes can be configured in more details using the route() helper.

• placeholder formats (using a regex):

• optional placeholders:

• accepted HTTP methods:

HTTP resources

You can define separate handlers for each HTTP method using the resource() helper:

However if you plan on using all HTTP methods you might want to use the RestRouter instead.

Controllers

Controllers, aka "route handlers", can be any PHP callables (closures, object methods, invokable objects, …).

The callable can decide which parameters it will take. The router will detect what to provide based on the callable's parameters. Parameters can be:

• the PSR-7 request: ServerRequestInterface $request; in that case the parameter must be named $request
• any request attribute, this includes:
  • route placeholders: /order/{orderId} => you can have a $orderId parameter (parameter names must be identical to the route placeholder name)
  • or any attribute defined by a previous middleware (e.g. if an authentication middleware defines a user attribute, you can have a $user parametre)
• the next callable to call ($next parameter), see below

Since a controller/route handler is a middleware, it can also have the middleware signature:

Controller responses

Controllers, like middlewares, are expected to return PSR-7 response objects.

However, in order to ease development, they can also return strings: those will be automatically turned into 200 HTML responses.

REST router

The REST router behaves exactly like the classic router (the same rules applies for controllers) except that it allows to register handlers more easily for HTTP resources.

This is equivalent to this mapping with the classic router:

Here is an example of a REST controller:

Prefix router

The PrefixRouter is a very simple and very fast router that routes based on URL prefixes.

The first prefix to match is used. Each route handler must be a middleware, i.e. a callable whose signature matches:

The prefix router is useful to separate several parts of a large application that do not need the same middlewares, for example:

• authentication required for all the "admin" part, but no authentication on the public website
• cache for the public website but no caching in the backend
• content negotiation and token authentication for an API, but not for the rest of the application
• etc.