Usage

Introduction

It is very easy to get up and running with Route. You can use Composer to install and manage your installation of Route. You’ll need to install both the Route project and an implementation of the PSR-7 message interface.

First, install the Route project itself:

composer require league/route

Next, install an implementation of PSR-7. We recommend the Laminas Diactoros project.

composer require laminas/laminas-diactoros

If you use Laminas Diactoros project you will also need

composer require laminas/laminas-httphandlerrunner

Optionally, you could also install a PSR-11 dependency injection container, see Dependency Injection for more information.

composer require league/container

What’s New in 7.0

Version 7.0 introduces several powerful new features:

• RouterInterface: A new RouterInterface that extends PSR-15’s RequestHandlerInterface, providing type-safe dependency injection. Both Router and Cache\Router implement this interface.
• Route Matching: The new match() method allows you to check if a route matches without executing it. It returns a MatchResult value object with a MatchStatus enum (Found, NotFound, MethodNotAllowed).
• Route Introspection: Retrieve all registered routes with getRoutes(), useful for route debugging, documentation, and advanced routing scenarios.
• Improved Cached Router: The cached router is no longer BETA. It caches compiled FastRoute data (not the router object itself) and automatically recovers from corrupt caches.
• PHP 8.2 Minimum: Requires PHP 8.2.0 or higher.

See Route Matching for more details on the new matching capabilities.

Hello, World!

Now that we have all the packages we need, we can make a simple Hello, World! application in one file.

<?php declare(strict_types=1);

include 'path/to/vendor/autoload.php';

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;

$request = Laminas\Diactoros\ServerRequestFactory::fromGlobals(
    $_SERVER, $_GET, $_POST, $_COOKIE, $_FILES
);

$router = new League\Route\Router;

$router->map('GET', '/', function (ServerRequestInterface $request): ResponseInterface {
    $response = new Laminas\Diactoros\Response;
    $response->getBody()->write('<h1>Hello, World!</h1>');
    return $response;
});

$response = $router->dispatch($request);

(new Laminas\HttpHandlerRunner\Emitter\SapiEmitter)->emit($response);

APIs

Only a few changes are needed to create a simple JSON API. We have to change the strategy that the router uses to dispatch a controller, as well as providing a response factory to ensure the JSON Strategy can build the response it needs to.

To provide a response factory, we will need to install a package that provides a response factory, such as Laminas Diactoros.

<?php declare(strict_types=1);

include 'path/to/vendor/autoload.php';

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;

$request = Laminas\Diactoros\ServerRequestFactory::fromGlobals(
    $_SERVER, $_GET, $_POST, $_COOKIE, $_FILES
);

$responseFactory = new Laminas\Diactoros\ResponseFactory();

$strategy = new League\Route\Strategy\JsonStrategy($responseFactory);
$router   = (new League\Route\Router)->setStrategy($strategy);

$router->map('GET', '/', function (ServerRequestInterface $request): array {
    return [
        'title'   => 'My New Simple API',
        'version' => 1,
    ];
});

$response = $router->dispatch($request);

(new Laminas\HttpHandlerRunner\Emitter\SapiEmitter)->emit($response);

The code above will convert your returned array into a JSON response.

{
    "title": "My New Simple API",
    "version": 1
}