枚举路由

Pin 用 PHP Enum 表达路由。每个 case 的值包含 HTTP 方法、URI 和可选路由名：

case Create = 'POST:/api/users';
case Login = 'POST:/auth/login|auth.login';

定义路由枚举

namespace App\Routes\User;

use App\Modules\User\Actions\ListUsersAction;
use Illuminate\Http\Request;
use Pin\Route\Attributes\Action;
use Pin\Route\Attributes\Middleware;
use Pin\Route\Attributes\Name;
use Pin\Route\InteractsWithRoute;
use Pin\Route\Routable;

enum UserRoute: string implements Routable
{
    use InteractsWithRoute;

    #[Name('user.index')]
    #[Action(ListUsersAction::class)]
    case Index = 'GET:/api/users';

    #[Middleware(\Illuminate\Foundation\Http\Middleware\TrimStrings::class)]
    case Create = 'POST:/api/users';

    case Update = 'PUT:/api/users/{id}';

    public static function registerRoutes(): void
    {
        foreach (self::cases() as $route) {
            $route->register($route->handler());
        }
    }
}

如果枚举使用 InteractsWithRoute，默认 registerRoutes() 已经会遍历全部 case 并调用 register()。

路由值格式

格式	结果
GET:/api/users	方法 GET，URI /api/users，名称自动推导为 users
POST:/api/users	名称自动推导为 users.create
PUT:/api/users/{id}	名称自动推导为 users.update
DELETE:/api/users/{id}	名称自动推导为 users.delete
`POST:/auth/login	auth.login`

也可以使用 #[Name('user.index')] 覆盖自动推导。

注册路由

单个路由：

UserRoute::Create->register([UserController::class, 'create']);

批量注册：

use Pin\Route\RouteRegistrar;

RouteRegistrar::register([
    App\Routes\User\UserRoute::class,
    App\Routes\Order\OrderRoute::class,
]);

Attribute

Attribute	说明
#[Name('name')]	覆盖路由名
#[Title('用户列表')]	给路由声明标题，常用于菜单或测试报告
#[Middleware(...)]	给 case 声明额外中间件
#[Action(...)]	指定 Route Testing 默认 Action
#[AssertionMethod(...)]	指定测试断言方式
#[Access(...)]	覆盖或关闭权限码

#[Access(false)] 会跳过权限中间件。未传权限码时，如果 auth.access.enabled 为真，会使用 config('auth.access.middleware')。

生成 URL

$url = UserRoute::Update->route(['id' => 1]);
$path = UserRoute::Update->route(['id' => 1], absolute: false);

底层使用 Laravel 的 route()，路由名来自 RouteDefinition。

路由注册索引

每次 register() 成功后，RouteRegistry 会绑定枚举 case 和 Laravel Route：

use Pin\Route\RouteRegistry;

$items = RouteRegistry::items();

这对菜单生成、测试报告和权限列表很有用。

路由扫描

Pin\Route\RouteScanner 会按 PSR-4 路径扫描 *Route.php，并过滤实现 Routable 的枚举：

$routes = app(Pin\Route\RouteScanner::class)->scan([
    app_path('Routes'),
]);

扫描结果是一组可交给 RouteRegistrar::register() 的枚举类名。