Roteamento
Definição de rotas, grupos, parâmetros, nomes e despacho.
Registro
Defina rotas em routes/web.php ou routes/api.php. A action aceita [Controller::class, 'método'] ou string Classe@metodo; prefira FQCN para deixar claro o namespace Web/API.
$router->get('/users/{id}', [UserApiController::class, 'show'], ['ApiAuthMiddleware']);Verbos e correspondência
O Router expõe get, post, put, patch, delete, options e match. Parâmetros dinâmicos {id} e opcionais {slug?} são passados à action; valores escalares tipados são convertidos via Reflection quando possível.
Grupos e middleware
$router->group([
'prefix' => '/admin',
'middleware' => ['AuthMiddleware'],
], function (Router $r): void {
$r->get('/dashboard', [DashboardController::class, 'index']);
});Prefixo e middlewares do grupo são combinados às definições internas. Middleware é executado antes da action. Parâmetros podem ser passados no nome, por exemplo RateLimitMiddleware:login.
Rotas resource
resource($path, $controller, $only = []) registra até sete rotas padrão (index/create/store/show/edit/update/destroy) e nomes como posts.index. O array $only restringe actions. O projeto usa essa facilidade disponível no Router, mas as rotas de exemplo não registram CRUD genérico automaticamente.
URLs nomeadas
Associe ->name('posts.show') à última rota e gere URL com route('posts.show', ['id' => 42]). Parâmetros obrigatórios omitidos lançam InvalidArgumentException; segmentos opcionais não fornecidos são removidos.
as, nem APIs como any() ou resource()->except(). Não as use como se estivessem implementadas.Básico · ligar uma rota à action
Uma rota associa verbo + caminho a um callable de Controller. Abaixo está um registro existente no projeto: o endpoint da API recebe um ID de URI e encaminha-o a show(). Para uma tela Web, routes/web.php define o mesmo tipo de vínculo.
$router->get('/users/{id}', [UserApiController::class, 'show'], ['ApiAuthMiddleware']);O Router captura `{id}` como string e usa Reflection para convertê-lo para `int`, pois a assinatura real é `show(int $id)`. O middleware roda antes da action. A classe/método precisam existir; erro de resolução vira erro de servidor controlado.
Intermediário · grupos, nomes e verbos de formulário
O grupo /auth no projeto compartilha GuestMiddleware. As rotas POST adicionam CSRF e rate limit individualmente; o prefixo entra no caminho final, então a rota abaixo atende POST /auth/login.
$router->group(['prefix' => '/auth', 'middleware' => ['GuestMiddleware']], function (Router $r): void {
$r->post('/login', [AuthController::class, 'login'], [
'CsrfMiddleware',
'RateLimitMiddleware:login',
]);
});Uma rota nomeada pode ser gerada com `route('auth.login')` para o GET já nomeado no projeto. O helper usa APP_URL e exige os placeholders obrigatórios; não concatene IDs manualmente quando houver nome de rota adequado.
Rotas resource · usar apenas quando as actions existirem
`resource($path, $controller, $only = [])` cria sete vínculos convencionais e nomes como `users.index`. Isso registra rotas; não cria método, regra de autorização nem CRUD automaticamente. Informe `only` para limitar a superfície e implemente cada action que registrar.
| Verbo | Caminho | Action | Nome convencional |
|---|---|---|---|
| GET | /users | index | users.index |
| GET | /users/create | create | users.create |
| POST | /users | store | users.store |
| GET | /users/{id} | show | users.show |
| GET | /users/{id}/edit | edit | users.edit |
| PUT | /users/{id} | update | users.update |
| DELETE | /users/{id} | destroy | users.destroy |
Para ver autenticação por middleware na prática, compare Middleware e FormRequest; as rotas da aplicação estão em routes/web.php e routes/api.php.
Geração de URL: Router::route() e helper global route()
Router::route(string $name, array $params = []): string gera uma URL absoluta para uma rota previamente nomeada com name(). Exemplo: $router->get('/users/{id}', ...)->name('users.show') e então $router->route('users.show', ['id' => 42]). Os placeholders precisam estar presentes; seus valores são codificados com rawurlencode() e a URL base vem de APP_URL. Um nome ausente ou parâmetro obrigatório ausente lança InvalidArgumentException.
O helper global route('users.show', ['id' => 42]) é diferente: ele tenta usar o Router global, mas em falha retorna o fallback da home em vez de propagar a exceção. Use Router::route() quando precisar detectar nome/parâmetros inválidos; não dependa do fallback como validação de rota.
Override de método de formulário
HTML suporta somente GET/POST. Para simular PUT/PATCH/DELETE, o formulário deve usar POST e incluir o campo oculto. Exemplo correto: <form method="POST" action="..."><?= csrf_field() ?><?= method_field('PUT') ?>.... As aspas em 'PUT' são necessárias em PHP. O Router só honra o override permitido em um POST; method_field() não cria novos verbos nem habilita métodos não suportados.
Registro de várias methods e OPTIONS
match(array $methods, string $path, array|string $action, array $middlewares = []): static registra uma rota por método e retorna a última rota registrada (ou o próprio Router se a lista estiver vazia). options(string $path, array|string $action, array $middlewares = []): static registra OPTIONS. Exemplo: $router->match(['GET', 'POST'], '/health', [HealthController::class, 'show']);. Quando CorsMiddleware está no grupo e trata um preflight, ele encerra a resposta antes da action; não espere que a action OPTIONS rode nesse caso.