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.0 or higher.

Installation

The package could be installed with Composer:

Additionally, you will need an adapter such as FastRoute.

Defining routes and URL matching

Common usage of the router looks like the following:

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:

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

Route could match for one or more HTTP methods: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS. There are corresponding static methods for creating a route for a certain method. If a route is to handle multiple methods at once, it could be created using methods().

If you want to generate a URL based on route and its parameters, give it a name with name(). Check "Creating URLs" for details.

action() in the above 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:

Defaults for parameters could be provided via defaults() method:

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:

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":

Route groups

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

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:

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:

Creating URLs

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

Then that is how URL could be obtained for it:

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

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

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:

The information could be obtained as follows:

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