Yii Router

The package provides PSR-7 compatible request routing and a PSR-15 middleware ready to be used in an application. Instead of implementing routing from ground up, the package provides an interface for configuring routes and could be used with an adapter package. Currently, the only adapter available is FastRoute.

Features

• URL matching and URL generation supporting HTTP methods, hosts, and defaults.
• Good IDE support for defining routes.
• Route groups with infinite nesting.
• Middleware support for both individual routes and groups.
• Ready to use middleware for route matching.
• Convenient CurrentRoute service that holds information about last matched route.
• Out of the box CORS middleware support.

Requirements

• PHP 8.1 - 8.5.

Installation

The package could be installed with Composer:

composer require yiisoft/router

Additionally, you will need an adapter such as FastRoute.

Defining routes and URL matching

Common usage of the router looks like the following:

use Yiisoft\Router\CurrentRoute;
use Yiisoft\Router\Group;
use Yiisoft\Router\Route\Get;
use Yiisoft\Router\RouteCollection;
use Yiisoft\Router\RouteCollectorInterface;
use Yiisoft\Router\UrlMatcherInterface;
use Yiisoft\Router\Fastroute\UrlMatcher;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;

// Define routes
$routes = [
    new Get(
        pattern: '/',
        action: static function (ServerRequestInterface $request, RequestHandlerInterface $next) use ($responseFactory) {
            $response = $responseFactory->createResponse();
            $response
                ->getBody()
                ->write('You are at homepage.');
            return $response;
        },
    ),
    new Get(
        pattern: '/test/{id:\w+}',
        action: static function (CurrentRoute $currentRoute, RequestHandlerInterface $next) use ($responseFactory) {
            $id = $currentRoute->getArgument('id');
    
            $response = $responseFactory->createResponse();
            $response
                ->getBody()
                ->write('You are at test with argument ' . $id);
            return $response;
        },
    ),
];

// Add routes defined to route collector
$collector = $container->get(RouteCollectorInterface::class);
$collector->addRoute(...$routes);

// Initialize URL matcher
/** @var UrlMatcherInterface $urlMatcher */
$urlMatcher = new UrlMatcher(new RouteCollection($collector));

// Do the match against $request which is PSR-7 ServerRequestInterface. 
$result = $urlMatcher->match($request);

if (!$result->isSuccess()) {
     // 404
}

// $result->arguments() contains arguments from the match.

// Run middleware assigned to a route found.
$response = $result->process($request, $notFoundHandler);

Note: Despite UrlGeneratorInterface and UrlMatcherInterface being common for all adapters available, certain features and, especially, pattern syntax may differ. To check usage and configuration details, please refer to specific adapter documentation. All examples in this document are for FastRoute adapter.

Middleware usage

In order to simplify usage in PSR-middleware based application, there is a ready to use middleware provided:

$router = $container->get(Yiisoft\Router\UrlMatcherInterface::class);
$responseFactory = $container->get(\Psr\Http\Message\ResponseFactoryInterface::class);

$routerMiddleware = new Yiisoft\Router\Middleware\Router($router, $responseFactory, $container);

// Add middleware to your middleware handler of choice.

In case of a route match router middleware executes handler middleware attached to the route. If there is no match, next application middleware processes the request.

Routes

Routes can match one or more HTTP methods. Use new Get(), new Post(), new Put(), new Delete(), new Patch(), new Head(), or new Options() from the Yiisoft\Router\Route namespace for a single method. For multiple methods, use new Route() with the methods argument.

Configure routes directly with named constructor arguments:

use Yiisoft\Http\Method;
use Yiisoft\Router\Route;
use Yiisoft\Router\Route\Delete;

new Delete(
    pattern: '/post/{id}',
    name: 'post-delete',
    action: [PostController::class, 'actionDelete'],
);

new Route(
    pattern: '/page/add',
    methods: [Method::GET, Method::POST],
    name: 'page-add',
    action: [PageController::class, 'actionAdd'],
);

The static factories Route::get(), post(), put(), delete(), patch(), head(), options(), methods(), and Group::create() are deprecated. Use constructors instead. The immutable configuration methods remain available.

If you want to generate a URL based on route and its parameters, provide the name constructor argument. Check Creating URLs for details.

The action argument is a primary middleware definition that is invoked last when matching result process() method is called. How middleware are executed and what middleware formats are accepted is defined by middleware dispatcher used. See readme of yiisoft/middleware-dispatcher for middleware examples.

If a route should be applied only to a certain host, it could be defined like the following:

use Yiisoft\Router\Route\Get;

new Get(
    pattern: '/special',
    name: 'special',
    action: SpecialAction::class,
    hosts: ['https://www.yiiframework.com'],
);

Defaults for parameters can be provided via the defaults constructor argument:

use Yiisoft\Router\Route\Get;

new Get(
    pattern: '/api[/v{version}]',
    name: 'api-index',
    action: ApiAction::class,
    defaults: ['version' => 1],
);

In the above we specify that if "version" is not obtained from URL during matching then it will be 1.

Besides action, additional middleware to execute before the action itself could be defined:

use Yiisoft\Http\Method;
use Yiisoft\Router\Route;

new Route(
    pattern: '/page/add',
    methods: [Method::GET, Method::POST],
    name: 'blog/add',
    action: [PostController::class, 'add'],
    middlewares: [Authentication::class, ExtraHeaders::class],
);

It is typically used for a certain actions that could be reused for multiple routes such as authentication.

If there is a need to either add middleware to be executed first or remove existing middleware from a route, prependMiddleware() and disableMiddleware() could be used.

