Aplicação web com Laravel

Um GET /sessoes precisa de escolher uma operação, consultar sessões e produzir uma resposta. No Laravel, a rota encaminha o pedido, o controlador coordena a operação, o modelo representa dados e relações e a vista produz HTML. Middleware, policies e serviços participam quando a operação exige autenticação, autorização ou regras de negócio.

O recurso Sessões de ponta a ponta

No percurso de um pedido, distingue o software pelo papel:

O servidor pode devolver um ficheiro estático ou obter uma resposta da aplicação. O navegador é o cliente deste percurso. O motor que interpreta e apresenta HTML no navegador não substitui o servidor HTTP.

Um recurso é algo identificável por um endereço, como uma sessão ou a lista de sessões. A aplicação define que operações permite sobre ele. As sessões da loja são um recurso. Estas rotas usam métodos HTTP com a semântica esperada; uma aplicação REST também tem outras condições, explicadas em HTTP:

Route::get('/sessoes', [SessaoController::class, 'index']);
Route::post('/sessoes', [SessaoController::class, 'store'])->middleware('auth');

O GET lista, o POST cria. O controlador recebe o pedido já encaminhado e devolve uma resposta, sem gerar HTML à mão:

// ler não muda nada: pode repetir-se e ficar na história do navegador
Route::get('/sessoes', [SessaoController::class, 'index']);

// escrever muda o estado: exige validação e redirecionamento
Route::post('/sessoes', [SessaoController::class, 'store'])->middleware('auth');

// Excerto: Request, Gate e Sessao são importados no controlador.
class SessaoController extends Controller
{
    public function index()
    {
        $sessoes = Sessao::where('data_hora', '>', now())
            ->orderBy('data_hora')
            ->get();
        return view('sessoes.index', ['sessoes' => $sessoes]);
    }

    public function store(Request $request)
    {
        Gate::authorize('create', Sessao::class);
        $dados = $request->validate([
            'evento_id' => 'required|exists:eventos,id',
            'data_hora' => 'required|date|after:now',
            'preco' => 'required|numeric|min:0',
            'lotacao' => 'required|integer|min:1',
        ]);
        Sessao::create($dados);
        return redirect('/sessoes', 303);
    }
}

O método validate é o ponto a fixar: se os dados cumprirem as regras, devolve os campos validados. Não os sanitiza para todos os destinos. Se falharem num formulário web, interrompe e redireciona com os erros; um pedido que espera JSON recebe normalmente 422. A regra exists:eventos,id repete na aplicação a chave estrangeira da base de dados, para dar erro amigável antes do erro técnico. A regra after:now valida a criação de uma sessão futura. Sessões antigas continuam a existir no histórico.

Este exemplo pressupõe SessaoPolicy associada ao modelo: o seu método create recebe o utilizador autenticado e permite apenas os papéis que podem gerir sessões. Gate é a facade Illuminate\Support\Facades\Gate e recusa com 403 quando a policy não permite; o formulário usa @csrf e apresenta os erros com @error e os valores anteriores com old(...).

Migração e modelo

A tabela nasce de uma migração, código versionado que cria e altera o esquema. Este excerto cria as colunas e a FK da tabela do esquema relacional, com campos adicionais de criação e atualização:

Schema::create('sessoes', function (Blueprint $table) {
    $table->id();
    $table->foreignId('evento_id')->constrained('eventos');
    $table->dateTime('data_hora');
    $table->decimal('preco', 8, 2);
    $table->integer('lotacao');
    $table->timestamps();
});

O excerto de migração não declara os CHECK de preço e lotação. Mantém essas garantias no SQL de PostgreSQL, além da validação do formulário. Se usares o esquema sem created_at e updated_at, o modelo deve declarar public $timestamps = false.

O modelo liga a classe à tabela e declara o que se pode preencher em massa:

class Sessao extends Model
{
    protected $table = 'sessoes';
    protected $fillable = ['evento_id', 'data_hora', 'preco', 'lotacao'];

    public function evento()
    {
        return $this->belongsTo(Evento::class);
    }
}

O nome da tabela é explícito porque as convenções de pluralização não garantem os nomes portugueses do esquema. Os restantes modelos precisam do mesmo cuidado. O belongsTo espelha a associação do UML: cada sessão pertence a um evento. A partir daqui, $sessao->evento->titulo navega da sessão ao evento sem SQL escrito à mão.

Um POST que falha a validação

Com um utilizador autorizado a criar sessões, preenche o formulário de nova sessão com lotação 0 e guarda. O pedido POST /sessoes chega ao store, o validate rejeita lotacao por violar min:1, e o utilizador volta ao formulário com a mensagem de erro junto ao campo e os restantes valores preservados. Nenhuma linha tocou na base de dados, porque a validação correu antes de qualquer escrita.

Se a autorização e a validação passassem, o create inseria a sessão e o redirecionamento voltava à lista. Se dois compradores disputarem o último lugar, a validação anterior à compra pode estar desatualizada. O protocolo de concorrência decide qual compra pode confirmar.

