Skip to content

4. A view e seu modelo

Até aqui, as actions geraram suas próprias respostas: texto, JSON e algumas tags HTML escritas como uma cadeia de caracteres. Em uma aplicação MVC, esse é o papel de uma view: um arquivo que descreve a página HTML, com marcadores para os dados que a action lhe transmite, o modelo da view.

[Laravel] vem com seu próprio engine de views, o [Blade]. Uma view [Blade] é um arquivo cujo nome termina com [.blade.php], armazenado na pasta [resources/views] da aplicação. É um arquivo de texto, neste caso HTML, no qual três tipos de tags são interpretados no servidor:

  • [{{ expression }}]: o valor de uma expressão [PHP], inserido na página;
  • [@instruction]: uma diretiva: condição ([@if]), laço ([@foreach]), herança de template ([@extends], [@section]), inclusão ([@include])... Uma diretiva começa com [@], seguido de seu nome;
  • [{{-- commentaire --}}]: um comentário, que não aparece na página gerada.

Todo o resto é copiado tal como está. As expressões são escritas em [PHP]: não há uma segunda linguagem para aprender. O [Blade] se parece, assim, com o [Razor], o engine de views do [ASP.NET Core MVC], que também mistura HTML e código e também usa o caractere [@]; ele difere do [Thymeleaf] ([Spring MVC]), cujas views são arquivos HTML válidos enriquecidos com atributos [th:]. Uma view [Blade] não é executada tal como está: no primeiro uso, o [Blade] a compila em um arquivo [PHP] padrão, armazenado em [storage/framework/views], que ele então reutiliza enquanto a view não for alterada. Veremos a aparência desse arquivo.

4.1. Exemplo 13: Uma primeira view

13-first-view/
├── app/
│   ├── Http/
│   │   └── Controllers/
│   │       └── ViewsController.php
│   └── Models/
│       └── PageModel.php
├── resources/
│   └── views/
│       └── views/
│           ├── unknown.blade.php
│           └── index.blade.php
├── routes/
│   └── web.php
└── ...

4.1.1. O modelo da view: app/Models/PageModel.php

<?php
// app/Models/PageModel.php: o modelo da view, os dados que a action passa à view

namespace App\Models;

readonly class PageModel
{
    public function __construct(
        public string $title,
        public string $message,
        public string $time,
    ) {
    }
}

O modelo da view é uma classe simples e imutável (veja o exemplo 03): as três informações que a view exibirá. Não é obrigatório definir o modelo de uma view como uma classe: seria possível passar três variáveis separadas para a view. No entanto, uma classe documenta o que a view espera e permite que o editor verifique o código da action. Essa é a abordagem que o estudo de caso seguirá, em que cada view tem sua própria classe de modelo.

4.1.2. O controller: app/Http/Controllers/ViewsController.php

<?php
// app/Http/Controllers/ViewsController.php: actions que retornam uma VIEW

namespace App\Http\Controllers;

use App\Models\PageModel;
use Illuminate\Http\Response;
use Illuminate\View\View;

class ViewsController
{
    // view: a engine Blade constrói a página a partir da view
    // resources/views/views/index.blade.php e das variáveis passadas no
    // array (aqui uma só, [model]); a página produzida é a resposta da action
    public function index(): View
    {
        $model = new PageModel(
            'My first view',
            'This page was built by Blade, on the server.',
            date('H:i:s'));
        return view('views.index', ['model' => $model]);
    }

    // a mesma view com outro modelo; ou outra view, com o código 404
    public function hello(string $name): View|Response
    {
        if ($name === 'unknown') {
            // a página, enviada com o código 404
            return response()->view('views.unknown', ['name' => $name], 404);
        }
        $model = new PageModel(
            "Hello $name",
            'This time, the title of the page comes from the URL.',
            date('H:i:s'));
        return view('views.index', ['model' => $model]);
    }
}
  • linhas 17–20: a action constrói o modelo da view. A função ***[date] do *[PHP] formata a hora atual: [H] para as horas, [i] para os minutos e [s]** para os segundos;
  • linha 21: a função [view] faz com que o [Blade] gere a página. O primeiro parâmetro é o nome da view: o caminho do arquivo, relativo à pasta [resources/views], em que as [/]s são substituídas por pontos e sem a extensão [.blade.php]: [views.index] refere-se ao arquivo [resources/views/views/index.blade.php]. O segundo parâmetro é um array associativo, em que cada chave se torna uma variável na view, neste caso uma só: [$model]. [view] retorna um objeto [View], que o [Laravel] transforma em uma resposta (do tipo [text/html]) ao gerar a página;
  • linha 29: outra view, com uma variável diferente ([$name]). [response()->view(...)] gera uma resposta a partir de uma view, com o código especificado, neste caso 404, para exibir uma página de erro personalizada. O tipo da action [View|Response] significa: ou uma [View] ou uma [Response];
  • linhas 31–35: a mesma view da action [index], mas com um modelo diferente. Esse é o benefício de separar as actions das views: uma mesma view pode ser usada por várias actions.

4.1.3. A view: resources/views/views/index.blade.php

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  {{-- {{ ... }}: the value of an expression, inserted into the page --}}
  <title>{{ $model->title }}</title>
</head>
<body>
  <h1>{{ $model->title }}</h1>
  <p>{{ $model->message }}</p>
  <p>Page built at {{ $model->time }}.</p>
</body>
</html>
  • linha 5: um comentário [Blade];
  • linha 6: [{{ $model->title }}] insere o valor da propriedade [title] da variável [$model]. Entre as chaves duplas, é possível escrever qualquer expressão [PHP].

