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
4.1.1. O modelo da view: app/Models/PageModel.php
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
- 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
- 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
Uma view não precisa receber um objeto: a variável [$name] é uma string.
4.1.5. Execução


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

A página gerada:
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.
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 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]:
- 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:
- 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
- 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
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
- 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
- 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.
- 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:
Por fim, a terceira página não usa o template:
4.3.6. Execução



A página da equipe, como recebida pelo navegador (as linhas em branco deixadas por comentários e diretivas foram removidas):
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):
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.
4.4.1. Funções: app/Helpers/Formats.php
- 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
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
- 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
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
- 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>]).
- 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].
- 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.
- 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.
- 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


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.

Um trecho do HTML produzido:
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
- 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
- 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.
4.5.3. A view: resources/views/books/search.blade.php
- 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

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

A URL da página de resultados contém os campos do formulário: [/search?keyword=le&genre=novel]. A resposta do formulário:
“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
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
- 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
- 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

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):
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:

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]:
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:
(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
- 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):
É 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
- 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:
- 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
- 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.
- 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.
[$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:

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:
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:
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]:

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
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
- 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:
4.8.3. As views
- 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.
- 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:
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):
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:
A mensagem é exibida e, depois dessa requisição, o arquivo de sessão não a contém mais:
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]):
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.

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

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.

4.9. Exemplo 21: links, botões e confirmação
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
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
- 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:
- 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
- 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">].
- 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:
- 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].
- 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]:
- 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:

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

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

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

Uma requisição sem token anti-CSRF é rejeitada, e um contato inexistente retorna um erro 404:
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.