# Router
Namespace Chevere\Router
The Router package provides a strict, strong typed router for HTTP requests.
💡 Router introduction
Read Router for PHP (opens new window) at Rodolfo's blog for a compressive introduction to this package.
# Installing
Router is available through Packagist (opens new window) and the repository source is at GitHub (opens new window).
composer require chevere/router
# Features
- Define path, name, view, middleware and HTTP method to controller binding using named arguments.
- HTTP method binding works with HttpController objects.
- Wildcards (
{id}
in the code above) inherits regex from parameter attributes at controller layer.- Can be implicit (
{id}
) or explicit ({id:[0-9]+}
). - Detects conflicts for all endpoints.
- Can be implicit (
- Supports route groups, define
web
,api
,admin
and any group you may need to add. - Supports PSR middleware (opens new window).
# Creating a Router
To create a Router, define a group name and its routes.
In the example below, the web
group defines two routes and its corresponding endpoints for HTTP method (opens new window) to HTTP controller binding. Another group api
, defines routing for API endpoints.
💡 Consider Router groups as namespaces, which resolves in the same website context.
use function Chevere\Router\router;
use function Chevere\Router\routes;
use function Chevere\Router\route;
router(
web: routes(
route(
path: '/',
GET: new HomeGetController(),
),
route(
path: '/product/{id}',
GET: new ProductGetController(),
POST: new ProductPostController(),
),
),
api: routes(
route(
path: '/api',
GET: new ApiGetController(),
),
route(
path: '/api/product',
DELETE: new ApiDeleteProductController(),
),
)
);
🪄 HTTP method HEAD
is automatic added when defining GET
.
# Routes
A Route is the building block for Router, on its most elemental representation it defines a path that will be routed to a HTTP endpoint.
In the example below, the run method of HomeGetController
will be executed when resolving requests to /
.
use function Chevere\Router\route;
route(
path: '/',
GET: new HomeGetController(),
);
# Wildcards
Route path can define wildcards, enabling to pass dynamic route-path-based arguments to Controllers. In the example below, wildcard {id}
determines a dynamic run
argument for ProductGetController
.
use function Chevere\Router\route;
route(
path: '/product/{id}',
GET: new ProductGetController(),
),
At ProductGetController
we define the regex for this {id}
wildcard by using StringAttribute
annotation.
use Chevere\Controller\HttpController;
use Chevere\Parameter\Attributes\StringAttribute;
class ProductGetController extends HttpController
{
public function run(
#[StringAttribute('/^[1-9]\d*/')]
string $id
): array {
// ...
}
}
For the request /product/123
the system will first check match of 123
against /^[1-9]\d*/
and then it will pass 123
to the run
method. Requests failing to match the defined regex will throw a HTTP 404 error.
# Additional attributes
Route may define name and view attributes. In the example below the Route at /
gets a name and view binding.
use Chevere\Controller\HttpMiddleware;
use function Chevere\Router\route;
route(
path: '/',
name: 'My Home',
view: 'home/default',
GET: new HomeGetController(),
);
# Middleware
Route can define HTTP Middleware, which is a collection of objects implementing Psr\Http\Server\MiddlewareInterface
. In the example below, CheckAuthToken
determines the validity of the request and RedirectIfLoggedIn
will redirect to another location (usually the user profile).
use Chevere\Controller\HttpMiddleware;
use function Chevere\Router\route;
route(
path: '/',
middleware: new HttpMiddleware(
new CheckAuthToken(),
new RedirectIfLoggedIn(),
)
GET: new HomeGetController(),
);