Tudo o que é inserido por [{{ }}] é escapado: os caracteres [<], [>], [&], ["] e ['] são substituídos por suas entidades HTML. Esse é o papel que a função [e] desempenhava no exemplo 09, mas desta vez de forma automática: uma view, portanto, não pode inserir inadvertidamente na página o HTML fornecido por um usuário.

4.1.4. A view: resources/views/views/unknown.blade.php

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Unknown</title>
</head>
<body>
  <h1>Nobody is called [{{ $name }}] here.</h1>
</body>
</html>

Uma view não precisa receber um objeto: a variável [$name] é uma string.

4.1.5. Execução

Image

Image

A hora exibida está em Tempo Universal Coordenado (UTC), pois o fuso horário padrão do [Laravel] é esse; o estudo de caso mostrará como alterá-lo. A saída bruta mostra o processamento realizado pelo [Blade]: as tags [{{ }}] foram substituídas por seus valores, e o comentário foi removido (resta uma linha em branco em seu lugar).

curl -i http://localhost:8000/
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">

  <title>My first view</title>
</head>
<body>
  <h1>My first view</h1>
  <p>This page was built by Blade, on the server.</p>
  <p>Page built at 16:04:07.</p>
</body>
</html>

A página de erro “home”, seguida de um nome que contém HTML ([<b>martin], codificado na URL):

curl -i http://localhost:8000/hello/unknown
curl http://localhost:8000/hello/%3Cb%3Emartin
HTTP/1.1 404 Not Found
Content-Type: text/html; charset=utf-8

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Unknown</title>
</head>
<body>
  <h1>Nobody is called [unknown] here.</h1>
</body>
</html>
...
  <title>Hello &lt;b&gt;martin</title>
...
  <h1>Hello &lt;b&gt;martin</h1>
...

A tag [<b>] foi escapada, embora nem a action nem a view tivessem qualquer relação com isso. Eis, por fim, a view compilada pelo [Blade], tal como encontrada na pasta [storage/framework/views] (com um nome calculado, como [bfadc851307fb914e48325630a6c9191.php]):

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">

  <title><?php echo e($model->title); ?></title>
</head>
<body>
  <h1><?php echo e($model->title); ?></h1>
  <p><?php echo e($model->message); ?></p>
  <p>Page built at <?php echo e($model->time); ?>.</p>
</body>
</html>
<?php /**PATH .../13-first-view/resources/views/views/index.blade.php ENDPATH**/ ?>

Cada [{{ expression }}] se tornou [<?php echo e(expression); ?>]: a conversão é realizada pela função [e] do exemplo 09. Uma view [Blade] é, portanto, apenas uma forma mais elegante de escrever um arquivo [PHP] que gera HTML. [PHP] foi originalmente concebido como uma linguagem de páginas, em que o código é inserido no arquivo HTML entre [<?php] e [?>]; o [Blade] mantém sua eficiência e corrige suas falhas (notadamente a ausência de escape).

4.2. Exemplo 14: A linguagem Blade

Este exemplo reúne as principais construções do [Blade] em uma única view.

4.2.1. O modelo e a action

O modelo da view é descrito por três classes imutáveis, cada uma em seu próprio arquivo (o [PHP] não exige uma classe por arquivo, mas o carregador de classes do [Composer] procura a classe [App\Models\Product] no arquivo [app/Models/Product.php]):

<?php
// app/Models/Product.php: um produto

namespace App\Models;

readonly class Product
{
    public function __construct(
        public string $name,
        public float $price,
        public bool $inStock,
    ) {
    }
}
<?php
// app/Models/Address.php: um endereço

namespace App\Models;

readonly class Address
{
    public function __construct(
        public string $street,
        public string $city,
    ) {
    }
}
<?php
// app/Models/BasicsModel.php: o modelo da view do exemplo 14

namespace App\Models;

readonly class BasicsModel
{
    /**
     * @param list<Product> $products
     * @param list<Product> $cart
     */
    public function __construct(
        public string $title,
        public string $name,
        public ?string $nickname,
        public string $html,
        public bool $loggedIn,
        public string $currency,
        public array $products,
        public array $cart,
        public Address $address,
    ) {
    }
}

O modelo contém valores de vários tipos: strings, [null], booleanos, arrays de objetos, arrays vazios e objetos que contêm outros objetos. Os preços aqui são do tipo [float], para simplificar os cálculos na view (o exemplo 06 mostrou por que se prefere um decimal exato).

<?php
// app/Http/Controllers/BasicsController.php: uma view que usa as principais construções do Blade

namespace App\Http\Controllers;

use App\Models\Address;
use App\Models\BasicsModel;
use App\Models\Product;
use Illuminate\View\View;

class BasicsController
{
    public function index(): View
    {
        $model = new BasicsModel(
            title: 'Blade basics',
            name: 'Martin',
            nickname: null,
            html: '<b>this is HTML</b>',
            loggedIn: true,
            currency: '€',
            products: [
                new Product('Keyboard', 25, true),
                new Product('Mouse', 12.5, false),
                new Product('Screen', 149, true),
            ],
            cart: [],
            address: new Address('12 rue des Lilas', 'Angers'));
        return view('basics.index', ['model' => $model]);
    }
}

A action constrói o modelo usando parâmetros nomeados (veja o exemplo 01): cada valor é precedido pelo nome do parâmetro a que se destina, o que torna a chamada legível apesar do número de parâmetros.

4.2.2. A view: resources/views/basics/index.blade.php

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>{{ $model->title }}</title>
</head>
<body>
  {{-- PHP code in the view, between the two instructions that follow; here, two variables --}}
  @php
    $total = collect($model->products)->sum('price');
    $count = count($model->products);
  @endphp
  <h1>{{ $model->title }}</h1>
  {{-- 1. display a value of the model; null is displayed as an empty string;
       the ?? operator replaces a null value. This Blade comment does not appear
       in the produced page --}}
  <p>1. Name: {{ $model->name }} - nickname: [{{ $model->nickname }}] [{{ $model->nickname ?? 'none' }}]</p>
  {{-- 2. {{ }} escapes HTML; {!! !!} inserts it as is --}}
  <p>2a. {{ $model->html }}</p>
  <p>2b. {!! $model->html !!}</p>
  {{-- 3. a condition --}}
  @if ($model->loggedIn)
    <p>3. You are logged in.</p>
  @else
    <p>3. You are not logged in.</p>
  @endif
  {{-- 4. a loop: $loop describes the state of the loop --}}
  <p>4. Our products:</p>
  <ul>
    @foreach ($model->products as $product)
      <li>no. {{ $loop->index }}: {{ $product->name }}, {{ $product->price }} {{ $model->currency }}
        {{ $product->inStock ? '(in stock)' : '(sold out)' }}
        @if ($loop->first) - the first one @endif
        @if ($loop->last) - the last one, seen by {{ $model->name }} @endif
      </li>
    @endforeach
  </ul>
  {{-- 5. the empty list: @forelse ... @empty --}}
  <p>5. Your cart:
    @forelse ($model->cart as $p)<span>{{ $p->name }}</span>@empty it is empty. @endforelse
  </p>
  {{-- 6. computed expressions, the @php variables, and number_format --}}
  <p>6. {{ $count }} products, for a total of {{ $total }} {{ $model->currency }};
    average price: {{ number_format($total / $count, 2, '.', ',') }} {{ $model->currency }}</p>
  {{-- 7. an object inside an object, and a PHP function (mb_strtoupper) --}}
  <p>7. Address: {{ $model->address->street }}, {{ mb_strtoupper($model->address->city) }}</p>
  {{-- 8. @ is a Blade instruction only at the start of a word; @@ writes an @ --}}
  <p>8. An email address: contact@example.com; a displayed instruction: @@if</p>
</body>
</html>
  • linhas 9–12: as diretivas [@php] e [@endphp] delimitam um bloco de código [PHP], executado neste ponto da página. Duas variáveis da view são criadas ali: o preço total, calculado pelo método [sum] de uma coleção (exemplo 03), que soma uma propriedade de cada elemento, e o número de produtos. O bloco [@php] deve ser reservado para esse tipo de preparação: o cálculo normalmente pertence à action;
  • linha 17: um valor [null] é exibido como uma string vazia. O operador [??] do [PHP] (exemplo 08) substitui um valor [null] por um valor padrão;
  • linhas 19–20: [{{ }}] escapa o HTML (2a); [{!! !!}], por outro lado, insere o valor tal como está, sem escapá-lo (2b). [{!! !!}] é reservado para o HTML gerado pela própria aplicação, nunca para dados digitados por usuários;
  • linhas 22–26: uma condição: [@if], [@elseif], [@else], [@endif], com uma condição [PHP] entre parênteses. Cada bloco é fechado por uma diretiva [@end...];
  • linhas 30–36: um laço [@foreach] ... [@endforeach], escrito como o laço [foreach] do [PHP]. Dentro dele, a variável especial [$loop] descreve o estado do laço: [$loop->index] (o número da iteração, começando em 0), [$loop->iteration] (começando em 1), [$loop->first], [$loop->last] (verdadeiro na primeira e na última iteração), [$loop->count] (o número de elementos). As variáveis externas ao laço ([$model->name]) continuam acessíveis;
  • linha 32: o operador ternário do [PHP], [condition ? a : b] (exemplo 11);
  • linha 40: a diretiva [@forelse] ... [@empty] ... [@endforelse] é um laço em que o bloco [@empty] é executado se a lista estiver vazia. Isso é mais simples do que um [@if] que testasse o tamanho da lista;
  • linhas 43–44: expressões calculadas ([$total / $count]) e as variáveis do bloco [@php]. A função [number_format] do [PHP] formata um número: duas casas decimais, um ponto como separador decimal e uma vírgula como separador de milhares. No exemplo 16, veremos uma forma muito melhor de formatar números e valores monetários;
  • linha 46: o operador [->] percorre os objetos ([$model->address->city]), e qualquer função do [PHP] pode ser chamada: [mb_strtoupper] converte uma string em maiúsculas (as funções [mb_...], de *multi-byte*, tratam corretamente os caracteres acentuados codificados em UTF-8);
  • linha 48: o caractere [@] só é interpretado pelo [Blade] no início de uma palavra; em um endereço de e-mail, ele é copiado tal como está. Para escrever um [@] seguido do nome de uma diretiva, ele é duplicado: [@@if] produz [@if]. Da mesma forma, [@{{ ... }}] produz [{{ ... }}], o que é útil quando uma página contém chaves destinadas a um framework [JavaScript].

Uma observação sobre comentários: [Blade] processa [@php] os blocos antes dos comentários. Um comentário que contenha a palavra [@php] seria, portanto, interpretado como o início de um bloco de código, com resultados inesperados: é por isso que o comentário da linha 8 não a inclui.

4.2.3. Execução

Image

A página gerada:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Blade basics</title>
</head>
<body>

    <h1>Blade basics</h1>

  <p>1. Name: Martin - nickname: [] [none]</p>

  <p>2a. &lt;b&gt;this is HTML&lt;/b&gt;</p>
  <p>2b. <b>this is HTML</b></p>

      <p>3. You are logged in.</p>

  <p>4. Our products:</p>
  <ul>
          <li>no. 0: Keyboard, 25 €
        (in stock)
         - the first one               </li>
          <li>no. 1: Mouse, 12.5 €
        (sold out)
                      </li>
          <li>no. 2: Screen, 149 €
        (in stock)
                 - the last one, seen by Martin       </li>
      </ul>

  <p>5. Your cart:
     it is empty.   </p>

  <p>6. 3 products, for a total of 186.5 €;
    average price: 62.17 €</p>

  <p>7. Address: 12 rue des Lilas, ANGERS</p>

  <p>8. An email address: contact@example.com; a displayed instruction: @if</p>
</body>
</html>

Os comentários e as diretivas desapareceram, mas deixam para trás seus espaços e quebras de linha: [Blade] não tenta produzir um HTML bem formatado. Isso não tem consequência: o navegador ignora esses caracteres de espaço em branco. Um número do tipo [float] inserido em uma string é escrito com ponto decimal ([12.5]); [number_format] usa os separadores que lhe são passados.

4.3. Exemplo 15: templates, fragmentos, arquivos estáticos

As páginas de um site costumam compartilhar a mesma estrutura: um cabeçalho, uma barra de navegação, um rodapé e as mesmas folhas de estilo. Em vez de repetir essa estrutura em cada view, ela é escrita uma só vez em um template (*layout*), que as páginas estendem. Este exemplo também usa [Bootstrap], o framework CSS mais utilizado, para o layout.

15-layout/
├── app/
│   ├── Http/
│   │   └── Controllers/
│   │       └── PagesController.php
│   └── Models/
│       └── Member.php
├── bootstrap/
│   └── app.php
├── public/
│   └── css/
│       └── styles.css
├── resources/
│   └── views/
│       ├── components/
│       │   └── card.blade.php
│       ├── fragments/
│       │   └── navbar.blade.php
│       ├── layout.blade.php
│       └── pages/
│           ├── home.blade.php
│           ├── raw.blade.php
│           └── team.blade.php
├── routes/
│   └── web.php
└── ...

4.3.1. Arquivos estáticos

Uma página HTML referencia outros arquivos: folhas de estilo, scripts [JavaScript] e imagens. Esses arquivos, que o servidor envia tal como estão, são chamados de arquivos estáticos. Com o [Laravel], eles ficam na pasta [public], que o servidor web serve diretamente (exemplo 01): o arquivo [public/css/styles.css] está disponível na URL [/css/styles.css], sem que o [Laravel] esteja envolvido.

/* algumas configurações além do Bootstrap */
body {
  background-color: #f5f7fa;
}

/* o rodapé do layout */
.footer {
  margin-top: 2rem;
  font-size: 0.85rem;
  color: #6c757d;
}

/* as mensagens de erro, no final da página, sobre um fundo rosa claro */
.error-area {
  margin-top: 1.5rem;
  padding: 0.75rem 1rem;
  background-color: #fdecef;
  border: 1px solid #f5c2c7;
  border-radius: 0.375rem;
  color: #842029;
}

Algumas regras CSS adicionais além das do [Bootstrap]: um fundo cinza-claro, o estilo do rodapé e o estilo de uma área de erro que será usada nos exemplos seguintes.

[Bootstrap] é usado nos exemplos 15 a 28. Em vez de colocar uma cópia na pasta [public] de cada exemplo, os exemplos o compartilham: ele fica na pasta [examples/common/bootstrap]. Essa pasta não é servida pelo servidor web: uma rota, comum a todos esses exemplos, serve seus arquivos. Ela é descrita pelo arquivo [examples/common/bootstrap.php]:

<?php
// common/bootstrap.php: uma rota que serve os arquivos do Bootstrap, compartilhada pelos
// exemplos 15 a 28 (a pasta examples/common/bootstrap), sob a URL /bootstrap/...

use Illuminate\Support\Facades\Route;

Route::get('bootstrap/{file}', function (string $file) {
    $folder = realpath(__DIR__.'/bootstrap');
    // realpath: o caminho absoluto do arquivo solicitado, sem o . e o .. ; false
    // se o arquivo não existir
    $path = realpath($folder.'/'.$file);
    // um arquivo que existe e que está de fato DENTRO da pasta (sem ../ para sair dela)
    abort_unless($path && str_starts_with($path, $folder.DIRECTORY_SEPARATOR)
        && is_file($path), 404);
    // o tipo do arquivo, a partir de sua extensão
    $types = ['css' => 'text/css', 'js' => 'text/javascript', 'map' => 'application/json'];
    $type = $types[pathinfo($path, PATHINFO_EXTENSION)] ?? 'application/octet-stream';
    return response()->file($path, ['Content-Type' => $type]);
})->where('file', '.*')->name('bootstrap');
  • linha 7: uma rota cuja ação é uma função anônima (exemplo 01). O parâmetro de rota [{file}] aceita qualquer final de caminho, inclusive barras (restrição [.*], linha 19, veja o exemplo 02): a URL [/bootstrap/css/bootstrap.min.css] refere-se ao arquivo [css/bootstrap.min.css] da pasta. A rota se chama [bootstrap];
  • linhas 8–14: servir arquivos designados por uma URL exige uma precaução: uma URL como [/bootstrap/../../15-layout/.env] não deve dar acesso a um arquivo localizado fora da pasta. A função [realpath] do [PHP] calcula o caminho absoluto de um arquivo, sem seus componentes [.] e [..], ou retorna [false] se o arquivo não existir. Verificamos que o caminho resultante realmente começa com o caminho da pasta ([str_starts_with]) e que ele se refere a um arquivo ([is_file]); caso contrário, [abort_unless] encerra a requisição com um erro 404. [abort_unless(condition, code)] equivale a [if (! condition) abort(code)]; de modo semelhante, também existe [abort_if]. [DIRECTORY_SEPARATOR] é o separador de caminhos do sistema: [\] no [Windows], [/] nos demais;
  • linhas 16–18: [response()->file] gera uma resposta que envia o conteúdo de um arquivo. O tipo de conteúdo é escolhido com base na extensão do arquivo (fornecida por [pathinfo]), de modo que uma folha de estilo seja declarada corretamente como [text/css]: um navegador rejeita uma folha de estilo declarada com outro tipo.

A rota é declarada pelo arquivo [bootstrap/app.php] de cada exemplo:

<?php
// bootstrap/app.php: a aplicação do exemplo 15

use Illuminate\Foundation\Application;
use Illuminate\Support\Facades\View;

(require __DIR__.'/../../vendor/autoload.php')->addPsr4('App\\', __DIR__.'/../app/');

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        // then: rotas declaradas fora do grupo web (sem sessão nem cookies):
        // a que serve o Bootstrap, compartilhada pelos exemplos 15 a 28
        then: fn () => require __DIR__.'/../../common/bootstrap.php')
    ->withMiddleware()
    ->withExceptions()
    // booted: código executado depois que a aplicação foi iniciada
    ->booted(function () {
        // um "view composer": executado antes da construção de CADA view (*),
        // ele adiciona suas variáveis a todas as views
        View::composer('*', function ($view) {
            $view->with(['path' => request()->path(), 'year' => date('Y')]);
        });
    })
    ->create();
  • linhas 11–14: o parâmetro [then] de [withRouting] é uma função, chamada depois que as rotas de [routes/web.php] foram declaradas, para declarar rotas adicionais. Elas não fazem parte do grupo [web]: não têm sessão nem cookies, o que é adequado para arquivos estáticos. A função de seta executa o arquivo [common/bootstrap.php];
  • linhas 18–24: o método [booted] registra uma função que é executada depois que a aplicação é iniciada;
  • linhas 21–23: a fachada [View] registra um view composer: uma função que o [Laravel] executa antes de renderizar cada view cujo nome corresponda ao padrão indicado, neste caso [*] (todas). Ela recebe a view e pode adicionar variáveis a ela ([with]). Aqui, [$path] (o caminho da URL solicitada, fornecido por [request()], a requisição atual) e [$year] (o ano atual) ficam assim disponíveis em todas as views, sem que as ações precisem fornecê-los. O template os usa no rodapé. O método [View::share('name', value)] compartilharia de forma semelhante um valor fixo com todas as views.

4.3.2. O template: resources/views/layout.blade.php

<!doctype html>
{{-- the layout of the pages: the pages EXTEND it, and fill its sections --}}
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {{-- @yield: a slot that the page can fill; here with a default content --}}
  <title>@yield('title', 'Home') - My site</title>
  {{-- route(): the URL of the [bootstrap] named route; asset(): the URL of a file of public/ --}}
  <link rel="stylesheet" href="{{ route('bootstrap', 'css/bootstrap.min.css') }}">
  <link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
  <div class="container py-3">
    {{-- insertion of the fragments/navbar.blade.php file --}}
    @include('fragments.navbar')
    <main>
      {{-- the content of the page requested by the action is inserted here --}}
      @yield('content')
    </main>
    {{-- $path, $year: added to all the views (see bootstrap/app.php) --}}
    <footer class="footer">Page [{{ $path }}] - © {{ $year }}</footer>
  </div>
</body>
</html>
  • linha 6: a tag [viewport] instrui os navegadores móveis a exibir a página na largura da tela, que é o que o [Bootstrap] espera;
  • Linha 8: a diretiva [@yield] marca um espaço nomeado, que as páginas que estendem o template podem preencher, com uma seção de mesmo nome. O segundo parâmetro é o conteúdo padrão do espaço, usado por uma página que não fornece a seção;
  • Linhas 10–11: [route('bootstrap', 'css/bootstrap.min.css')] gera a URL da rota nomeada [bootstrap] (exemplo 04), usando o valor de seu parâmetro [{file}]. A função [asset] cria a URL de um arquivo da pasta [public]. Escrever a URL do arquivo manualmente ([/css/styles.css]) também funcionaria, mas [asset] continua funcionando se a aplicação estiver instalada sob um prefixo de URL;
  • linha 16: [@include] insere o conteúdo de outra view, neste caso a barra de navegação. A view incluída tem acesso às variáveis da view que a inclui;
  • linha 19: a área que cada página preenche com seu próprio conteúdo;
  • linha 22: o rodapé usa as duas variáveis do view composer.

A classe [container] do [Bootstrap] centraliza o conteúdo e limita sua largura; [py-3] adiciona um preenchimento vertical: o [Bootstrap] fornece centenas de classes como essa, que são combinadas no atributo [class].

4.3.3. A barra de navegação: resources/views/fragments/navbar.blade.php

1
2
3
4
5
6
7
8
9
{{-- a fragment: a piece of page, inserted by @include --}}
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <span class="navbar-brand">My site</span>
  <div class="navbar-nav">
    <a class="nav-link" href="/">Home</a>
    <a class="nav-link" href="/team">Team</a>
    <a class="nav-link" href="/raw">Page without layout</a>
  </div>
</nav>

Um fragmento: um pedaço de página que não tem significado por si só. As classes [navbar], [navbar-brand] e [nav-link] são as da barra de navegação do [Bootstrap].

4.3.4. Um componente: resources/views/components/card.blade.php

1
2
3
4
5
6
7
8
{{-- a COMPONENT: a piece of page that has parameters, like a function --}}
@props(['name', 'role'])
<div class="card">
  <div class="card-body">
    <h5 class="card-title">{{ $name }}</h5>
    <p class="card-text">{{ $role }}</p>
  </div>
</div>
  • Linha 2: um componente é uma seção de página que tem parâmetros; esta é a função do [Blade]. Um componente anônimo é uma view simples da pasta [resources/views/components]; a diretiva [@props] declara seus parâmetros, que se tornam variáveis da view. Ele é usado como uma tag HTML cujo nome começa com [x-]: [<x-card name="..." role="..." />] insere o fragmento de página gerado com esses valores. Os parâmetros podem ter um valor padrão: [@props(['name', 'role' => ''])]. O cartão ([card]) é um componente do [Bootstrap].

