berlioz/router

Berlioz Router

Berlioz Router

, _(*1)

Berlioz Router is a PHP library for manage HTTP routes, respecting PSR-7 (HTTP message interfaces) standard., _(*2)

Installation

Composer

You can install Berlioz Router with Composer, it's the recommended installation., _(*3)

$ composer require berlioz/router

Dependencies

• PHP ^8.0
• Packages:
  • berlioz/http-message
  • psr/log

Usage

Routes

Create route

You can create simple route like this:, _(*4)

use Berlioz\Router\Route;

$route = new Route('/path-of/my-route');
$route = new Route('/path-of/my-route/{attribute}/with-attribute');

Constructor arguments are:, _(*5)

• defaults: an associated array to set default values of attributes when route is generated
• requirements: an associated array to restrict the format of attributes. Key is the name of attribute and value is the validation regex
• name: name of route
• method: an array of allowed HTTP methods, or just a method
• host: an array of allowed hosts, or just a host
• priority: you can specify the priority for a route (default: -1)

Route group

A route can be transformed to a group, only associate another route to them., _(*6)

use Berlioz\Router\Route;

$route = new Route('/path');
$route->addRoute($route2 = new Route('/path2')); // Path will be: /path/path2

Children routes inherit parent route attributes, requirements, ..., _(*7)

Attributes

Route accept optional attributes, you need to wrap the optional part by brackets., _(*8)

$route = new \Berlioz\Router\Route('/path[/optional-part/{with-attribute}]');

You can also define requirements directly in the path :, _(*9)

• Add a regular expression after the name of attribute (separate by ":").
• Add a type name after the name of attribute (separate by "::").

$route = new \Berlioz\Router\Route('/path/{attributeName:\d+}');
$route = new \Berlioz\Router\Route('/path/{attributeName::int}');

Supported defined types:, _(*10)

• int (equivalent of \d+)
• float (equivalent of \d+(\.\d+))
• uuid4 (equivalent of [0-9A-Fa-f]{8}\-[0-9A-Fa-f]{4}\-[0-9A-Fa-f]{4}\-[0-9A-Fa-f]{4}\-[0-9A-Fa-f]{12})
• slug (equivalent of [a-z0-9]+(?:-[a-z0-9]+)*)
• md5 (equivalent of [0-9a-fA-F]{32})
• sha1 (equivalent of [0-9a-fA-F]{40})
• domain (equivalent of ([a-zA-Z0-9]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,6})

Router

The router is the main functionality in the package, it is defined by Router class. He is able to find the good Route object according to a ServerRequestInterface object (see PSR-7)., _(*11)

use Berlioz\Http\Message\ServerRequest;
use Berlioz\Router\Route;
use Berlioz\Router\Router;

// Create server request or get them from another place in your app
$serverRequest = new ServerRequest(...);

// Create router
$router = new Router();
$router->addRoute(
    new Route('/path-of/my-route'),
    new Route('/path-of/my-route/{attribute}/with-attribute')
);

$route = $router->handle($serverRequest);

Options

Generate path

You can generate a path with some parameters directly with Router object., _(*12)

use Berlioz\Router\Exception\NotFoundException;
use Berlioz\Router\Router;

$router = new Router();
// ...add routes

try {
    $path = $router->generate('name-of-route', ['attribute1' => 'value']);
} catch (NotFoundException $exception) {
    // ... not found route
}

The return of method, is the path in string format or thrown an exception if not able to generate path (not all required parameters for example)., _(*13)

Valid path

You can be valid a ServerRequestInterface to known if a path can be treated by a route., _(*14)

use Berlioz\Http\Message\ServerRequest;
use Berlioz\Router\Router;

$serverRequest = new ServerRequest(...);
$router = new Router();
// ...add routes

/** bool $valid Valid path ?*/
$valid = $router->isValid($serverRequest);

The return of method is a boolean value., _(*15)