Para isolar a condição «inteiro positivo», o bloco usa um inteiro PHP onde um formulário HTTP enviaria texto, que o validador Laravel também precisa de interpretar:

<?php
function validar($dados) {
    $erros = [];
    if (!isset($dados['lotacao']) || !is_int($dados['lotacao']) || $dados['lotacao'] < 1) {
        $erros['lotacao'] = 'A lotação tem de ser um inteiro a partir de 1.';
    }
    return $erros;
}
$erros = validar(['evento_id' => 3, 'preco' => 10, 'lotacao' => 0]);
foreach ($erros as $campo => $mensagem) {
    echo "$campo: $mensagem
";
}

Num formulário Laravel, o erro é apresentado junto ao campo. O bloco não reproduz a conversão das strings HTTP nem todas as regras do validador.

Na sequência da página da lista, a vista gera HTML no servidor; o navegador recebe esse HTML e decide quando enviar outro pedido.

Entrar e proteger rotas

A loja tem registo e login nos requisitos, e as compras exigem saber quem compra. A autenticação no Laravel segue o mesmo molde do recurso: formulário, validação e tentativa de entrada.

public function entrar(Request $request)
{
    $dados = $request->validate([
        'email' => 'required|email',
        'palavra_passe' => 'required',
    ]);
    if (!Auth::attempt([
        'email' => $dados['email'],
        'password' => $dados['palavra_passe'],
    ])) {
        return back()->withErrors([
            'email' => 'Credenciais inválidas.',
        ]);
    }
    $request->session()->regenerate();
    return redirect('/sessoes');
}

Este fragmento pressupõe o modelo autenticável e a coluna password do starter Laravel. Para usar utilizadores.palavra_passe_hash do esquema anterior, configura o provider e o modelo para essa tabela e esse atributo de hash. A chave password das credenciais continua a receber a palavra-passe em claro para a API a verificar. Não passes o hash como credencial.

O Auth::attempt verifica a palavra-passe com hash e inicia a sessão. Se falhar, volta atrás com erro genérico de propósito: dizer “email certo, palavra-passe errada” ajuda quem ataca a adivinhar contas.

Com a entrada feita, protege as rotas que precisam de comprador autenticado com o middleware auth:

Route::middleware('auth')->group(function () {
    Route::post('/compras', [CompraController::class, 'store']);
});

Quem não entrou é redirecionado para o login em vez de chegar ao controlador. A autorização sobre a operação e o recurso precisa de uma policy, gate ou verificação equivalente no servidor.

Ambiente e ferramentas

O ambiente do projeto usa PHP e Laravel para a aplicação, Composer para as dependências, PostgreSQL para os dados e Docker Compose para a infraestrutura local. Git e GitLab guardam versões e permitem rever as alterações do grupo. Usa o template e o guia da edição atual, ligados na apresentação da cadeira.

Uma imagem Docker descreve o sistema de ficheiros e a configuração que servem para criar contentores. Um contentor é uma instância em execução dessa imagem. Um volume conserva os dados fora da camada descartável do contentor. Parar ou recriar o contentor não é o mesmo que apagar o volume da base de dados.

Blade: gerar uma vista

view('sessoes.index', ['sessoes' => $sessoes]) passa os dados à vista resources/views/sessoes/index.blade.php. Blade compila o template para PHP:

<ul>
  @foreach ($sessoes as $sessao)
    <li>{{ $sessao->evento->titulo }}: {{ $sessao->data_hora }}</li>
  @endforeach
</ul>

@foreach repete o elemento para cada sessão. {{ ... }} escreve texto escapado para HTML. O acesso a evento precisa da relação do modelo e pode provocar consultas adicionais, como veremos no caso N+1.

Ler o âmbito de uma variável em PHP

Uma variável global não fica automaticamente disponível numa função nomeada. Os parâmetros e variáveis locais pertencem à chamada. No programa abaixo, a $taxa local de calcular vale 1; a global continua a valer 4.

<?php
$taxa = 4;

function calcular($base) {
    $taxa = 1;
    return $base + $taxa;
}

function aumentarTaxa() {
    global $taxa;
    $taxa++;
}

echo calcular(10) . PHP_EOL;
echo $taxa . PHP_EOL;
aumentarTaxa();
echo $taxa . PHP_EOL;

$ajustar = fn($n) => $n + $taxa;
$taxa = 9;
echo $ajustar(10) . PHP_EOL;

global $taxa em aumentarTaxa liga o nome local à variável global e permite alterá-la. A função arrow captura o valor 5 ao ser criada; mudar depois a global para 9 não muda essa captura. Uma closure escrita com function precisa de use ($taxa) para essa captura por valor, ou use (&$taxa) para uma referência.

Ler uma variável local não definida gera um aviso no PHP atual; não soma silenciosamente a global do mesmo nome. Ao prever uma saída, começa por identificar onde cada nome foi definido. Para aplicações, passar dados explicitamente torna as dependências da função mais fáceis de seguir.