If you combine routes from multiple sources and want last route to have priority over existing ones, mark it as "override":

use Yiisoft\Router\Route\Get;

new Get(
    pattern: '/special',
    name: 'special',
    action: SpecialAction::class,
    override: true,
);

Route groups

Routes could be grouped. That is useful for API endpoints and similar cases:

use Yiisoft\Router\Group;
use Yiisoft\Router\Route\Get;
use Yiisoft\Router\RouteCollectorInterface;

// for obtaining router see adapter package of choice readme
$collector = $container->get(RouteCollectorInterface::class);
    
$collector->addRoute(
    new Group(
        prefix: '/api',
        middlewares: [ApiAuthentication::class],
        hosts: ['https://example.com'],
        routes: [
            new Get('/comments'),
            new Group('/posts', routes: [
                new Get('/list'),
            ]),
        ],
    ),
);

A group could have a prefix, such as /api in the above. The prefix is applied for each group's route both when matching and when generating URLs.

Similar to individual routes, a group could have a set of middleware managed using middleware(), prependMiddleware(), and disableMiddleware(). These middleware are executed prior to matched route's own middleware and action.

If host is specified, all routes in the group would match only if the host match.

Automatic OPTIONS response and CORS

By default, router responds automatically to OPTIONS requests based on the routes defined:

HTTP/1.1 204 No Content
Allow: GET, HEAD

Generally that is fine unless you need CORS headers. In this case, you can add a middleware for handling it such as tuupola/cors-middleware:

use Yiisoft\Router\Group;
use \Tuupola\Middleware\CorsMiddleware;

return [
    new Group(
        prefix: '/api',
        corsMiddleware: CorsMiddleware::class,
        routes: [
            // ...
        ],
    ),
];

Creating URLs

URLs could be created using UrlGeneratorInterface::generate(). Let's assume a route is defined like the following:

use Yiisoft\Http\Method;
use Yiisoft\Router\Route\Get;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;
use Psr\Http\Message\ResponseFactoryInterface;
use Yiisoft\Yii\Http\Handler\NotFoundHandler;
use Yiisoft\Yii\Runner\Http\SapiEmitter;
use Yiisoft\Yii\Runner\Http\ServerRequestFactory;
use Yiisoft\Router\CurrentRoute;
use Yiisoft\Router\RouteCollection;
use Yiisoft\Router\RouteCollectorInterface;
use Yiisoft\Router\Fastroute\UrlMatcher;


$request = $container
    ->get(ServerRequestFactory::class)
    ->createFromGlobals();
$responseFactory = $container->get(ResponseFactoryInterface::class);
$notFoundHandler = new NotFoundHandler($responseFactory);
$collector = $container->get(RouteCollectorInterface::class);
$collector->addRoute(
    new Get(
        pattern: '/test/{id:\w+}',
        action: static function (CurrentRoute $currentRoute, RequestHandlerInterface $next) use ($responseFactory) {
            $id = $currentRoute->getArgument('id');
            $response = $responseFactory->createResponse();
            $response
                ->getBody()
                ->write('You are at test with argument ' . $id);

           return $response;
        },
        name: 'test',
    )
);
$router = new UrlMatcher(new RouteCollection($collector));
$route = $router->match($request);
$response = $route->process($request, $notFoundHandler);
$emitter = new SapiEmitter();
$emitter->emit($response, $request->getMethod() === Method::HEAD);

Then that is how URL could be obtained for it:

use Yiisoft\Router\UrlGeneratorInterface;

function getUrl(UrlGeneratorInterface $urlGenerator, $parameters = [])
{
    return $urlGenerator->generate('test', $parameters);
}

Absolute URL cold be generated using UrlGeneratorInterface::generateAbsolute():

use Yiisoft\Router\UrlGeneratorInterface;

function getUrl(UrlGeneratorInterface $urlGenerator, $parameters = [])
{
    return $urlGenerator->generateAbsolute('test', $parameters);
}

Also, there is a handy UrlGeneratorInterface::generateFromCurrent() method. It allows generating a URL that is a modified version of the current URL:

use Yiisoft\Router\UrlGeneratorInterface;

function getUrl(UrlGeneratorInterface $urlGenerator, $id)
{
    return $urlGenerator->generateFromCurrent(['id' => 42]);
}

In the above, ID will be replaced with 42 and the rest of the parameters will stay the same. That is useful for modifying URLs for filtering and/or sorting.

Obtaining current route information

For such a route:

use Yiisoft\Router\Route\Post;

$routes = [
    new Post(
        pattern: '/post/{id:\d+}',
        action: [PostController::class, 'actionEdit'],
    ),
];

The information could be obtained as follows:

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\UriInterface;
use Yiisoft\Router\CurrentRoute;

final class PostController
{   
    public function actionEdit(CurrentRoute $currentRoute): ResponseInterface
    {
        $postId = $currentRoute->getArgument('id');
        if ($postId === null) {
            throw new \InvalidArgumentException('Post ID is not specified.');
        }
        
        // ...
    
    }
}

In addition to commonly used getArgument() method, the following methods are available:

• getArguments() - To obtain all arguments at once.
• getName() - To get route name.
• getHost() - To get route host.
• getPattern() - To get route pattern.
• getMethods() - To get route methods.
• getUri() - To get current URI.

Documentation

• Internals

If you need help or have a question, the Yii Forum is a good place for that. You may also check out other Yii Community Resources.

License

The Yii Router is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.

Support the project

Follow updates