Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/berliozframework/router
Berlioz Router is a PHP library for manage HTTP routes, respecting PSR-7 (HTTP message interfaces) standard.
https://github.com/berliozframework/router
berlioz composer php php-library psr router
Last synced: about 2 months ago
JSON representation
Berlioz Router is a PHP library for manage HTTP routes, respecting PSR-7 (HTTP message interfaces) standard.
- Host: GitHub
- URL: https://github.com/berliozframework/router
- Owner: BerliozFramework
- License: mit
- Created: 2018-01-26T15:41:30.000Z (almost 7 years ago)
- Default Branch: 2.x
- Last Pushed: 2024-11-04T13:28:14.000Z (about 2 months ago)
- Last Synced: 2024-11-04T14:27:48.688Z (about 2 months ago)
- Topics: berlioz, composer, php, php-library, psr, router
- Language: PHP
- Homepage: https://getberlioz.com
- Size: 101 KB
- Stars: 1
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Berlioz Router
[](https://github.com/BerliozFramework/Router/releases)
[](https://github.com/BerliozFramework/Router/blob/2.x/LICENSE)
[](https://github.com/BerliozFramework/Router/actions/workflows/tests.yml?query=branch%3A2.x)
[](https://www.codacy.com/manual/BerliozFramework/Router)
[](https://packagist.org/packages/berlioz/router)
**Berlioz Router** is a PHP library for manage HTTP routes, respecting PSR-7 (HTTP message interfaces) standard.
## Installation
### Composer
You can install **Berlioz Router** with [Composer](https://getcomposer.org/), it's the recommended installation.
```bash
$ 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:
```php
use Berlioz\Router\Route;
$route = new Route('/path-of/my-route');
$route = new Route('/path-of/my-route/{attribute}/with-attribute');
```
Constructor arguments are:
- **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.
```php
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, ...
#### Attributes
Route accept optional attributes, you need to wrap the optional part by brackets.
```php
$route = new \Berlioz\Router\Route('/path[/optional-part/{with-attribute}]');
```
You can also define requirements directly in the path :
- Add a regular expression after the name of attribute (separate by ":").
- Add a type name after the name of attribute (separate by "::").
```php
$route = new \Berlioz\Router\Route('/path/{attributeName:\d+}');
$route = new \Berlioz\Router\Route('/path/{attributeName::int}');
```
Supported defined types:
- `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).
```php
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
| Options | Type | Description |
|--------------------|----------------|-------------------------------------------------------------------------------------------|
| X-Forwarded-Prefix | boolean/string | Default to **false**, **true** to use "X-Forwarded-Prefix" value or custom name of header |
#### Generate path
You can generate a path with some parameters directly with `Router` object.
```php
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).
#### Valid path
You can be valid a `ServerRequestInterface` to known if a path can be treated by a route.
```php
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.