README.md

Yii File Router

Note: The router can be used along with the yiisoft/router package. Once the router found a matching route, it will interrupt the middleware queue and execute the controller action.

General usage

1. Add \Yiisoft\FileRouter\FileRouter to the list of middlewares in your application configuration:

web/params.php

return [
    'middlewares' => [
        // ...
        \Yiisoft\FileRouter\FileRouter::class,
        // or
        [
            'class' => FileRouter::class,
            'withNamespace()' => ['MyApp\\Package1'],
            'withDefaultControllerName()' => ['Default'],
        ],
        // ...
    ]
];

2. Configure the router for your needs.

Configuration

\Yiisoft\FileRouter\FileRouter supports the following configuration options:

withBaseControllerDirectory(string $directory): self

Sets the directory where controllers are located.

By default, it is set to Controller.

withClassPostfix(string $postfix): self

Sets the postfix for controller class names.

By default, it is set to Controller.

withNamespace(string $namespace): self

Sets the namespace for controller classes.

By default, it is set to App.

withDefaultControllerName(string $name): self

Sets the default controller name.

By default, it is set to Index.

withRoutePrefix(string $prefix): self

Sets the route prefix.

By default, it is empty.

It could be useful if you want to add a prefix to all routes or to separate routes from different modules.

Middlewares

\Yiisoft\FileRouter\FileRouter supports adding middlewares to the routes.

To add a middleware, add the static property $middlewares to the controller class:

class UserController
{
    public static array $middlewares = [
        'index' => [
            HeaderMiddleware::class,
        ],
    ];

    public function index(): ResponseInterface
    {
        return new TextResponse('Hello, user/index!');
    }
}

Where index is the method name and the value is an array of middleware class names, or middleware definitions.

Look at all supported middleware definitions formats in the Middleware Dispatcher package.

Matching

HTTP methods matching

The router maps HTTP methods to controller action methods as follows:

Method	Action
HEAD	head()
OPTIONS	options()
GET	index()
POST	create()
PUT	update()
PATCH	patch()
DELETE	delete()

Note: If the controller does not have a method that matches the HTTP method, the router will not throw an exception.

Custom routes

To add a custom route, add the static property $actions to the controller class:

class UserController
{
    public static array $actions = [
        'GET' => 'main',
    ];

    public function main(): ResponseInterface
    {
        return new TextResponse('Hello, user/main!', 200);
    }
}

Note: Once you override the actions map, the router will only look for the actions specified in the map. In the example above, the router will fail to find the index / delete, etc. actions

Route collision

Let's imagine that you have a request GET /user/index.

It has two possible controller and action variations:

• src/Controller/User/IndexController::index()
  • User/IndexController class has matched by the full route path (user/index)
  • index() method has matched by the HTTP methods matching
• src/Controller/UserController::index()
  • UserController class has matched by the first part of the route path (user)
  • index() method has matched by the second part of the route path (index)

For example, if you have a UserController and a User/IndexController, a GET request to /user will be handled by the UserController, if it has an index() method.

Otherwise, the User/IndexController will be used along with the HTTP methods matching.

Unicode routes

The router also supports Unicode in routes, controller names, and action names.

You can use Unicode characters in your URIs, controller class names, and action method names.

Modularity

You can add more than one router to the application. It can help to build a modular application.

For example, you have two modules with the same controller name:

- src
  - Module1/Controller/
    - UserController.php
  - Module2/Controller/
    - UserController.php

To add the router for each module, add the following code to the application configuration:

web/params.php

return [
    'middlewares' => [
        // ...
        [
            'class' => FileRouter::class,
            'withNamespace()' => ['App\\Module1\\'],
            'withRoutePrefix()' => ['module1'],
        ],
        [
            'class' => FileRouter::class,
            'withNamespace()' => ['App\\Module2\\'],
            'withRoutePrefix()' => ['module2'],
        ],
        // ...
    ]
];

As a usual middleware, each router will be executed one by one. The first router that matches the route will be used.