Tutorial Laravel 13 #2: o routing e as rotas nomeadas

Uma rota associa um endereço a código. É a porta de entrada de qualquer pedido: o Laravel lê o URL pedido, procura a rota que corresponde e executa aquilo que ela designa. Este capítulo mostra as quatro formas que essa associação assume.

A rota mais simples

Todas as rotas do site público se declaram no routes/web.php. Eis o seu conteúdo acabado de instalar:

<?php

use Illuminate\Support\Facades\Route;

Route::get('/', function () {
    return view('welcome');
});

Esta rota diz o seguinte: quando alguém pede / em método GET, devolve a view welcome, ou seja, o ficheiro resources/views/welcome.blade.php.

O Route::get() recebe dois argumentos: o endereço e aquilo que há a fazer. Este segundo argumento pode assumir várias formas.

Devolver uma string

Route::get('/bonjour', function () {
    return 'Bonjour !';
});

Visita o http://127.0.0.1:8000/bonjour: o navegador mostra o texto em bruto. É útil para verificar que uma rota é mesmo atingida, raramente para mais do que isso.

Devolver uma view

Para confirmares que a view mostrada na página inicial é mesmo a welcome, abre o resources/views/welcome.blade.php e acrescenta uma linha visível em qualquer sítio dentro do <body>:

<h1>Bonjour tout le monde !</h1>

Recarrega a página inicial: o título aparece. Acabaste de alterar uma view sem tocar na rota.

Devolver um controlador

Num projeto a sério, a lógica não vive no ficheiro de rotas mas sim num controlador. A rota limita-se então a designar uma classe e um método:

use App\Http\Controllers\PostController;

Route::get('/article', [PostController::class, 'show']);

O array [PostController::class, 'show'] significa «chama o método show da classe PostController». O controlador ainda não existe: o capítulo seguinte cria-o. Repara no use no topo do ficheiro, que importa a classe. Sem ele, o PHP procura o PostController no espaço de nomes global e não o encontra.

Illuminate\Contracts\Container\BindingResolutionException
Target class [PostController] does not exist.

Os parâmetros do URL

Um blogue precisa de endereços variáveis: /article/mon-premier-article, /article/un-autre. A parte que muda passa a ser um parâmetro, escrito entre chavetas:

Route::get('/article/{slug}', function (string $slug) {
    return "Vous avez demandé l'article : {$slug}";
});

O Laravel captura tudo o que vem a seguir a /article/ e passa-o à função com o nome $slug. O nome do parâmetro no URL e o nome do argumento têm de coincidir.

Podes restringir a forma esperada. Aqui, a rota só responde se o identificador for numérico:

Route::get('/article/{id}', function (int $id) {
    return "Article numéro {$id}";
})->whereNumber('id');

Um URL como /article/bonjour devolve então um erro 404, em vez de chegar ao teu código com um valor inesperado.

As rotas nomeadas

Escrever os URL à mão nos templates é frágil: no dia em que mudares /article/ para /blog/, tens de encontrar cada link. Dar um nome à rota resolve o problema:

Route::get('/article/{slug}', [PostController::class, 'show'])->name('post');

O link constrói-se então a partir do nome, nunca a partir do endereço:

route('post', ['slug' => 'mon-premier-article'])
// http://127.0.0.1:8000/article/mon-premier-article

Numa view Blade, fica assim:

<a href="http://%20route('post',%20$post)%20">{{ $post->title }}</a>

Muda o endereço no web.php e todos os links acompanham. É assim que este tutorial constrói todos os seus links a partir do capítulo 7.

O route model binding

O Laravel sabe ir mais longe. Se o parâmetro tiver o nome de um modelo, a framework vai buscar o registo sozinha:

use App\Models\Post;

Route::get('/article/{post}', function (Post $post) {
    return $post->title;
});

O Laravel lê o segmento do URL, interroga a tabela posts e devolve automaticamente um erro 404 se nada corresponder. Recebes o objeto diretamente, sem escreveres a consulta. Por omissão, a procura faz-se na coluna id; o capítulo 6 mostra como lhe pedir que use o slug.

Este route model binding poupa metade do código habitual de um controlador. É usado por todo o resto do tutorial.

Os outros verbos HTTP

O Route::get() responde aos pedidos de leitura. Para os formulários e as API, o Laravel expõe os outros métodos:

Route::post('/article', [PostController::class, 'store']);
Route::put('/article/{post}', [PostController::class, 'update']);
Route::delete('/article/{post}', [PostController::class, 'destroy']);

Este tutorial só usa o get: as escritas passam pelo painel de administração instalado no capítulo 4.

Ver todas as rotas

Este comando lista aquilo que a tua aplicação sabe servir:

php artisan route:list --except-vendor

No projeto terminado deste tutorial, depois de instalado o painel de administração do capítulo 4, mostra também as rotas do back-office: são declaradas por classes da sua pasta app/Filament, não pelo pacote em si. Para ver apenas as páginas do site, acrescente --except-path=admin:

php artisan route:list --except-vendor --except-path=admin

  GET|HEAD       / .................................... home › IndexController
  GET|HEAD       article/{post} ................... post › PostController@show
  GET|HEAD       categorie/{category} .......... category › CategoryController
  GET|HEAD       etiquette/{tag} ......................... tag › TagController
  GET|HEAD       recherche .................... search › PostController@search

A opção --except-vendor esconde as rotas acrescentadas pelos pacotes instalados, --except-path=admin deixa de fora as do painel de administração, que são mesmo suas. É o primeiro comando a executar quando um endereço devolve 404 apesar de julgar tê-lo declarado.

O capítulo seguinte cria os controladores e as views que estas rotas designam.