Docs folder standardization and other fixes

LICENSE.md

@@ -1,17 +1,17 @@
-Copyright © 2008 by Yii Software (https://www.yiiframework.com/)
+Copyright © 2008 by Yii Software (<https://www.yiiframework.com/>)
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
 
- * Redistributions of source code must retain the above copyright
+* Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
- * Redistributions in binary form must reproduce the above copyright
+* Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in
    the documentation and/or other materials provided with the
    distribution.
- * Neither the name of Yii Software nor the names of its
+* Neither the name of Yii Software nor the names of its
    contributors may be used to endorse or promote products derived
    from this software without specific prior written permission.
 

README.md

@@ -31,55 +31,15 @@ composer require yiisoft/file-router
 
 ## Documentation
 
-- [English](docs/en/README.md)
+- [English](docs/guide/en/README.md)
+- [Português - Brasil](docs/guide/pt-BR/readme.md)
 
-## Testing
+- [Internals](docs/internals.md)
 
-### Unit testing
+## Support
 
-The package is tested with [PHPUnit](https://phpunit.de/). To run tests:
-
-```shell
-./vendor/bin/phpunit
-```
-
-### Mutation testing
-
-The package tests are checked with [Infection](https://infection.github.io/) mutation framework with
-[Infection Static Analysis Plugin](https://github.com/Roave/infection-static-analysis-plugin). To run it:
-
-```shell
-./vendor/bin/roave-infection-static-analysis-plugin
-```
-
-### Static analysis
-
-The code is statically analyzed with [Psalm](https://psalm.dev/). To run static analysis:
-
-```shell
-./vendor/bin/psalm
-```
-
-### Code style
-
-Use [Rector](https://github.com/rectorphp/rector) to make codebase follow some specific rules or 
-use either newest or any specific version of PHP: 
-
-```shell
-./vendor/bin/rector
-```
-
-### Dependencies
-
-Use [ComposerRequireChecker](https://github.com/maglnet/ComposerRequireChecker) to detect transitive 
-[Composer](https://getcomposer.org/) dependencies.
-
-## License
-
-The File Router is free software. It is released under the terms of the BSD License.
-Please see [`LICENSE`](./LICENSE.md) for more information.
-
-Maintained by [Yii Software](https://www.yiiframework.com/).
+If you need help or have a question, the [Yii Forum](https://forum.yiiframework.com/c/yii-3-0/63) is a good place for that.
+You may also check out other [Yii Community Resources](https://www.yiiframework.com/community).
 
 ## Support the project
 
@@ -92,3 +52,10 @@ Maintained by [Yii Software](https://www.yiiframework.com/).
 [![Telegram](https://img.shields.io/badge/telegram-join-1DA1F2?style=flat&logo=telegram)](https://t.me/yii3en)
 [![Facebook](https://img.shields.io/badge/facebook-join-1DA1F2?style=flat&logo=facebook&logoColor=ffffff)](https://www.facebook.com/groups/yiitalk)
 [![Slack](https://img.shields.io/badge/slack-join-1DA1F2?style=flat&logo=slack)](https://yiiframework.com/go/slack)
+
+## License
+
+The Yii Access is free software. It is released under the terms of the BSD License.
+Please see [`LICENSE`](./LICENSE.md) for more information.
+
+Maintained by [Yii Software](https://www.yiiframework.com/).

docs/en/README.md → docs/guide/en/README.md

@@ -1,9 +1,9 @@
-# Documentation
+# Yii File Router
 
-> Note: The router can be used along with the [`yiisoft/router`](https://github.com/yiisoft/router) package.
-
-> Note: Once the router found a matching route, it will interrupt the middleware queue and execute the controller
-> action.
+> **Notes:**
+>
+>- The router can be used along with the [`yiisoft/router`](https://github.com/yiisoft/router) package.
+>- Once the router found a matching route, it will interrupt the middleware queue and execute the controller action.
 
 ## General usage
 
@@ -131,7 +131,6 @@ class UserController
 > 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`.

docs/guide/pt-BR/README.md

@@ -0,0 +1,195 @@
+# Yii File Router
+
+> **Notes:**
+>
+>- The router can be used along with the [`yiisoft/router`](https://github.com/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`
+
+```php
+return [
+    'middlewares' => [
+        // ...
+        \Yiisoft\FileRouter\FileRouter::class,
+        // or
+        [
+            'class' => FileRouter::class,
+            'withNamespace()' => ['MyApp\\Package1'],
+            'withDefaultControllerName()' => ['Default'],
+        ],
+        // ...
+    ]
+];
+```
+
+2. [Configure the router](#configuration) 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](#modularity).
+
+## Middlewares
+
+`\Yiisoft\FileRouter\FileRouter` supports adding middlewares to the routes.
+
+To add a middleware, add the static property `$middlewares` to the controller class:
+
+```php
+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](https://github.com/yiisoft/middleware-dispatcher#general-usage) 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:
+
+```php
+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](#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](#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:
+
+```text
+- 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`
+
+```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.

docs/internals.md

@@ -0,0 +1,45 @@
+# Internals
+
+## Unit testing
+
+The package is tested with [PHPUnit](https://phpunit.de/). To run tests:
+
+```shell
+./vendor/bin/phpunit
+```
+
+## Mutation testing
+
+The package tests are checked with [Infection](https://infection.github.io/) mutation framework with
+[Infection Static Analysis Plugin](https://github.com/Roave/infection-static-analysis-plugin). To run it:
+
+```shell
+./vendor/bin/roave-infection-static-analysis-plugin
+```
+
+## Static analysis
+
+The code is statically analyzed with [Psalm](https://psalm.dev/). To run static analysis:
+
+```shell
+./vendor/bin/psalm
+```
+
+## Rector
+
+Use [Rector](https://github.com/rectorphp/rector) to make codebase follow some specific rules or
+use either newest or any specific version of PHP:
+
+```shell
+./vendor/bin/rector
+```
+
+## Composer require checker
+
+This package uses [composer-require-checker](https://github.com/maglnet/ComposerRequireChecker) to check if all dependencies are correctly defined in `composer.json`.
+
+To run the checker, execute the following command:
+
+```shell
+./vendor/bin/composer-require-checker
+```