4.3.5. As páginas

{{-- this page EXTENDS the layout: it only provides the content of its sections --}}
@extends('layout')

@section('content')
  <h1>Welcome</h1>
  <p>This page only contains its own content: the header, the navigation
    bar and the footer come from the <code>layout.blade.php</code> layout.</p>
  {{-- the [card] component, with two parameters written on the spot --}}
  <x-card name="A component" role="called with parameters written on the spot" />
@endsection
  • linha 2: a página estende o template: [Blade] gera a página do template, substituindo seus marcadores [@yield] pelas seções definidas pela página. Em uma view que estende um template, o texto escrito fora das seções não aparece na página gerada;
  • Linhas 4–10: a seção [content], que preenche o marcador de mesmo nome. A página não define a seção [title]: o marcador mantém seu conteúdo padrão, “Home”;
  • linha 9: o uso do componente [card]. Os parâmetros são escritos como atributos HTML; seus valores são strings.
@extends('layout')

@section('title', 'Our team')

@section('content')
  <h1>Our team</h1>
  <div class="row g-3">
    @foreach ($members as $member)
      <div class="col-md-4">
        {{-- :name="...": the value of the parameter is a PHP EXPRESSION --}}
        <x-card :name="$member->name" :role="$member->role" />
      </div>
    @endforeach
  </div>
@endsection
  • linha 3: uma seção curta, cujo conteúdo é fornecido como segundo parâmetro;
  • linhas 8–13: um cartão por membro da equipe, em uma grade do [Bootstrap] ([row], [col-md-4]: três colunas em uma tela média ou grande, uma coluna em uma tela estreita);
  • linha 11: um parâmetro cujo nome é precedido por [:] recebe o valor de uma expressão [PHP], e não uma string: [:name="$member->name"].

O controller não introduz nenhum recurso novo:

<?php
// app/Http/Controllers/PagesController.php: três páginas

namespace App\Http\Controllers;

use App\Models\Member;
use Illuminate\View\View;

class PagesController
{
    public function home(): View
    {
        return view('pages.home');
    }

    public function team(): View
    {
        $members = [
            new Member('Marie Pélissier', 'Director'),
            new Member('Jacques Bromard', 'Developer'),
            new Member('Philippe Jandot', 'Graphic designer'),
        ];
        return view('pages.team', ['members' => $members]);
    }

    public function raw(): View
    {
        return view('pages.raw');
    }
}

Por fim, a terceira página não usa o template:

<!doctype html>
{{-- this view does not use the layout: it is a complete page --}}
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Raw page</title>
</head>
<body>
  <p>This page does not use the layout: no Bootstrap, no navigation bar.</p>
  <p><a href="/">Back to home</a></p>
</body>
</html>

4.3.6. Execução

Image

Image

Image

A página da equipe, como recebida pelo navegador (as linhas em branco deixadas por comentários e diretivas foram removidas):

curl http://localhost:8000/team
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Our team - My site</title>
  <link rel="stylesheet" href="http://localhost:8000/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="http://localhost:8000/css/styles.css">
</head>
<body>
  <div class="container py-3">
    <nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <span class="navbar-brand">My site</span>
  <div class="navbar-nav">
    <a class="nav-link" href="/">Home</a>
    <a class="nav-link" href="/team">Team</a>
    <a class="nav-link" href="/raw">Page without layout</a>
  </div>
</nav>
    <main>
        <h1>Our team</h1>
  <div class="row g-3">
          <div class="col-md-4">
        <div class="card">
  <div class="card-body">
    <h5 class="card-title">Marie Pélissier</h5>
    <p class="card-text">Director</p>
  </div>
</div>
      </div>
...
      </div>
    </main>
    <footer class="footer">Page [team] - © 2026</footer>
  </div>
</body>
</html>

O navegador recebeu uma página completa: o template, o fragmento, a página e os componentes foram montados no servidor. Os valores das URLs nas folhas de estilo foram calculados por [route] e [asset]: são URLs absolutas. O caminho da página inicial é [/]; os caminhos das outras páginas são escritos sem barra inicial ([team]): essa é a convenção de [request()->path()]. Você pode verificar que as folhas de estilo estão sendo aplicadas corretamente (a opção [-I] do [curl] exibe apenas os cabeçalhos da resposta):

curl -I http://localhost:8000/bootstrap/css/bootstrap.min.css
curl -I http://localhost:8000/css/styles.css
1
2
3
4
5
6
7
8
9
HTTP/1.1 200 OK
Content-Type: text/css; charset=utf-8
Last-Modified: Sat, 26 Sep 2026 16:04:06 GMT
Content-Length: 232111
Accept-Ranges: bytes
...
HTTP/1.1 200 OK
Content-Type: text/css; charset=UTF-8
Content-Length: 435

O primeiro arquivo foi enviado por nossa rota; o segundo foi enviado diretamente pelo servidor de desenvolvimento, sem passar pelo [Laravel].

4.4. Exemplo 16: helpers

Uma view muitas vezes precisa formatar valores: um valor monetário com sua moeda, uma data por extenso ou um texto em maiúsculas. Esse código não pertence à ação (que não cuida da apresentação) e seria trabalhoso de escrever na view. Em vez disso, ele é escrito em [PHP], em funções que as views chamam: são os helpers da view. O [Blade] oferece várias maneiras de disponibilizá-los: chamar uma função ou um método estático, escrever as próprias diretivas ([@money($price)]) e usar componentes, que já conhecemos.

16-helpers/
├── app/
│   ├── Helpers/
│   │   └── Formats.php
│   ├── Http/
│   │   ├── Controllers/
│   │   │   └── PagesController.php
│   │   └── Middleware/
│   │       └── SetLanguage.php
│   └── Models/
│       └── Product.php
├── resources/
│   └── views/
│       ├── components/
│       │   ├── badge.blade.php
│       │   └── link.blade.php
│       ├── fragments/
│       │   └── navbar.blade.php
│       ├── layout.blade.php
│       └── pages/
│           ├── home.blade.php
│           └── products.blade.php
└── ...

4.4.1. Funções: app/Helpers/Formats.php

<?php
// app/Helpers/Formats.php: funções chamadas pelas views

namespace App\Helpers;

use Brick\Math\BigDecimal;
use Carbon\CarbonInterface;
use Illuminate\Support\Facades\App;
use Illuminate\Support\Number;

class Formats
{
    // "keyboard" -> "KEYBOARD"
    public static function uppercase(?string $text): string
    {
        return $text === null ? '' : mb_strtoupper($text);
    }

    // um valor em uma moeda, no formato do idioma da requisição (veja o middleware
    // SetLanguage): 1149.9 -> "€1,149.90" em inglês, "1 149,90 €" em
    // francês. A extensão intl do PHP conhece as convenções de cada país
    public static function money(BigDecimal $amount, string $currency = 'EUR'): string
    {
        return Number::currency($amount->toFloat(), in: $currency, locale: App::getLocale());
    }

    // uma data por extenso, no idioma da requisição: "Saturday 26 September 2026"
    public static function longDate(CarbonInterface $day): string
    {
        return $day->locale(App::getLocale())->isoFormat('dddd D MMMM YYYY');
    }
}
  • Linhas 14–17: um método estático ([static]): ele é chamado na classe, sem um objeto ([Formats::uppercase('keyboard')]). Ele aceita [null];
  • linhas 22–24: formatação de um valor monetário. Ela depende do idioma: em francês, [1 149,90 €] (espaço para separar os milhares, vírgula decimal, símbolo após o valor); em inglês, [€1,149.90]. A classe [Number] do [Laravel] baseia-se na extensão [intl] do [PHP], que suporta as convenções de todos os países (ela usa dados do projeto Unicode *CLDR*): [Number::currency] formata um valor monetário, com a moeda designada por seu código internacional ([EUR], [USD]). [intl] só consegue formatar números [float]: o decimal é convertido ([toFloat()]), o que é seguro aqui, já que o número não é mais usado em cálculos. O idioma ([fr], [en]) é o da aplicação para a requisição atual, retornado por [App::getLocale()]; veremos quem o define;
  • Linhas 28–30: formatação de uma data [Carbon] (exemplo 12). [locale(...)] retorna uma cópia da data configurada para um idioma específico; [isoFormat] a formata da seguinte maneira: [dddd] escreve o dia da semana por extenso, [D] o dia do mês, [MMMM] escreve o mês por extenso e [YYYY] o ano. [Carbon] traz traduções desses nomes em mais de duzentos idiomas. O tipo [CarbonInterface] aceita todas as datas [Carbon].

4.4.2. O idioma de cada requisição: app/Http/Middleware/SetLanguage.php

<?php
// app/Http/Middleware/SetLanguage.php: o idioma de formatação de cada requisição

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\App;
use Symfony\Component\HttpFoundation\Response;

class SetLanguage
{
    // o parâmetro ?lang=fr da URL, inglês caso contrário
    public function handle(Request $request, Closure $next): Response
    {
        App::setLocale($request->query('lang') === 'fr' ? 'fr' : 'en');
        return $next($request);
    }
}

O idioma de formatação depende da requisição: o parâmetro [?lang=fr] da URL seleciona o francês; o inglês é o idioma padrão. Um middleware (exemplo 03) o define antes de cada ação, por meio de [App::setLocale]: a fachada [App] refere-se à própria aplicação. O idioma definido dessa forma vale apenas para a requisição atual: a requisição seguinte voltará ao idioma de [.env] ([APP_LOCALE], com o inglês como padrão). O capítulo sobre internacionalização usará esse mesmo idioma para traduzir os textos.

4.4.3. Configuração: bootstrap/app.php

<?php
// bootstrap/app.php: a aplicação do exemplo 16

use App\Http\Middleware\SetLanguage;
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Middleware;
use Illuminate\Support\Facades\Blade;

(require __DIR__.'/../../vendor/autoload.php')->addPsr4('App\\', __DIR__.'/../app/');

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        // then: rotas declaradas fora do grupo web (sem sessão nem cookies):
        // a que serve o Bootstrap, compartilhada pelos exemplos 15 a 28
        then: fn () => require __DIR__.'/../../common/bootstrap.php')
    ->withMiddleware(function (Middleware $middleware): void {
        // o idioma de cada requisição (veja app/Http/Middleware/SetLanguage.php)
        $middleware->web(append: SetLanguage::class);
    })
    ->withExceptions()
    ->booted(function () {
        // DIRETIVAS "caseiras": @money($price), @longDate($day). Uma diretiva
        // recebe o TEXTO do seu parâmetro e retorna o código PHP que o substituirá
        Blade::directive('money', fn (string $expression) =>
            "<?php echo e(\\App\\Helpers\\Formats::money($expression)); ?>");
        Blade::directive('longDate', fn (string $expression) =>
            "<?php echo e(\\App\\Helpers\\Formats::longDate($expression)); ?>");
    })
    ->create();
  • Linha 19: o middleware é adicionado ao final do grupo [web]: ele é executado para todas as rotas de [routes/web.php], depois dos middlewares do grupo (sessão, cookies etc.). O exemplo 03 usou [append], que adiciona um middleware global executado para todas as requisições, inclusive as de rotas fora do grupo [web];
  • Linhas 25–28: a fachada [Blade] registra duas diretivas “personalizadas”: [@money(...)] e [@longDate(...)]. Uma diretiva é processada quando a view é compilada (exemplo 13): sua função recebe o texto escrito entre os parênteses (por exemplo, [$product->price, 'USD']) e retorna o código [PHP], que substituirá a diretiva na view compilada. Aqui, é feita uma chamada ao método correspondente de ***[Formats]***, cujo resultado é escapado ([e]***) e escrito ([echo]***). Em uma string delimitada por aspas, [\\] representa uma única [\];
  • as diretivas são registradas em uma função [booted] (exemplo 15) depois que a aplicação é iniciada: a fachada [Blade] só pode ser usada nesse momento.

Como geram código compilado, as diretivas exigem uma precaução: depois de modificar uma diretiva, é preciso limpar as views compiladas (comando [php artisan view:clear]) para que as views sejam recompiladas com a nova versão.

4.4.4. O controller: app/Http/Controllers/PagesController.php

<?php
// app/Http/Controllers/PagesController.php: duas páginas

namespace App\Http\Controllers;

use App\Models\Product;
use Brick\Math\BigDecimal;
use Carbon\CarbonImmutable;
use Illuminate\View\View;

class PagesController
{
    public function home(): View
    {
        return view('pages.home', ['today' => CarbonImmutable::today()]);
    }

    public function products(): View
    {
        return view('pages.products', ['products' => [
            new Product('keyboard', BigDecimal::of('25'), 12),
            new Product('mouse', BigDecimal::of('12.5'), 0),
            new Product('screen', BigDecimal::of('1149.9'), 3),
        ]]);
    }
}

As ações passam valores brutos para as views: uma data ([CarbonImmutable::today()], a data de hoje à meia-noite) e números decimais. A formatação fica por conta das views. A classe [Product] combina um nome, um preço (um [BigDecimal], veja o exemplo 06) e um nível de estoque. As rotas se chamam [home] e [products].

4.4.5. As views

1
2
3
4
5
6
{{-- a component: a link of the navigation bar, which receives the [active]
     class if the current page is under the [path] path. request(): the
     current request, available in all the views; $slot: the content placed
     between the tags of the component --}}
@props(['href', 'path'])
<a @class(['nav-link', 'active' => request()->is($path)]) href="{{ $href }}">{{ $slot }}</a>
  • linha 5: um componente que cria um link na barra de navegação. O link da página atual recebe a classe [active] do [Bootstrap], que o destaca;
  • Linha 6: a diretiva [@class] gera o atributo [class] de uma tag a partir de um array: uma classe escrita sozinha (['nav-link']) está sempre presente; uma classe escrita como chave (['active' => condition]) só está presente se a condição for verdadeira. A função [request()] retorna a requisição atual; seu método [is] compara o caminho da URL com um padrão, em que [*] corresponde a qualquer sequência de caracteres. A variável [$slot] contém o conteúdo entre as tags de abertura e de fechamento do componente ([<x-link ...>Products</x-link>]).
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <span class="navbar-brand">Helpers</span>
  <div class="navbar-nav">
    {{-- 1. a condition written in the view --}}
    <a class="nav-link{{ request()->is('/') ? ' active' : '' }}" href="/">Home</a>
    {{-- 2. the [link] component --}}
    <x-link href="/products" path="products*">Products</x-link>
    {{-- 3. route() builds the URL of a named route; a parameter that is not a
         parameter of the route is added at the end of the URL: /products?lang=fr --}}
    <a class="nav-link" href="{{ route('products', ['lang' => 'fr']) }}">Produits (fr)</a>
  </div>