Separar responsabilidades no pedido

Uma rota escolhe a operação. Middleware pode verificar sessão e proteção CSRF antes do controlador. O controlador coordena o caso de uso, a policy decide a autorização, o modelo representa dados e relações, e a vista produz a representação. Nem todos os pedidos usam uma vista HTML: uma API pode devolver JSON, e uma operação pode redirecionar ou devolver 204.

Validação pergunta se os dados têm o formato e o domínio esperados. Autorização pergunta se esta pessoa pode executar esta operação sobre este objeto. Autenticação identifica a pessoa. As três são necessárias em contextos diferentes e nenhuma substitui as restantes.

public function atualizar(Request $request, Bilhete $bilhete)
{
    Gate::authorize('update', $bilhete);
    $dados = $request->validate(['estado' => 'required|in:reservado,pago,cancelado']);
    // A transição de estado e a capacidade exigem ainda a regra de negócio.
    return $this->servicoCompras->alterarEstado($bilhete, $dados['estado']);
}

Este fragmento usa a facade Gate e mostra a separação; pressupõe uma policy e um serviço com o protocolo de compra definido. Autorizar uma alteração não torna válida qualquer transição. Por exemplo, passar de cancelado a pago pode exigir voltar a reservar capacidade.

ORM e o problema N+1

Se carregares 100 sessões e, num ciclo, acederes a $sessao->evento, o carregamento preguiçoso pode fazer uma consulta inicial e mais 100 consultas. É o problema N+1. Carregamento antecipado, como Sessao::with('evento')->get(), pode carregar as relações em consultas agrupadas. Mede as consultas e os dados transferidos; antecipar todas as relações sem necessidade também custa recursos.

O mesmo cuidado aplica-se a verificações de autorização dentro de ciclos: um @can por linha numa lista pode reavaliar a policy para cada objeto e repetir consultas que a decisão usa. Quando a decisão é igual para todas as linhas, avalia-a uma vez fora do ciclo; quando depende de cada objeto, confirma que as relações usadas pela policy já vêm carregadas. Uma verificação barata em isolamento pode dominar o tempo da página quando é repetida cem vezes.

O modelo não é a página. Não coloques decisões de autorização só no template: um pedido direto pode contorná-lo. Não aceites campos privilegiados só porque estão no $fillable; esse atributo limita a atribuição em massa, não determina quem pode alterar cada valor.

Resposta e proteção de dados

Usa parâmetros para valores nas consultas; valida escolhas de coluna e direção de ordenação por uma lista explícita. Escapa dados na vista e usa proteção CSRF nas rotas de alteração que recebem cookies. Quando a base de dados recusar uma regra conhecida, traduz o resultado para uma resposta útil sem expor SQL, credenciais ou stack traces.

Uma atualização feita em vários modelos pode precisar de DB::transaction(...), mas só envolver código nessa função não resolve a corrida do último lugar. Aplica também a coordenação de transações.

Onde cada falha aparece no percurso

Os caminhos abaixo partem de POST /sessoes num formulário web. Cada recusa interrompe o percurso; o mesmo pedido não atravessa todas as falhas.

Num cliente que espera JSON, autenticação e validação podem devolver 401 e 422 em vez de redirecionar. O contrato da resposta precisa de declarar essa diferença.

Validar uma funcionalidade num protótipo vertical

Um protótipo vertical implementa um percurso através de todas as camadas. Uma lista desenhada com dados fixos pode validar a disposição da interface, mas não demonstra que a aplicação consulta, autoriza ou altera os dados. A8 serve para experimentar a arquitetura com funcionalidades do projeto; as histórias obrigatórias vêm dos requisitos e checklists da edição atual.

Para a história de cancelar uma reserva, liga os artefactos ao mesmo comportamento:

Um contrato possível usa POST /bilhetes/{id}/cancelamento. Num formulário web, a ação processa e redireciona para uma página de resultado, preservando os dados necessários em caso de erro. Uma operação AJAX pode devolver JSON e códigos de falha, desde que isso conste do contrato e o cliente os interprete. Não devolvas um redirecionamento para HTML a um cliente que espera sempre o JSON de um bilhete.

Para verificar o percurso, começa com uma reserva de U7 e zero lugares livres. Entra como U7, cancela e confirma na interface e nos dados que o estado mudou e há um lugar livre. Recarrega: a alteração deve persistir. Repete: não deve libertar outro lugar. Com U8, um pedido direto ao mesmo endereço deve ser recusado, mesmo que o botão nem exista na sua página.

Depois verifica uma sessão esgotada, uma falha técnica e o retorno ao formulário. Uma mensagem de sucesso isolada não prova a escrita, e uma consulta bem-sucedida não prova autorização. Este é um percurso didático; não substitui as restantes histórias exigidas para o protótipo nem a verificação do produto no ambiente indicado pela cadeira.