Download the PHP package ingenioz-it/router without Composer

Router

A PHP Router.

Disclaimer

In order to ensure that this package is easy to integrate into your app, it is built around the PHP Standard Recommendations : it takes in a PSR-7 Server Request and returns a PSR-7 Response. It also uses a PSR-11 Container (such as EDICT) to resolve the route handlers.

It is inspired by routers from well-known frameworks (did anyone say Laravel ?) aswell as some home-made routers used internally by some major companies.

It is build with quality in mind : readability, immutability, no global states, 100% code coverage, 100% mutation testing score, and validation from various static analysis tools at the highest level.

About

Info	Value
Latest release
Requires
License
Unit tests
Code coverage
Code quality
Quality tested with	phpunit, phan, psalm, phpcs, phpstan, phpmd, infection, rector

Installation

Documentation

Overview

Here is the whole process of using this router :

• Create your routes
• Instantiate the router
• Handle the request:

Basic routing

The simplest route consists of a path and a handler.

The path is a string, and the handler is a callable that will be executed when the route is matched. The handler must return a PSR-7 ResponseInterface.

Organizing routes

Route groups are used to contain routes definitions.
They also allows you to visually organize your routes according to your application's logic.

This is useful when you want to apply the same conditions, middlewares, or attributes to several routes at once (as we will see later).

Route groups can be nested to create a hierarchy of routes that will inherit everything from their parent groups.

HTTP methods

You can specify the HTTP method that the route should match:

If you want a route to match multiple HTTP methods, you can use the some method:

You can also use the any method to match all HTTP methods:

Path parameters

Basic usage

You can define route parameters by using the {} syntax in the route path.

The matched parameters will be available in the request attributes.

Custom parameter patterns

By default, the parameters are matched by the [^/]+ regex (any characters that are not a /).

You can specify a custom pattern by using the where parameter:

Custom parameter patterns in a group

Parameters patterns can also be defined globally for all routes inside a group:

Route handlers

Closures

The simplest way to define a route handler is to use a closure.
The closure must return a PSR-7 ResponseInterface.

Closures can take in parameters: the request and a request handler (the router itself).

RequestHandlerInterface

A route handler can be a callable, but it can also be a PSR RequestHandlerInterface.

MiddlewareInterface

Sometimes, you might want a handler to be able to "refuse" to handle the request, and pass it to the next handler in the chain.

This is done by using a PSR MiddlewareInterface as a route handler :

Dependency injection

Instead of using a closure or a class instance, your handler can be a class name. The router will then resolve the class using the PSR container you injected into the router.

The router will resolve this handler by calling get(MyHandler::class) on the container. This means that you can use any value that the container can resolve into a valid route handler.

Additional attributes

You can add additional attributes to a route by using the with method.
Just like path parameters, these attributes will be available in the request attributes.

Attributes can also be defined globally for all the routes inside a group:

Middlewares

Middlewares are classes that can modify the request and/or the response before and after the route handler is called.

They can be applied to a route group.

The middleware class must implement the PSR \Psr\Http\Server\MiddlewareInterface interface.

Conditions

Conditions are callables that will determine if a route group should be parsed.

Additionally, conditions can return an array of attributes that will be added to the request attributes.

If a condition returns an array, it is assumed that the route group should be parsed.

If any condition returns false, the route group will not be parsed:

Naming routes

Routes can be named.

Using the router, you can then generate the path to a named route:

If a route has parameters, you can pass them as the second argument:

Error handling

This router uses custom exceptions to handle errors.

Here is the inheritance tree of those exceptions:

• IngeniozIT\Router\RouterException (interface): the base exception, all other exceptions inherit from this one
  • IngeniozIT\Router\EmptyRouteStack: thrown when no route has been matched by the router
  • IngeniozIT\Router\Route\RouteException: (interface) the base exception for route errors
    • IngeniozIT\Router\Route\Exception\InvalidRouteHandler: thrown when the route handler is not a valid request handler
    • IngeniozIT\Router\Route\Exception\InvalidRouteResponse: thrown when the route handler does not return a PSR-7 ResponseInterface
    • IngeniozIT\Router\Route\Exception\RouteNotFound: thrown when calling $router->pathTo with a route name that does not exist
    • IngeniozIT\Router\Route\Exception\InvalidRouteParameter: thrown when calling $router->pathTo with invalid parameters
    • IngeniozIT\Router\Route\Exception\MissingRouteParameters: thrown when calling $router->pathTo with missing parameters
  • IngeniozIT\Router\Middleware\MiddlewareException: (interface) the base exception for middleware errors
    • IngeniozIT\Router\Middleware\Exception\InvalidMiddlewareHandler: thrown when a middleware is not a valid middleware handler
    • IngeniozIT\Router\Middleware\Exception\InvalidMiddlewareResponse: thrown when a middleware does not return a PSR-7 ResponseInterface
  • IngeniozIT\Router\Condition\ConditionException: (interface) the base exception for condition errors
    • IngeniozIT\Router\Condition\Exception\InvalidConditionHandler: thrown when a condition is not a valid condition handler
    • IngeniozIT\Router\Condition\Exception\InvalidConditionResponse: thrown when a condition does not return a valid response