</nav>
  • linha 5: a mesma coisa, escrita diretamente na view, sem componente, usando o operador ternário. [request()->is('/')] só reconhece a página inicial. O componente evita repetir a condição em cada link;
  • linha 7: o uso do componente;
  • linha 10: um parâmetro de [route] que não é um parâmetro de rota é adicionado à URL como parâmetro de consulta: [/products?lang=fr].
1
2
3
{{-- a Bootstrap badge: green if the product is in stock, red otherwise --}}
@props(['stock'])
<span @class(['badge', 'text-bg-success' => $stock > 0, 'text-bg-danger' => $stock <= 0])>{{ $stock > 0 ? "$stock in stock" : 'sold out' }}</span>
  • Linha 3: um selo do [Bootstrap], verde ([text-bg-success]) ou vermelho ([text-bg-danger]) conforme o estoque, usando [@class]. O texto do selo é escolhido pelo operador ternário; ["$stock in stock"] é uma string interpolada.
@extends('layout')
@section('title', 'Home')

@section('content')
  <h1>Home</h1>
  {{-- the "home-made" @longDate directive --}}
  <p>Today is @longDate($today).</p>
  {{-- app()->getLocale(): the language of the request, set by the SetLanguage middleware --}}
  <p>Formatting language: {{ app()->getLocale() }}
    (<a href="/?lang=fr">in French</a>, <a href="/">in English</a>)</p>
@endsection
  • linha 7: a chamada à diretiva “home”;
  • linha 9: a função [app()] retorna a aplicação, e [getLocale()] retorna seu idioma para a requisição atual.
@extends('layout')
{{-- @use: the equivalent, in a view, of PHP's use instruction --}}
@use('App\Helpers\Formats')
@section('title', 'Products')

@section('content')
  <h1>Products</h1>
  <table class="table table-sm w-auto">
    <thead><tr><th>Product</th><th>Price</th><th>Price in dollars</th><th>Stock</th></tr></thead>
    <tbody>
      @foreach ($products as $product)
        <tr>
          {{-- a static method, then a directive, without then with a parameter --}}
          <td>{{ Formats::uppercase($product->name) }}</td>
          <td>@money($product->price)</td>
          <td>@money($product->price, 'USD')</td>
          {{-- the [badge] component builds the HTML of the badge --}}
          <td><x-badge :stock="$product->stock" /></td>
        </tr>
      @endforeach
    </tbody>
  </table>
@endsection
  • linha 3: a diretiva [@use] importa uma classe para a view, exatamente como a instrução [use] de um arquivo [PHP];
  • linha 14: uma chamada a um método estático, que funciona como uma função;
  • Linhas 15–16: a diretiva [@money], primeiro com sua moeda padrão e depois com um parâmetro;
  • linha 18: o uso do componente [badge].

O template [layout.blade.php] é uma versão simplificada do template do exemplo 15.

4.4.6. Execução

Image

Image

A mesma página, com o parâmetro [?lang=fr]. Apenas a formatação dos números muda; o texto em si está fixo nas views. O capítulo sobre internacionalização também traduzirá o texto.

Image

Um trecho do HTML produzido:

curl "http://localhost:8000/products?lang=en"
1
2
3
4
5
6
7
8
9
...
              <tr>
          <td>KEYBOARD</td>
          <td>€25.00</td>
          <td>$25.00</td>
          <td><span class="badge text-bg-success">12 in stock</span>
</td>
        </tr>
...

4.5. Exemplo 17: um formulário GET

Um formulário HTML envia seus campos ao servidor de uma de duas maneiras, dependendo de seu atributo [method]:

  • [method="get"]: os campos são adicionados à URL como parâmetros ([/search?keyword=le&genre=novel]). Esse é o método usado por um formulário que faz uma consulta: uma busca ou um filtro. A URL que contém os resultados pode ser salva nos favoritos, compartilhada ou recarregada com segurança;
  • [method="post"]: os campos são incluídos no corpo da requisição (veja o exemplo 11). Esse é o método usado por um formulário que modifica dados: um cadastro, uma inclusão ou uma exclusão.

Este primeiro formulário é uma busca de livros.

4.5.1. O modelo: app/Models/Book.php e SearchModel.php

<?php
// app/Models/Book.php: um livro

namespace App\Models;

readonly class Book
{
    public function __construct(
        public string $title,
        public string $author,
        public string $genre,
    ) {
    }
}
<?php
// app/Models/SearchModel.php: o modelo da view: a entrada (para exibi-la
// novamente), os gêneros, os resultados

namespace App\Models;

readonly class SearchModel
{
    /**
     * @param list<string> $genres
     * @param list<Book> $results
     */
    public function __construct(
        public string $keyword,
        public string $genre,
        public array $genres,
        public array $results,
    ) {
    }
}
  • Linhas 14–17: o modelo da view contém o que o usuário digitou (que o formulário exibirá), a lista de gêneros sugeridos e os resultados.

4.5.2. O controller: app/Http/Controllers/BooksController.php

<?php
// app/Http/Controllers/BooksController.php: um formulário de busca, enviado por GET

namespace App\Http\Controllers;

use App\Models\Book;
use App\Models\SearchModel;
use Illuminate\Http\Request;
use Illuminate\View\View;

class BooksController
{
    // CONSTANTES de classe: os dados, escritos no código para o exemplo
    private const GENRES = ['novel', 'poetry', 'drama'];

    /** @return list<Book> */
    private static function books(): array
    {
        return [
            new Book('Le Rouge et le Noir', 'Stendhal', 'novel'),
            new Book('Les Fleurs du mal', 'Baudelaire', 'poetry'),
            new Book('Madame Bovary', 'Flaubert', 'novel'),
            new Book('Alcools', 'Apollinaire', 'poetry'),
            new Book('Le Cid', 'Corneille', 'drama'),
        ];
    }

    // GET / e GET /search?keyword=...&genre=...: o formulário E seus resultados
    public function search(Request $request): View
    {
        // string: o parâmetro, na forma de uma string ('' se estiver ausente)
        $keyword = $request->string('keyword')->value();
        $genre = $request->string('genre')->value();
        $word = mb_strtolower($keyword);
        $results = array_values(array_filter(self::books(), fn (Book $book) =>
            ($word === '' || str_contains(mb_strtolower($book->title), $word)
                || str_contains(mb_strtolower($book->author), $word))
            && ($genre === '' || $book->genre === $genre)));
        return view('books.search', [
            'model' => new SearchModel($keyword, $genre, self::GENRES, $results),
        ]);
    }
}
  • Linha 14: uma constante de classe privada chamada [self::GENRES] ([self] refere-se à classe atual). Uma constante não pode conter objetos: por isso, os livros são fornecidos por um método estático (linhas 17–25). Em uma aplicação real, eles viriam de um banco de dados;
  • linhas 32–33: os campos do formulário são lidos como parâmetros da URL (exemplo 07). O método [string] retorna o parâmetro como um objeto [Stringable] do tipo [Laravel] (uma string enriquecida com métodos), que fica vazio se o parâmetro estiver ausente; [value()] extrai dele a string [PHP];
  • Linhas 35–38: filtragem. A função [array_filter] mantém os elementos de um array para os quais a função fornecida retorna [true]: um livro é mantido se a palavra-chave estiver vazia ou aparecer em seu título ou autor (em minúsculas de ambos os lados), e se o gênero estiver vazio ou corresponder ao do livro. [array_filter] mantém as chaves dos elementos selecionados (0, 2...): [array_values] as renumera a partir de 0;
  • linhas 39–41: o modelo da view.

A tabela de rotas associa duas URLs à mesma ação: na primeira visita ([/]), não há parâmetros e todos os livros são exibidos.

1
2
3
4
5
6
7
8
9
<?php
// routes/web.php: as rotas do exemplo 17

use App\Http\Controllers\BooksController;
use Illuminate\Support\Facades\Route;

// duas rotas para a mesma action
Route::get('/', [BooksController::class, 'search']);
Route::get('search', [BooksController::class, 'search']);

4.5.3. A view: resources/views/books/search.blade.php

@extends('layout')

@section('content')
  <h1 class="h3">Book search</h1>
  {{-- method="get": the fields are sent in the URL (?keyword=...&genre=...) --}}
  <form method="get" action="/search" class="row g-2 align-items-end mb-3">
    <div class="col-auto">
      <label class="form-label" for="keyword">Title or author</label>
      {{-- value: the field displays again what was typed (escaped by {{ }}) --}}
      <input class="form-control" id="keyword" name="keyword" value="{{ $model->keyword }}">
    </div>
    <div class="col-auto">
      <label class="form-label" for="genre">Genre</label>
      <select class="form-select" id="genre" name="genre">
        <option value="">(all)</option>
        @foreach ($model->genres as $genre)
          {{-- @selected: the boolean selected attribute, written if the condition is true, omitted otherwise --}}
          <option value="{{ $genre }}" @selected($genre === $model->genre)>{{ $genre }}</option>
        @endforeach
      </select>
    </div>
    <div class="col-auto">
      <button class="btn btn-primary" type="submit">Search</button>
    </div>
  </form>
  <p>{{ count($model->results) }} book(s) found.</p>
  <ul>
    @foreach ($model->results as $book)
      <li><i>{{ $book->title }}</i>, {{ $book->author }} ({{ $book->genre }})</li>
    @endforeach
  </ul>
@endsection
  • Linha 6: a tag [<form>]. O atributo [action] é a URL para a qual o formulário é enviado; [method="get"] coloca os campos na URL. As classes do [Bootstrap] dispõem os campos em uma única linha;
  • Linha 8: um rótulo. Seu atributo [for] especifica o identificador ([id]) do campo que ele descreve: clicar no rótulo coloca o cursor no campo, e os leitores de tela leem o rótulo junto com o campo;
  • linha 10: um campo de entrada. Seu atributo [name] é o nome do parâmetro enviado ao servidor: esse é o elo entre o formulário e a ação ([$request->string('keyword')]). O atributo [value] é o valor exibido: a entrada anterior, reexibida (e escapada por [{{ }}], o que é essencial em um atributo: uma entrada contendo aspas ["] fecharia o atributo);
  • linhas 14–20: uma lista suspensa. Cada [<option>] tem um valor ([value]), enviado ao servidor, e um texto, exibido. A primeira opção, com valor vazio, significa “todos os gêneros”;
  • linha 18: a opção selecionada na requisição anterior recebe o atributo [selected]. Trata-se de um atributo booleano: sua simples presença basta; ele não tem valor. A diretiva [@selected(condition)] o define se a condição for verdadeira e não define nada caso contrário. Da mesma forma, existem [@checked], [@disabled], [@readonly], e [@required];
  • linha 23: o botão de envio;
  • linha 26: o número de resultados.

4.5.4. Execução

Image

Digite [le] e selecione o tipo [novel]:

Image

A URL da página de resultados contém os campos do formulário: [/search?keyword=le&genre=novel]. A resposta do formulário:

curl "http://localhost:8000/search?keyword=le&genre=novel"
...
  <form method="get" action="/search" class="row g-2 align-items-end mb-3">
    <div class="col-auto">
      <label class="form-label" for="keyword">Title or author</label>
      <input class="form-control" id="keyword" name="keyword" value="le">
    </div>
    <div class="col-auto">
      <label class="form-label" for="genre">Genre</label>
      <select class="form-select" id="genre" name="genre">
        <option value="">(all)</option>
          <option value="novel" selected>novel</option>
          <option value="poetry" >poetry</option>
          <option value="drama" >drama</option>
              </select>
    </div>
...
  </form>
  <p>1 book(s) found.</p>
  <ul>
          <li><i>Le Rouge et le Noir</i>, Stendhal (novel)</li>
      </ul>
...

“Madame Bovary” não é selecionado: “le” não aparece nem no título nem no nome do autor.

4.6. Exemplo 18: campos de formulário

Este exemplo apresenta todos os tipos de campo de um formulário HTML, enviado aqui por POST. Ele demonstra como reexibir cada tipo de campo com seu valor atual, como o navegador envia os valores de cada campo e como o servidor verifica se um valor recebido é de fato uma das opções disponíveis. O [Laravel] não tem uma biblioteca que defina formulários por meio de classes (como o [WTForms] e o [Python]): os campos são escritos em HTML na view, e as diretivas do [Blade] ([@checked], [@selected]...) ajudam a renderizá-los.

4.6.1. O serviço de listas: app/Services/ListsService.php

<?php
// app/Services/ListsService.php: as listas oferecidas pelo formulário. Em uma
// aplicação real, elas viriam de um banco de dados.

namespace App\Services;

class ListsService
{
    // cada lista: um array associativo enviado valor => texto exibido
    public function titles(): array
    {
        return ['Mr' => 'Mr', 'Mme' => 'Mme', 'Melle' => 'Melle'];
    }

    public function countries(): array
    {
        return ['fr' => 'France', 'be' => 'Belgium', 'ch' => 'Switzerland', 'ca' => 'Canada'];
    }

    public function hobbies(): array
    {
        return ['reading' => 'reading', 'music' => 'music', 'sport' => 'sport',
            'cinema' => 'cinema'];
    }

    public function languages(): array
    {
        return ['French' => 'French', 'English' => 'English', 'Spanish' => 'Spanish',
            'German' => 'German'];
    }
}

As listas suspensas do formulário (títulos, países, hobbies, idiomas) são fornecidas por um serviço, seguindo o modelo do exemplo 06: em uma aplicação real, elas viriam de um banco de dados. Cada lista é um array associativo: a chave é o valor enviado ao servidor, e o valor é o texto exibido. O serviço é uma classe concreta: o contêiner do [Laravel] sabe criá-la sem uma declaração (exemplo 06).

4.6.2. O controller: app/Http/Controllers/FormController.php

<?php
// app/Http/Controllers/FormController.php: um formulário que usa todos os tipos de campos

namespace App\Http\Controllers;

use App\Services\ListsService;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;
use Illuminate\View\View;

class FormController
{
    // o serviço de listas é injetado pelo container (veja o exemplo 06)
    public function __construct(private ListsService $lists)
    {
    }

    // GET: o formulário, com valores iniciais (um por campo)
    public function display(): View
    {
        $input = ['title' => 'Mme', 'country' => 'fr', 'languages' => ['French'], 'token' => 'A7X2'];
        return view('form.form', ['lists' => $this->lists, 'input' => $input]);
    }

    // POST: os campos enviados são validados e depois exibidos novamente pelo formulário
    public function process(Request $request): View
    {
        $l = $this->lists;
        // array_keys: os VALORES permitidos de cada lista (as chaves dos arrays)
        $validator = Validator::make($request->post(), [
            'title' => ['required', Rule::in(array_keys($l->titles()))],
            'birth_date' => 'nullable|date_format:Y-m-d',
            'hobbies' => 'array',
            'hobbies.*' => Rule::in(array_keys($l->hobbies())),
            'country' => ['required', Rule::in(array_keys($l->countries()))],
            'languages' => 'array',
            'languages.*' => Rule::in(array_keys($l->languages())),
        ]);
        // o que o navegador realmente enviou, parâmetro por parâmetro
        $received = [];
        foreach ($request->post() as $name => $value) {
            $received[] = "$name = [".implode(', ', (array) $value).']';
        }
        return view('form.form', [
            'lists' => $l,
            'input' => $request->post(),
            'received' => implode("\n", $received),
            'valid' => $validator->passes(),
            'errors' => $validator->errors(),
        ]);
    }
}
  • linha 15: o serviço é injetado pelo construtor;
  • linhas 20–23: os valores iniciais do formulário, um array associativo: um valor por campo (um array para um campo de vários valores). A view recebe esses valores na variável [$input], junto com o serviço de listas;
  • linhas 31–39: os campos recebidos são validados. Os campos de lista suspensa devem conter um dos valores sugeridos: um usuário malicioso poderia enviar qualquer coisa, e não apenas o que a página sugeriu. [Rule::in(...)] gera a regra [in] (exemplo 08) a partir de um array de valores — neste caso, as chaves da lista ([array_keys]). Os campos de vários valores são verificados elemento por elemento ([hobbies.*], exemplo 10). [date_format:Y-m-d]: um campo [<input type="date">] troca seus valores com o servidor no formato [yyyy-mm-dd], independentemente do formato em que o navegador o exibe;
  • linhas 41–44: para o exemplo, a lista do que o navegador realmente enviou. [(array) $value] converte um valor único em um array de um elemento (um array continua sendo um array); [implode] combina os elementos de um array em uma string, separados pelo primeiro parâmetro;
  • linhas 45–51: o formulário é reexibido com os valores recebidos ([$input]), o que o servidor recebeu, o resultado da validação ([passes()], o oposto de [fails()]) e eventuais erros.

A tabela de rotas associa a URL [/form] à ação [display] para o método GET e à ação [process] para o método POST.

4.6.3. A view: resources/views/form/form.blade.php

@extends('layout')

@section('content')
  <h1 class="h3">A complete form</h1>
  <form method="post" action="/form" style="max-width: 40rem">
    {{-- the hidden fields: Laravel's anti-CSRF token, and our [token] field --}}
    @csrf
    <input type="hidden" name="token" value="{{ $input['token'] ?? '' }}">

    <div class="mb-2">
      <span class="form-label me-3">Title</span>
      {{-- radio buttons: same [name], a single value sent --}}
      @foreach ($lists->titles() as $value => $text)
        <div class="form-check form-check-inline">
          <input class="form-check-input" type="radio" id="title-{{ $loop->index }}" name="title"
                 value="{{ $value }}" @checked(($input['title'] ?? '') === $value)>
          <label class="form-check-label" for="title-{{ $loop->index }}">{{ $text }}</label>
        </div>
      @endforeach
    </div>

    <div class="row g-2 mb-2">
      <div class="col">
        <label class="form-label" for="name">Name</label>
        <input class="form-control" type="text" id="name" name="name" value="{{ $input['name'] ?? '' }}">
      </div>
      <div class="col">
        {{-- a password is NEVER sent back in the page: no value attribute --}}
        <label class="form-label" for="password">Password</label>
        <input class="form-control" type="password" id="password" name="password">
      </div>
      <div class="col">
        <label class="form-label" for="birth_date">Date of birth</label>
        <input class="form-control" type="date" id="birth_date" name="birth_date" value="{{ $input['birth_date'] ?? '' }}">
      </div>
    </div>

    <div class="mb-2">
      <span class="form-label me-3">Hobbies</span>
      {{-- checkboxes: the hobbies[] name makes the received value an ARRAY (see example 10) --}}
      @foreach ($lists->hobbies() as $value => $text)
        <div class="form-check form-check-inline">
          <input class="form-check-input" type="checkbox" id="hobbies-{{ $loop->index }}" name="hobbies[]"
                 value="{{ $value }}" @checked(in_array($value, $input['hobbies'] ?? []))>
          <label class="form-check-label" for="hobbies-{{ $loop->index }}">{{ $text }}</label>
        </div>
      @endforeach
    </div>

    <div class="row g-2 mb-2">
      <div class="col">
        <label class="form-label" for="country">Country</label>
        <select class="form-select" id="country" name="country">
          @foreach ($lists->countries() as $value => $text)
            <option value="{{ $value }}" @selected(($input['country'] ?? '') === $value)>{{ $text }}</option>
          @endforeach
        </select>
      </div>
      <div class="col">
        <label class="form-label" for="languages">Spoken languages</label>
        {{-- multiple-selection list: several possible values, hence languages[] --}}
        <select class="form-select" id="languages" name="languages[]" multiple size="4">
          @foreach ($lists->languages() as $value => $text)
            <option value="{{ $value }}" @selected(in_array($value, $input['languages'] ?? []))>{{ $text }}</option>
          @endforeach
        </select>
      </div>
    </div>

    <div class="mb-2">
      <label class="form-label" for="comment">Comment</label>
      {{-- a text area: the value is BETWEEN the tags --}}
      <textarea class="form-control" id="comment" name="comment" rows="2">{{ $input['comment'] ?? '' }}</textarea>
    </div>

    <button class="btn btn-primary" type="submit">Send</button>
  </form>

  {{-- isset: true if the $received variable was passed to the view (by the POST action) --}}
  @isset($received)
    <h2 class="h5 mt-3">What the server received</h2>
    <pre class="bg-light p-2 border">{{ $received }}</pre>
    <p>Valid form: {{ $valid ? 'yes' : 'no' }}</p>
    {{-- $errors->messages(): field -> list of its error messages --}}
    <ul>
      @foreach ($errors->messages() as $field => $messages)
        <li>{{ $field }}: {{ implode(', ', $messages) }}</li>
      @endforeach
    </ul>
  @endisset
@endsection
  • linha 5: um formulário de nome POST;
  • linha 7: a diretiva [@csrf] escreve um campo oculto chamado [_token], que contém o token anti-CSRF. Um ataque CSRF (*Cross-Site Request Forgery*) consiste em um site malicioso induzir o navegador da vítima a enviar um formulário à nossa aplicação. O navegador inclui os cookies da nossa aplicação na requisição — e, portanto, a sessão do usuário autenticado —, fazendo a requisição parecer legítima. A defesa: todo formulário da nossa aplicação contém um token aleatório vinculado à sessão do usuário, que o site malicioso não tem como conhecer. O middleware [PreventRequestForgery] do grupo [web] (exemplo 01) rejeita qualquer requisição POST (assim como PUT, PATCH e DELETE) cujo token esteja ausente ou seja inválido, antes mesmo de a ação ser chamada: nenhuma ação pode deixar de aplicá-lo. É esse o middleware que os exemplos 02 e 11 excluíram para suas requisições [curl];
  • linha 8: nosso próprio campo oculto;
  • linhas 13–19: um grupo de botões de opção, um por título. Todos têm o mesmo atributo [name]: apenas um é selecionado por vez, e apenas um valor é enviado. Cada botão tem seu próprio identificador ([title-0], [title-1]...), gerado com [$loop->index], ao qual seu rótulo se refere. A diretiva [@checked] marca o botão cujo valor corresponde ao título atual;
  • linha 25: o campo de entrada do nome; [?? ''] trata o caso em que um nome não está na tabela;
  • Linha 30: uma senha nunca deve trafegar de um lado para o outro em uma página HTML: o campo não tem o atributo [value]; ele sempre está vazio quando exibido;
  • Linhas 41–47: caixas de seleção, estilizadas como botões de opção. Elas também compartilham o mesmo nome; no entanto, várias caixas podem ser marcadas, e o navegador então envia vários valores: o nome [hobbies[]] instrui o [PHP] a organizá-los em um array (exemplo 10). A função [in_array] verifica se um valor está presente em um array;
  • linhas 53–57: uma lista suspensa, cuja opção atual é marcada por [@selected];
  • linha 62: uma lista de seleção múltipla (atributo [multiple]), exibida em quatro linhas ([size]), cujo nome também termina com [[]];
  • linha 73: um campo de texto de duas linhas. Seu valor é inserido entre as tags, e não em um atributo;
  • Linhas 80–90: a diretiva [@isset] verifica a existência de uma variável: [$received] só foi passada à view pela ação POST. [$errors->messages()] retorna, para cada campo inválido, uma lista de suas mensagens de erro (exemplo 09).

4.6.4. Execução

Image

Os valores padrão estão visíveis: o botão de opção “Mme”, o país “France” e o idioma “French”. O HTML produz (trechos):

<input type="hidden" name="_token" value="mjFN6z3WBF79ZEA8EWgmoX3Hio8DjjmG7hGQlGax" autocomplete="off">
<input type="hidden" name="token" value="A7X2">
...
<input class="form-check-input" type="radio" id="title-1" name="title"
       value="Mme" checked>
<label class="form-check-label" for="title-1">Mme</label>
...
<input class="form-control" type="date" id="birth_date" name="birth_date" value="">
...
<input class="form-check-input" type="checkbox" id="hobbies-0" name="hobbies[]"
       value="reading" >
<label class="form-check-label" for="hobbies-0">reading</label>
...
<select class="form-select" id="country" name="country">
  <option value="fr" selected>France</option>
  <option value="be" >Belgium</option>
...
<select class="form-select" id="languages" name="languages[]" multiple size="4">
  <option value="French" selected>French</option>
...
<textarea class="form-control" id="comment" name="comment" rows="2"></textarea>

O token anti-CSRF é uma string aleatória de 40 caracteres, armazenada na sessão do usuário (exemplo 20). Vamos preencher o formulário e enviá-lo:

Image

A página mostra o que o servidor recebeu: um parâmetro por campo, com vários valores para as caixas de seleção e para a lista suspensa; a senha foi enviada, mas não é exibida novamente em seu campo. O campo oculto [token] foi devolvido exatamente como estava: é assim que se enviam e recebem informações que o usuário não vê (o estudo de caso usa isso para o número de versão de um registro). No entanto, um campo oculto não é um campo protegido: o usuário pode modificá-lo com as ferramentas de desenvolvedor do navegador, e o servidor deve validá-lo como qualquer outro campo. Observamos também que o token anti-CSRF ([_token]) está entre os campos recebidos.

Agora vamos enviar um formulário sem token, usando o [curl]:

curl -i -d "name=Martin&country=xx" http://localhost:8000/form
1
2
3
4
5
6
7
8
HTTP/1.1 419 unknown status
Content-Type: text/html; charset=utf-8

<!DOCTYPE html>
<html lang="en">
...
        <title>Page Expired</title>
...

A requisição é rejeitada pelo middleware [PreventRequestForgery] com o código de status 419, específico do [Laravel] (*Page Expired*: é a mensagem vista por um usuário cuja sessão expirou entre o momento em que o formulário foi exibido e o momento em que foi enviado). Para resolver isso, o [curl] deve se comportar como um navegador: primeiro solicitar o formulário, mantendo o cookie de sessão (opção [-c], que salva os cookies recebidos em um arquivo), depois reenviar o cookie (opção [-b]) e o token lido da página:

curl -c cookies.txt http://localhost:8000/form
curl -b cookies.txt -d "_token=WkdoQuahsZxMScUg5UJ5UOwWN4nDF8l3Niyce9WK&name=Martin&country=xx" http://localhost:8000/form
...
      <h2 class="h5 mt-3">What the server received</h2>
    <pre class="bg-light p-2 border">_token = [WkdoQuahsZxMScUg5UJ5UOwWN4nDF8l3Niyce9WK]
name = [Martin]
country = [xx]</pre>
    <p>Valid form: no</p>
    <ul>
              <li>title: The title field is required.</li>
              <li>country: The selected country is invalid.</li>
          </ul>
...

(o token é o da página recebida pelo primeiro comando). Dois erros: o país [xx] não está entre as opções; nenhum título foi enviado. As mensagens são as padrão do Laravel: o exemplo seguinte as personaliza.

4.7. Exemplo 19: validação de formulário

Um formulário de cadastro, em que cada campo tem suas próprias regras de validação. Se ocorrer um erro, o formulário é reexibido com o que o usuário digitou e uma mensagem abaixo de cada campo inválido. Este exemplo usa a abordagem padrão do [Laravel]: uma form request (exemplo 08) valida os campos antes da ação; se ocorrer um erro, o [Laravel] redireciona para a página do formulário, preservando o que o usuário digitou e os erros para a próxima requisição.

4.7.1. O formulário: app/Http/Requests/RegistrationRequest.php

<?php
// app/Http/Requests/RegistrationRequest.php: os campos do formulário e suas restrições

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class RegistrationRequest extends FormRequest
{
    // as regras de cada campo. Os espaços que cercam a entrada já foram
    // removidos pelo middleware TrimStrings, e uma entrada vazia substituída por null
    public function rules(): array
    {
        return [
            'name' => 'required|max:20',
            // email:filter: a verificação da função filter_var do PHP, que
            // exige um nome de domínio completo (example.com, e não example)
            'email' => 'required|email:filter',
            'age' => 'required|integer|between:18,120',
            'password' => 'required|min:6',
            // uma regra sobre DOIS campos: same compara este campo com outro
            'confirmation' => 'required|same:password',
        ];
    }

    // as mensagens de erro, campo.regra => mensagem
    public function messages(): array
    {
        return [
            'name.required' => 'The name is required.',
            'name.max' => 'The name must not exceed 20 characters.',
            'email.required' => 'The email address is required.',
            'email.email' => 'Invalid email address.',
            'age.required' => 'The age is required.',
            'age.between' => 'The age must be between 18 and 120 years.',
            'password.required' => 'The password is required.',
            'password.min' => 'The password must have at least 6 characters.',
            'confirmation.required' => 'The confirmation is required.',
            'confirmation.same' => 'The confirmation does not match the password.',
        ];
    }
}
  • Linhas 12–23: as regras de validação de cada campo (exemplo 08). Os espaços em volta da entrada já foram removidos pelo middleware [TrimStrings] (exemplo 08): um nome composto apenas de espaços se torna uma string vazia, depois [null], e será rejeitado por [required];
  • Linha 18: a regra [email] aceita variantes, que determinam qual validação é aplicada. Por padrão, ela segue o padrão de endereços de e-mail, que aceita [martin@example] (um nome de host sem domínio). [email:filter] usa a função [filter_var] do [PHP] (exemplo 07), que exige um nome de domínio totalmente qualificado ([example.com]);
  • linha 19: [integer] seguida de [between:18,120];
  • Linha 22: uma regra que se aplica a dois campos: [same:password] compara o valor de um campo com o de outro campo. O [Laravel] também fornece a regra [confirmed], que, aplicada ao campo [password], exigiria um campo chamado [password_confirmation];
  • Linhas 27–40: o método [messages] fornece mensagens específicas deste formulário. Cada chave designa um campo e uma regra ([name.required]); uma chave única como [required] se aplicaria a todos os campos. Essas mensagens têm precedência sobre as dos arquivos de idioma (exemplo 09).

As mensagens não fornecidas pela classe vêm do arquivo [lang/en/validation.php] (o arquivo [.env] define o idioma como [en]; veja o exemplo 09):

1
2
3
4
5
6
<?php
// lang/en/validation.php: as mensagens que a classe RegistrationRequest não
// fornece por conta própria
return [
    'integer' => 'An integer is expected.',
];

É o caso da mensagem da regra [integer], que só é exibida se algo diferente de um número for digitado no campo de idade — algo que um navegador não faz (veremos isso com o [curl]).

4.7.2. O controller: app/Http/Controllers/RegistrationController.php

<?php
// app/Http/Controllers/RegistrationController.php: um formulário validado pelo servidor

namespace App\Http\Controllers;

use App\Http\Requests\RegistrationRequest;
use Illuminate\Http\Request;
use Illuminate\View\View;

class RegistrationController
{
    // GET /register: o formulário; ?html5=true: deixamos o navegador
    // validá-lo antes do envio
    public function display(Request $request): View
    {
        return view('registration.registration', ['html5' => $request->query('html5') === 'true']);
    }

    // POST /register: a action só é chamada se o formulário for VÁLIDO.
    // Caso contrário, o Laravel REDIRECIONA para a página do formulário, mantendo a entrada e
    // os erros para a próxima requisição (veja old e @error nas views)
    public function register(RegistrationRequest $request): View
    {
        return view('registration.welcome', ['registration' => $request->validated()]);
    }
}
  • linhas 14–17: a exibição do formulário. O parâmetro [?html5=true] ativa a validação do navegador (veja abaixo);
  • linhas 22–25: a ação só aceita formulários válidos: a form request [RegistrationRequest] foi validada antes de ela ser chamada (exemplo 08). Ela exibe a página de boas-vindas com os dados validados. (O exemplo seguinte mostrará que é melhor redirecionar após um POST bem-sucedido.)

E um formulário inválido? Ele nunca chega à ação. A form request dispara uma [ValidationException] (exemplo 08), que o [Laravel] trata da seguinte maneira para uma requisição vinda de um navegador: ele armazena os erros e os valores digitados (exceto as senhas) na sessão do usuário e, em seguida, responde com um redirecionamento para a página anterior — a página do formulário. O navegador solicita imediatamente essa página de novo (via GET), e a view do formulário recupera os erros e o que o usuário digitou, que a sessão fornece uma única vez (veremos esse mecanismo de dados “flash” no próximo exemplo). O formulário é, assim, reexibido por sua ação GET, e não pela ação POST: este já é o padrão Post/Redirect/Get do exemplo seguinte, aplicado aos erros.

4.7.3. Um campo reutilizável: resources/views/components/field.blade.php

Cada campo é exibido da mesma forma: um rótulo, o campo de entrada e, em caso de erro, a área contornada em vermelho e a mensagem abaixo dela. Um componente evita ter de escrever isso cinco vezes:

{{-- an input field, with its label and its FIRST error message.
     old($name): the previous input, kept by Laravel after an invalid
     form; $attributes: the other attributes given to the component (required,
     min, max...), copied onto the input tag --}}
@props(['name', 'label', 'type' => 'text'])
<div class="mb-2">
  <label class="form-label" for="{{ $name }}">{{ $label }}</label>
  <input {{ $attributes->class(['form-control', 'is-invalid' => $errors->has($name)]) }}
         type="{{ $type }}" id="{{ $name }}" name="{{ $name }}"
         @if ($type !== 'password') value="{{ old($name) }}" @endif>
  {{-- @error: the block is displayed only if the field has an error, whose
       first message is in the $message variable --}}
  @error($name)
    <div class="invalid-feedback">{{ $message }}</div>
  @enderror
</div>
  • linha 5: os parâmetros do componente: o nome do campo, seu rótulo e seu tipo, [text] por padrão;
  • linha 8: a variável [$attributes] contém os atributos atribuídos ao componente que não são parâmetros declarados por [@props] (aqui, [required], [min], [max]...): quando escrita na tag, ela os copia. Seu método [class] adiciona a ela o atributo [class], de forma semelhante à diretiva [@class] (exemplo 16): a classe [is-invalid] do [Bootstrap] contorna o campo em vermelho se ele contiver um erro. A variável [$errors] está disponível em todas as views: é uma “sacola” de mensagens (exemplo 09) — contendo os erros do formulário anterior armazenados na sessão — ou uma sacola vazia; [has] verifica se há erros em um campo;
  • Linha 10: a função [old] retorna o valor digitado no formulário anterior, armazenado na sessão, ou [null]. Um campo do tipo [password] não tem o atributo [value] (exemplo 18);
  • Linhas 13–15: o bloco [@error] ... [@enderror] só é exibido se o campo contiver um erro; nesse caso, sua primeira mensagem é armazenada na variável [$message]. O elemento [invalid-feedback] é exibido em vermelho pelo [Bootstrap], abaixo de uma zona marcada com [is-invalid].

4.7.4. As views

@extends('layout')

@section('content')
  <h1 class="h3">Registration</h1>
  @if ($html5)
    <p>Browser validation <b>enabled</b> - <a href="/register">disable it</a></p>
  @else
    <p>Browser validation <b>disabled</b> - <a href="/register?html5=true">enable it</a></p>
  @endif
  {{-- novalidate: the browser ignores the required, min... attributes and
       sends the form as is; only the server validates --}}
  <form method="post" action="/register" @if (! $html5) novalidate @endif>
    @csrf
    <x-field name="name" label="Name" required maxlength="20" />
    <x-field name="email" label="Email address" type="email" required />
    <x-field name="age" label="Age" type="number" required min="18" max="120" />
    <x-field name="password" label="Password" type="password" required minlength="6" />
    <x-field name="confirmation" label="Confirmation" type="password" required />
    <button class="btn btn-primary" type="submit">Register</button>
  </form>
@endsection
  • linha 12: o atributo [novalidate] desativa a validação do navegador: o formulário é enviado como está, e apenas o servidor o valida. É isso que queremos observar primeiro;
  • linhas 14–18: um componente por campo. Os atributos HTML5 ([required], [maxlength], [min], [max], [minlength], [type="email"]) permitem que o navegador verifique a entrada mesmo antes de ela ser enviada (veremos isso adiante). [Laravel] não os deriva das regras de validação: eles são escritos na view e devem permanecer consistentes com as regras.
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Registration</title>
  <link rel="stylesheet" href="{{ route('bootstrap', 'css/bootstrap.min.css') }}">
  <link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
  <div class="container py-3" style="max-width: 36rem">
    <main>
      @yield('content')
    </main>
    {{-- the global error, at the bottom of the page, on a light pink background. $errors: the errors
         of the previous form, available in all the views --}}
    @if ($errors->any())
      <div class="error-area" role="alert">The form contains errors.</div>
    @endif
  </div>
</body>
</html>
  • linhas 16–18: uma mensagem geral no final da página se o formulário anterior continha erros ([any()] verifica se a sacola contém pelo menos uma mensagem), em uma área cujo estilo é definido por [public/css/styles.css] (exemplo 15). O atributo [role="alert"] sinaliza isso para os leitores de tela.
1
2
3
4
5
6
7
8
@extends('layout')

@section('content')
  {{-- $registration: the validated data --}}
  <h1 class="h3">Welcome {{ $registration['name'] }}</h1>
  <p>Your registration is saved: address <b>{{ $registration['email'] }}</b>,
    age <b>{{ $registration['age'] }}</b> years.</p>
@endsection

[$registration] contém os dados validados: o nome sem espaços, a idade (uma string; veja o exemplo 08).

4.7.5. Execução

Vamos enviar um formulário cheio de erros: um nome composto de espaços, um endereço de e-mail sem domínio completo, uma idade de 12, uma senha curta demais e uma confirmação diferente:

Image

O que foi digitado foi preservado (exceto as senhas), e cada erro é sinalizado abaixo do campo correspondente. A URL é a do formulário, e [/register] indica que a página foi exibida pela ação GET após o redirecionamento. Com o [curl], fornecendo o token anti-CSRF como no exemplo 18, vemos esse redirecionamento:

curl -i -b cookies.txt -c cookies.txt -d "_token=...&name=Martin&email=martin@example.com&age=abc&password=abcdef&confirmation=abcdef" http://localhost:8000/register
1
2
3
4
HTTP/1.1 302 Found
Location: http://localhost:8000/register
Content-Type: text/html; charset=utf-8
...

Também é possível enviar algo que um navegador não enviaria, como uma idade não numérica. A página seguinte ([curl -b cookies.txt http://localhost:8000/register]) mostra o campo de idade, com o que foi digitado e a mensagem da regra [integer], extraída do arquivo de idioma:

1
2
3
4
  <input class="form-control is-invalid" required="required" min="18" max="120"
         type="number" id="age" name="age"
          value="abc" >
      <div class="invalid-feedback">An integer is expected.</div>

Vemos também os atributos HTML5 copiados por [$attributes]: [required] (escrito como [required="required"], uma forma equivalente), [min], [max].

4.7.6. Validação no navegador

Vamos remover o atributo [novalidate] seguindo o link “Enable” (parâmetro [?html5=true]). O navegador passa então a verificar os atributos [required], [type="email"], [min], [maxlength]... antes de enviar o formulário e exibe suas próprias mensagens em uma dica abaixo do primeiro campo inválido (“Please fill in this field”, “The value must be greater than or equal to 18” etc.): o formulário não é enviado enquanto houver um erro.

Essa validação é conveniente para o usuário: é imediata, sem idas e vindas ao servidor. Mas ela não substitui a validação no servidor: um usuário pode desativá-la, e um programa como o [curl] a ignora por completo. A regra é absoluta: o servidor sempre valida; a validação no navegador é apenas uma comodidade adicional.

Uma entrada correta, enfim. O nome, digitado com espaços dos dois lados, foi limpo pelo middleware [TrimStrings]:

Image

4.8. Exemplo 20: o padrão Post/Redirect/Get

Quando uma ação POST retorna uma página, essa página é o resultado de um POST. Se o usuário atualiza a página (pressionando [F5]), o navegador reenvia a requisição POST, após um aviso que poucas pessoas leem: o comando é enviado duas vezes, e a mensagem é publicada duas vezes. O padrão Post/Redirect/Get (PRG) evita esse problema: uma ação POST bem-sucedida não retorna uma página; ela responde com um redirecionamento (exemplo 04) para uma página GET, que o navegador solicita imediatamente. Recarregar essa página simplesmente executa de novo a ação GET.

Resta um problema: a página GET gostaria de exibir uma mensagem (“a tarefa foi adicionada”), mas é a ação POST que conhece essa mensagem, e ela não pode passar uma variável para uma requisição que ainda não ocorreu. A solução: a mensagem flash, armazenada na sessão pela ação POST, é mantida até a próxima requisição, exibida e depois descartada. É o mecanismo que o [Laravel] já usava, no exemplo 19, para os erros de formulário.

4.8.1. O serviço: app/Services/TasksService.php

<?php
// app/Services/TasksService.php: a lista de tarefas, compartilhada por todos os
// usuários. Em PHP, os objetos não sobrevivem à requisição: a lista é
// armazenada no CACHE do Laravel (aqui, um arquivo da pasta storage/framework/cache)

namespace App\Services;

use Illuminate\Support\Facades\Cache;

class TasksService
{
    private const KEY = 'tasks';

    /** @return list<string> */
    public function list(): array
    {
        // o valor armazenado sob a chave [tasks], ou a lista inicial
        return Cache::get(self::KEY, ['Read chapter 3']);
    }

    public function add(string $label): void
    {
        // várias requisições podem ser executadas AO MESMO TEMPO (o servidor as trata
        // em vários processos): um lock garante que apenas uma por vez
        // leia, modifique e regrave a lista. block(5, ...) espera pelo lock no máximo 5
        // segundos, executa a função e depois libera o lock
        Cache::lock('tasks-lock', 10)->block(5, function () use ($label) {
            $tasks = $this->list();
            $tasks[] = $label;
            // forever: o valor é mantido sem limite de tempo
            Cache::forever(self::KEY, $tasks);
        });
    }
}

A lista de tarefas é compartilhada por todos os usuários e deve persistir de uma requisição para a seguinte. Em [Java], [C#] ou [Python], ela seria mantida em memória dentro de um único serviço. Em [PHP], isso é impossível: como vimos nos exemplos 01 e 06, nada sobrevive à requisição. A lista deve, portanto, ser armazenada fora do [PHP]: em um banco de dados, em um arquivo... ou no cache do [Laravel], que usamos aqui.

  • Linha 18: a interface [Cache] dá acesso ao cache da aplicação: um armazenamento de pares chave→valor. O arquivo [.env] dos exemplos armazena esses dados em arquivos dentro da pasta [storage/framework/cache] ([CACHE_STORE=file], exemplo 01); em produção, prefere-se um servidor dedicado, como o [Redis]. [get] retorna o valor armazenado sob uma chave, ou o valor padrão fornecido como segundo parâmetro. Qualquer valor (neste caso, um array de strings) pode ser armazenado: o [Laravel] o serializa — isto é, converte-o em texto — usando a função [serialize] do [PHP];
  • Linhas 27–32: o servidor de desenvolvimento, como um servidor de produção, pode processar várias requisições ao mesmo tempo, em vários processos (a variável de ambiente [PHP_CLI_SERVER_WORKERS] define o número de processos de [php artisan serve]). Duas inserções simultâneas poderiam ler a mesma lista, cada uma adicionar sua própria tarefa a ela e depois gravá-la de volta: a segunda gravação sobrescreveria a primeira tarefa. Um lock garante que apenas uma requisição por vez execute o código que ele protege: [Cache::lock('tasks-lock', 10)] cria um lock nomeado — que também é armazenado no cache — que expira após no máximo 10 segundos (caso a requisição que o detém seja encerrada abruptamente); [block(5, function)] espera até 5 segundos para que o lock fique disponível, adquire-o, executa a função e depois o libera. A palavra-chave [use] em uma função anônima dá a ela acesso a uma variável da função que a contém (aqui, [$label]); uma função de seta, por outro lado, enxerga essas variáveis automaticamente;
  • Linha 31: [forever] armazena um valor indefinidamente; [put(key, value, seconds)] o armazenaria por uma duração especificada.

4.8.2. O controller: app/Http/Controllers/TasksController.php

<?php
// app/Http/Controllers/TasksController.php: o padrão Post / Redirect / Get

namespace App\Http\Controllers;

use App\Services\TasksService;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\View\View;

class TasksController
{
    public function __construct(private TasksService $tasks)
    {
    }

    // GET /tasks: a lista e o formulário de adição
    public function display(): View
    {
        return view('tasks.tasks', ['tasks' => $this->tasks->list()]);
    }

    // POST /tasks: o padrão Post / Redirect / Get
    public function add(Request $request): View|RedirectResponse
    {
        $label = $request->string('label')->value();
        if ($label === '' || mb_strlen($label) > 40) {
            // entrada inválida: exibimos a página novamente, sem redirecionamento
            return view('tasks.tasks', ['tasks' => $this->tasks->list(),
                'label' => $label,
                'error' => 'The label must have 1 to 40 characters.']);
        }
        $this->tasks->add($label);
        // nenhuma página: um redirecionamento para a página GET; with deixa uma mensagem "flash"
        // na sessão: ela sobreviverá ao redirecionamento, para a PRÓXIMA requisição
        return redirect()->route('tasks')->with('message', "The task [$label] has been added.");
    }

    // POST /tasks/without-prg: o contraexemplo (uma página em resposta ao POST)
    public function addWithoutPrg(Request $request): View
    {
        $this->tasks->add($request->string('label')->value() ?: '(untitled)');
        return view('tasks.tasks', ['tasks' => $this->tasks->list(), 'withoutPrg' => true]);
    }
}
  • linhas 26–31: a entrada é validada manualmente para manter o exemplo simples. Uma entrada inválida é exibida novamente, sem redirecionamento: não há nada a proteger contra um envio duplicado, pois nada foi modificado. [mb_strlen] conta os caracteres de uma string UTF-8;
  • linha 36: o redirecionamento para a página GET, chamada [tasks]. O método [with] de um redirecionamento coloca uma mensagem flash na sessão: dados mantidos apenas para a próxima requisição;
  • linhas 40–43: o contraexemplo: uma página em resposta a um POST. O operador [?:] retorna seu operando da esquerda se ele for “verdadeiro” (aqui, uma string não vazia) e o operando da direita caso contrário.

A tabela de rotas:

<?php
// routes/web.php: as rotas do exemplo 20

use App\Http\Controllers\TasksController;
use Illuminate\Support\Facades\Route;

Route::controller(TasksController::class)->group(function () {
    Route::get('tasks', 'display')->name('tasks');
    Route::post('tasks', 'add');
    Route::post('tasks/without-prg', 'addWithoutPrg');
});

4.8.3. As views

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Tasks</title>
  <link rel="stylesheet" href="{{ route('bootstrap', 'css/bootstrap.min.css') }}">
  <link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
  <div class="container py-3" style="max-width: 36rem">
    {{-- the flash message, at the top of the page: left BEFORE the redirect; the session
         returns it during the next request, then forgets it --}}
    @session('message')
      <div class="alert alert-success" role="status">{{ $value }}</div>
    @endsession
    <main>
      @yield('content')
    </main>
    @isset($error)
      <div class="error-area" role="alert">{{ $error }}</div>
    @endisset
  </div>
</body>
</html>
  • Linhas 13–15: o bloco [@session('message')] ... [@endsession] só é exibido se a sessão contiver uma entrada [message], caso em que seu valor é armazenado na variável [$value]. A classe [alert alert-success] do [Bootstrap] exibe a mensagem em uma moldura verde.
@extends('layout')

@section('content')
  <h1 class="h3">My tasks</h1>
  <ol>
    @foreach ($tasks as $task)
      <li>{{ $task }}</li>
    @endforeach
  </ol>
  <form method="post" action="/tasks" class="d-flex gap-2">
    @csrf
    <input class="form-control" name="label" value="{{ $label ?? '' }}" placeholder="New task">
    <button class="btn btn-primary text-nowrap" type="submit">Add</button>
    {{-- formaction: this button sends the SAME form to another address --}}
    <button class="btn btn-outline-secondary text-nowrap" type="submit" formaction="/tasks/without-prg">Add without PRG</button>
  </form>
  @isset($withoutPrg)
    <p class="text-danger mt-2">Page displayed in response to a POST: press F5 and the task will be added a second time.</p>
  @endisset
@endsection
  • Linha 15: o atributo [formaction] de um botão envia o formulário para um endereço diferente do especificado por seu atributo [action]: um único formulário pode, assim, disparar duas ações diferentes.

4.8.4. Onde as mensagens flash são armazenadas?

Entre a requisição POST e a requisição GET seguinte, a mensagem precisa ser armazenada em algum lugar: na sessão do usuário. A sessão do [Laravel] é armazenada no servidor: o arquivo [.env] dos exemplos a armazena em um arquivo dentro da pasta [storage/framework/sessions] ([SESSION_DRIVER=file]), com um arquivo por usuário. O navegador, por sua vez, recebe apenas o ID da sessão no cookie [example20_session] (o nome é derivado de [APP_NAME]), que ele devolve a cada requisição. Vamos examinar isso usando o [curl], armazenando os cookies em um arquivo (opções [-c] e [-b], exemplo 18) e fornecendo o token anti-CSRF:

curl -i -b cookies.txt -c cookies.txt -d "_token=...&label=Do%20the%20exercises" http://localhost:8000/tasks
1
2
3
4
5
6
HTTP/1.1 302 Found
Location: http://localhost:8000/tasks
Content-Type: text/html; charset=utf-8
Set-Cookie: XSRF-TOKEN=eyJpdiI6IjFJLzhDVy9CWndjODZNb2s3N2VMUnc9PSIsInZhbHVlIjoiT3JXZy96MmJROHUrYmZaNUFNbUFoM3d4...; expires=...; Max-Age=7200; path=/; samesite=lax
Set-Cookie: example20_session=eyJpdiI6IlMwK3R3ZkQ2TEhKUVZ4SW9saDVMNUE9PSIsInZhbHVlIjoiMVVnUTNvTHFL...; expires=...; Max-Age=7200; path=/; httponly; samesite=lax
...

A resposta ao POST é um redirecionamento (código de status 302, cabeçalho [Location]), acompanhado do cookie de sessão. Seu valor é criptografado com a chave [APP_KEY] (esse é o papel do middleware [EncryptCookies] do grupo [web]): o usuário não pode lê-lo nem modificá-lo. Quando descriptografado, ele contém apenas o ID da sessão — 40 caracteres aleatórios —, que também é o nome do arquivo de sessão no servidor: [storage/framework/sessions/HNuWctWJ0HcPvmsAhFN5v3iCiw1SFFDMXv46F6og]. Eis esse arquivo, após a requisição POST (exibido em várias linhas):

1
2
3
4
a:4:{s:6:"_token";s:40:"X0omnUmKl13zVLUrzTdZy5mWN7R6fBaiOmfEUPpr";
     s:9:"_previous";a:2:{s:3:"url";s:27:"http://localhost:8000/tasks";s:5:"route";s:5:"tasks";}
     s:6:"_flash";a:2:{s:3:"old";a:1:{i:0;s:7:"message";}s:3:"new";a:0:{}}
     s:7:"message";s:43:"The task [Do the exercises] has been added.";}

Este é um array [PHP] serializado: [a:4] indica um array de 4 elementos, [s:6:"_token"] uma string de 6 bytes... Ele contém o token anti-CSRF da sessão, a URL da página anterior ([_previous], usada pelo redirecionamento para a página anterior no exemplo 19), nossa mensagem e a lista [_flash] de dados flash. Ao final de cada requisição, os dados flash definidos durante a requisição (lista [new]) são movidos para a lista [old], e os dados que já estavam em [old] são removidos: assim, um dado flash sobrevive por exatamente uma requisição. Vamos seguir o redirecionamento devolvendo o cookie:

curl -i -b cookies.txt -c cookies.txt http://localhost:8000/tasks
1
2
3
4
5
6
7
HTTP/1.1 200 OK
...
          <div class="alert alert-success" role="status">The task [Do the exercises] has been added.</div>
...
          <li>Read chapter 3</li>
          <li>Do the exercises</li>
...

A mensagem é exibida e, depois dessa requisição, o arquivo de sessão não a contém mais:

1
2
3
a:3:{s:6:"_token";s:40:"X0omnUmKl13zVLUrzTdZy5mWN7R6fBaiOmfEUPpr";
     s:9:"_previous";a:2:{s:3:"url";s:27:"http://localhost:8000/tasks";s:5:"route";s:5:"tasks";}
     s:6:"_flash";a:2:{s:3:"old";a:0:{}s:3:"new";a:0:{}}}

Uma nova requisição GET não exibiria mais a mensagem. A lista de tarefas, por outro lado, é armazenada em um arquivo de cache cujo nome é calculado a partir da chave ([storage/framework/cache/data/55/d8/55d8727a05eb80b0788af57a5317f3e0a1f4aa55]):

9999999999a:2:{i:0;s:14:"Read chapter 3";i:1;s:16:"Do the exercises";}

Os dez primeiros dígitos representam a data de expiração do valor (neste caso, nunca); o restante é a lista serializada.

4.8.5. Execução

Adição de uma tarefa: o navegador seguiu o redirecionamento; a URL corresponde à página GET, que pode ser recarregada com segurança.

Image

Uma entrada inválida, reexibida com sua mensagem de erro:

Image

O contraexemplo: a página é a resposta a um POST, e sua URL é [/tasks/without-prg]. Se você clicar em [F5], o navegador pergunta se você deseja reenviar o formulário; se você concordar, a tarefa é adicionada uma segunda vez.

Image

Um princípio do protocolo HTTP: uma requisição GET não altera nada. Navegadores, mecanismos de busca e ferramentas que pré-carregam páginas seguem links livremente, sem pedir permissão ao usuário. Um link “excluir” ([<a href="/contacts/2/delete">]) seria, portanto, perigoso: um robô que rastreasse o site apagaria tudo. Em uma aplicação web:

  • a visualização é feita por meio de um link ([<a href>]), que envia uma requisição GET;
  • a edição (salvar, duplicar, excluir) é feita por meio de um botão colocado em um formulário, protegido por um token anti-CSRF.

Este exemplo gerencia uma lista de contatos e exibe uma janela de confirmação antes de cada exclusão.

4.9.1. O serviço: app/Services/ContactsService.php

<?php
// app/Services/ContactsService.php: os contatos, compartilhados por todos, armazenados no
// cache do Laravel (veja o exemplo 20)

namespace App\Services;

use App\Models\Contact;
use Illuminate\Support\Facades\Cache;

class ContactsService
{
    private const KEY = 'contacts';

    /** @return array{contacts: list<Contact>, lastId: int} */
    private function data(): array
    {
        return Cache::get(self::KEY, [
            'contacts' => [
                new Contact(1, 'Marie Durand', '01 23 45 67 89'),
                new Contact(2, 'Paul Martin', '06 12 34 56 78'),
                new Contact(3, 'Philippe Jandot', '02 98 76 54 32'),
            ],
            'lastId' => 3,
        ]);
    }

    // uma modificação dos dados, sob lock: a função recebe os dados,
    // os modifica (&) e retorna o resultado da operação
    private function editData(callable $operation): mixed
    {
        return Cache::lock('contacts-lock', 10)->block(5, function () use ($operation) {
            $data = $this->data();
            $result = $operation($data);
            Cache::forever(self::KEY, $data);
            return $result;
        });
    }

    /** @return list<Contact> */
    public function list(): array
    {
        return $this->data()['contacts'];
    }

    // o contato, ou null se ele não existir
    public function read(int $id): ?Contact
    {
        return array_find($this->list(), fn (Contact $c) => $c->id === $id);
    }

    public function edit(int $id, string $name, string $phone): ?Contact
    {
        return $this->editData(function (array &$data) use ($id, $name, $phone) {
            foreach ($data['contacts'] as $i => $contact) {
                if ($contact->id === $id) {
                    // um contato é imutável (readonly): construímos um novo,
                    // que substitui o antigo no array
                    return $data['contacts'][$i] = new Contact($id, $name, $phone);
                }
            }
            return null;
        });
    }

    public function add(string $name, string $phone): Contact
    {
        return $this->editData(function (array &$data) use ($name, $phone) {
            $contact = new Contact(++$data['lastId'], $name, $phone);
            $data['contacts'][] = $contact;
            return $contact;
        });
    }

    public function delete(int $id): ?Contact
    {
        return $this->editData(function (array &$data) use ($id) {
            foreach ($data['contacts'] as $i => $contact) {
                if ($contact->id === $id) {
                    // array_splice remove o item i do array e renumera os seguintes
                    array_splice($data['contacts'], $i, 1);
                    return $contact;
                }
            }
            return null;
        });
    }
}

Os contatos são armazenados no cache, assim como as tarefas do exemplo 20. Cada contato é um objeto [Contact] imutável (um ID, um nome, um telefone), armazenado em um array junto com o último ID atribuído. Alguns pontos sobre o [PHP]:

  • Linhas 29–37: todas as modificações seguem o mesmo padrão: adquirir o lock, ler os dados, modificá-los, gravá-los de volta e liberar o lock. Este método grava no array uma única vez; cada modificação passa a ele uma função (do tipo [callable], “chamável”), que recebe os dados e os modifica. A função deve modificar o próprio array, e não uma cópia: seu parâmetro é declarado como [array &$data], em que [&] especifica uma passagem por referência (sem [&], um array é copiado; veja o exemplo 06);
  • linhas 51–63: um contato é imutável: cria-se um novo, que substitui o antigo no array. Uma atribuição é uma expressão cujo valor é o valor atribuído: [return $data['contacts'][$i] = new Contact(...)] substitui o contato e o retorna;
  • linha 68: [++] colocado antes de uma variável a incrementa em 1 e retorna o novo valor;
  • linha 80: [array_splice] remove um elemento do array e renumera os elementos seguintes;
  • Os métodos retornam [null] para um contato inexistente: cabe ao controller decidir a resposta.

4.9.2. O controller: app/Http/Controllers/ContactsController.php

<?php
// app/Http/Controllers/ContactsController.php: links (GET) e botões (POST, DELETE)

namespace App\Http\Controllers;

use App\Models\Contact;
use App\Services\ContactsService;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\View\View;

class ContactsController
{
    public function __construct(private ContactsService $contacts)
    {
    }

    // o contato, ou uma resposta 404 se ele não existir
    private static function contactOr404(?Contact $contact): Contact
    {
        abort_if($contact === null, 404, 'unknown contact');
        return $contact;
    }

    // um LINK (<a href>): uma requisição GET, que não modifica nada
    public function list(): View
    {
        return view('contacts.list', ['contacts' => $this->contacts->list()]);
    }

    public function details(int $id): View
    {
        return view('contacts.details', ['contact' => self::contactOr404($this->contacts->read($id))]);
    }

    // um BOTÃO em um formulário POST: uma requisição que modifica dados
    public function save(Request $request, int $id): RedirectResponse
    {
        $contact = self::contactOr404($this->contacts->edit($id,
            $request->string('name')->value(), $request->string('phone')->value()));
        return redirect()->route('contacts')->with('message', "The contact [$contact->name] has been edited.");
    }

    // mesmo formulário, outro botão (atributo formaction): outra action
    public function duplicate(Request $request, int $id): RedirectResponse
    {
        $copy = $this->contacts->add($request->string('name')->value().' (copy)',
            $request->string('phone')->value());
        return redirect()->route('contacts')->with('message', "The contact [$copy->name] has been created.");
    }

    // uma requisição DELETE, simulada por um formulário POST (veja @method na view)
    public function delete(int $id): RedirectResponse
    {
        $contact = self::contactOr404($this->contacts->delete($id));
        return redirect()->route('contacts')->with('message', "The contact [$contact->name] has been deleted.");
    }
}
  • linhas 19–23: uma função utilitária: um contato inexistente encerra a ação com uma resposta 404 ([abort_if], veja o exemplo 15);
  • linhas 26–34: as duas ações GET, que não modificam nada: a lista e a ficha de um contato;
  • linhas 37–42: salvar a ficha: uma ação POST, que segue o esquema PRG. A mesma URL, [/contacts/2], é tratada por duas ações diferentes, dependendo do método: GET exibe, POST salva;
  • Linhas 45–50: duplicação — outra ação POST, disparada por um segundo botão do mesmo formulário;
  • Linhas 53–57: a exclusão, tratada por uma requisição DELETE.

A tabela de rotas:

<?php
// routes/web.php: as rotas do exemplo 21

use App\Http\Controllers\ContactsController;
use Illuminate\Support\Facades\Route;

Route::prefix('contacts')->controller(ContactsController::class)->group(function () {
    Route::get('/', 'list')->name('contacts');
    Route::get('{id}', 'details')->whereNumber('id')->name('contacts.details');
    Route::post('{id}', 'save')->whereNumber('id')->name('contacts.save');
    Route::post('{id}/duplicate', 'duplicate')->whereNumber('id')->name('contacts.duplicate');
    Route::delete('{id}', 'delete')->whereNumber('id')->name('contacts.delete');
});
  • Linha 12: a exclusão é declarada para o método HTTP DELETE, que o protocolo HTTP especifica para excluir um recurso. No entanto, um formulário HTML só pode enviar requisições GET e POST. O [Laravel] contorna essa limitação: um formulário POST contendo um campo oculto [_method], com o valor [DELETE] (ou [PUT], [PATCH]), é tratado como uma requisição desse método. Isso é o method spoofing, implementado pela diretiva [@method] nas views.

4.9.3. As views

@extends('layout')

@section('content')
  <h1 class="h3">Contacts</h1>
  <table class="table align-middle">
    <tbody>
      @foreach ($contacts as $contact)
        <tr>
          <td>{{ $contact->name }}</td>
          <td>{{ $contact->phone }}</td>
          <td class="text-end">
            {{-- view: a simple link; route() places the id in the path: /contacts/2 --}}
            <a class="btn btn-sm btn-outline-primary" href="{{ route('contacts.details', $contact->id) }}">View</a>
            {{-- delete: a form, whose submission will be confirmed --}}
            <form method="post" class="d-inline" action="{{ route('contacts.delete', $contact->id) }}"
                  data-confirmation="Delete the contact {{ $contact->name }}?">
              {{-- the anti-CSRF token, required for any request that is not a GET --}}
              @csrf
              {{-- the DELETE method, which an HTML form cannot send --}}
              @method('DELETE')
              <button class="btn btn-sm btn-outline-danger" type="submit">Delete</button>
            </form>
          </td>
        </tr>
      @endforeach
    </tbody>
  </table>
@endsection
  • linha 13: um link, apresentado como botão pelas classes do [Bootstrap] ([btn]...): a aparência nada tem a ver com o método HTTP. [route('contacts.details', $contact->id)] coloca o ID no caminho: [/contacts/2] (um único parâmetro pode ser fornecido sem um array);
  • Linhas 15–22: um formulário para cada botão “Delete”, sem outros campos além do token e do método. A classe [d-inline] o exibe na mesma linha do link. O atributo [data-confirmation] contém a mensagem de confirmação; os atributos [data-...] não são especificados e destinam-se ao [JavaScript] da página;
  • linha 18: o token anti-CSRF (exemplo 18), exigido para qualquer requisição que não seja GET;
  • linha 20: a diretiva [@method] escreve o campo oculto [_method]: [<input type="hidden" name="_method" value="DELETE">].
@extends('layout')

@section('content')
  <h1 class="h3">Contact no. {{ $contact->id }}</h1>
  <form method="post" action="{{ route('contacts.save', $contact->id) }}">
    @csrf
    <div class="mb-2">
      <label class="form-label" for="name">Name</label>
      <input class="form-control" id="name" name="name" value="{{ $contact->name }}">
    </div>
    <div class="mb-3">
      <label class="form-label" for="phone">Phone</label>
      <input class="form-control" id="phone" name="phone" value="{{ $contact->phone }}">
    </div>
    {{-- two submit buttons for the same form --}}
    <button class="btn btn-primary" type="submit">Save</button>
    <button class="btn btn-outline-primary" type="submit"
            formaction="{{ route('contacts.duplicate', $contact->id) }}">Duplicate</button>
    <a class="btn btn-link" href="{{ route('contacts') }}">Back to the list</a>
  </form>
@endsection
  • Linhas 16–18: dois botões de envio para o mesmo formulário: “Save” envia o formulário para o endereço especificado por seu atributo [action], e “Duplicate” o envia para o endereço especificado por seu atributo [formaction] (exemplo 20). Este formulário não usa [@method]: o campo [_method] seria enviado pelos dois botões, e a duplicação também se tornaria uma requisição PUT ou DELETE;
  • Linha 19: volta à lista: um link.

4.9.4. A janela de confirmação

O navegador pode exibir uma caixa de confirmação (função [JavaScript] [confirm]), mas ela não é muito atraente, e sua aparência depende do navegador. Aqui usamos uma janela modal do [Bootstrap], exibida por algumas linhas de [JavaScript]. A janela é um fragmento incluído no template e, portanto, está presente — embora oculta — em todas as páginas:

{{-- a single window for the whole page, hidden (d-none) at first --}}
<div id="confirmation-modal" class="d-none">
  <div class="modal-backdrop fade show"></div>
  <div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true">
    <div class="modal-dialog modal-dialog-centered">
      <div class="modal-content">
        <div class="modal-header">
          <h5 class="modal-title">Confirmation</h5>
        </div>
        <div class="modal-body">
          <p class="mb-0" id="confirmation-modal-message"></p>
        </div>
        <div class="modal-footer">
          <button type="button" class="btn btn-secondary" data-action="no">No, go back</button>
          <button type="button" class="btn btn-danger" data-action="yes">Yes, confirm</button>
        </div>
      </div>
    </div>
  </div>
</div>
  • linha 2: a classe [d-none] do [Bootstrap] oculta o elemento;
  • linhas 3–4: o fundo cinza, seguido da janela, são renderizados pelas classes do [Bootstrap];
  • linha 11: a posição da mensagem;
  • linhas 14–15: os dois botões, do tipo [button] (e não [submit]: eles não enviam nenhum formulário), distinguidos por seu atributo [data-action].
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Contacts</title>
  <link rel="stylesheet" href="{{ route('bootstrap', 'css/bootstrap.min.css') }}">
  <link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
  <div class="container py-3" style="max-width: 40rem">
    @session('message')
      <div class="alert alert-success" role="status">{{ $value }}</div>
    @endsession
    <main>
      @yield('content')
    </main>
  </div>
  {{-- the confirmation window, present in all the pages --}}
  @include('fragments.confirmation')
  {{-- the script, at the end of the page: the elements it looks for already exist --}}
  <script src="{{ asset('js/app.js') }}"></script>
</body>
</html>
  • linha 19: a janela, incluída em todas as páginas;
  • linha 21: o script, colocado no final da página: quando ele é executado, os elementos que ele procura já existem. Ele fica armazenado na pasta [public/js].

O script [public/js/app.js]:

// confirmação dos formulários que carregam o atributo data-confirmation="..."
// Sem JavaScript, esses formulários são simplesmente enviados sem confirmação.
(() => {
  const modal = document.getElementById('confirmation-modal');
  const message = document.getElementById('confirmation-modal-message');
  let pending = null; // o formulário a enviar se o usuário confirmar

  // 1. interceptamos o envio dos formulários a confirmar
  document.querySelectorAll('form[data-confirmation]').forEach((form) => {
    form.addEventListener('submit', (event) => {
      event.preventDefault(); // o envio é suspenso
      pending = form;
      message.textContent = form.dataset.confirmation;
      modal.classList.remove('d-none'); // a janela aparece
    });
  });

  // 2. os dois botões da janela
  modal.addEventListener('click', (event) => {
    const action = event.target.dataset.action;
    if (action === 'yes') {
      pending.submit(); // envio, SEM disparar novamente o evento 'submit'
    } else if (action === 'no') {
      modal.classList.add('d-none');
      pending = null;
    }
  });
})();
  • linha 3: o código é envolvido em uma função anônima, que é executada imediatamente; suas variáveis não interferem nas dos outros scripts da página;
  • linhas 4–6: a janela, o local da mensagem e o formulário que aguarda confirmação;
  • linhas 9–14: para cada formulário que tenha um atributo [data-confirmation], o evento [submit] — disparado quando o formulário é enviado — é interceptado. [preventDefault()] suspende o envio; o formulário fica em espera, e sua mensagem ([dataset.confirmation], o valor do atributo [data-confirmation]) é exibida na janela, que aparece;
  • linhas 19–25: um único handler para os cliques na janela: [event.target] é o elemento clicado; seu atributo [data-action] especifica de qual botão se trata. “Yes” envia o formulário pendente com o método [submit()], que — ao contrário de clicar em um botão — não dispara o evento [submit] (caso contrário, a janela reapareceria); “No” oculta a janela.

Sem [JavaScript], o formulário é simplesmente enviado sem confirmação: a página continua utilizável. Isso é aprimoramento progressivo: [JavaScript] acrescenta comodidade, mas a aplicação não depende dele.

4.9.5. Execução

A lista de contatos:

Image

Clicar em “Delete” exibe a janela de confirmação:

Image

Após a confirmação, a requisição DELETE (simulada), o redirecionamento e a mensagem pop-up:

Image

A ficha de um contato, com seus dois botões de envio:

Image

Uma requisição sem token anti-CSRF é rejeitada, e um contato inexistente retorna um erro 404:

curl -i -X POST -d "_method=DELETE" http://localhost:8000/contacts/2
curl -i http://localhost:8000/contacts/9
HTTP/1.1 419 unknown status
Content-Type: text/html; charset=utf-8
...
        <title>Page Expired</title>
...
HTTP/1.1 404 Not Found
Content-Type: text/html; charset=utf-8
...
        <title>Not Found</title>
...

As páginas de erro ainda são as páginas em inglês do [Laravel]. O capítulo sobre o ciclo de vida da requisição mostrará como substituí-las por páginas personalizadas.