Skip to content

3. O modelo da action

Uma action precisa das informações enviadas pelo navegador: os parâmetros da URL ([?name=martin&age=42]), os campos de formulário, o corpo JSON da requisição e, às vezes, um cabeçalho HTTP da requisição. O curso original se refere a todas essas informações como o modelo da action. Este capítulo mostra como uma action do [Laravel] obtém essas informações, as converte para o tipo correto e as valida. Esse processo se chama data binding.

[Laravel] fornece acesso às informações da requisição por meio do objeto [Request] (exemplo 05), na forma de strings, junto com alguns métodos de conversão. Para verificar os dados, ele dispõe de um sistema completo de validação: os dados esperados são descritos por meio de regras (“obrigatório”, “um inteiro entre 0 e 150” etc.), e o [Laravel] verifica se os dados as cumprem. Primeiro leremos os parâmetros manualmente (exemplo 07) e depois usaremos essas regras para validá-los (exemplos 08 a 12). No próximo capítulo, o mesmo sistema validará os formulários HTML.

Nota sobre a terminologia: no próximo capítulo, a palavra “modelo” se referirá principalmente aos dados que uma action passa à sua view. O modelo de uma action, como usado neste capítulo, é aquilo que ela recebe. [Laravel] também usa a palavra *model* para as classes que representam tabelas de banco de dados (capítulo 9): esse é um terceiro significado.

Os exemplos 07 a 12 são executados da mesma forma que os do capítulo anterior: abra um terminal na pasta do exemplo e execute [php artisan serve]; [Ctrl-C] interrompe o servidor. Seus arquivos [bootstrap/app.php] são todos semelhantes: eles adicionam o middleware [ReadableJson] do exemplo 03, o que resulta em um JSON legível. Só os comentaremos quando introduzirem algo novo.

3.1. Exemplo 07: Os parâmetros da URL

Os parâmetros da URL são a parte que vem depois de [?]: [?name=martin&age=42]. Essa parte é chamada de query string (*query string*). Cada parâmetro é um par [name=value]; os pares são separados por [&]. O controller [ParametersController]:

<?php
// app/Http/Controllers/ParametersController.php: os parâmetros da URL (a "query string")

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class ParametersController
{
    // /parameters/action01?name=martin: query retorna o valor do parâmetro, ou
    // null se ele estiver ausente
    public function action01(Request $request): string
    {
        $name = $request->query('name');
        return "name = [$name], of type ".get_debug_type($name);
    }

    // /parameters/action02?age=42: integer CONVERTE o valor (uma string) em um
    // inteiro; um parâmetro ausente, ou que não seja um inteiro, resulta em 0
    public function action02(Request $request): string
    {
        $age = $request->integer('age');
        return "age = [$age], of type ".get_debug_type($age);
    }

    // /parameters/action03?age=42: um parâmetro OBRIGATÓRIO; sua ausência, ou um
    // valor que não seja um inteiro, interrompe a action com uma resposta 400 (Bad Request)
    public function action03(Request $request): string
    {
        $text = $request->query('age');
        if ($text === null) {
            // abort lança uma exceção, que o Laravel transforma em uma resposta de erro
            abort(400, 'the [age] parameter is required');
        }
        // a conversão fica por nossa conta: filter_var retorna o inteiro, ou false
        $age = filter_var($text, FILTER_VALIDATE_INT);
        if ($age === false) {
            abort(400, "[$text] is not an integer");
        }
        return "age = [$age], of type ".get_debug_type($age);
    }

    // /parameters/action04?page=2: um valor padrão se o parâmetro estiver ausente
    public function action04(Request $request): string
    {
        $page = $request->integer('page', 1);
        return "page = [$page]";
    }

    // /parameters/action05?q=laravel: o nome do parâmetro da URL não é necessariamente
    // o da variável PHP
    public function action05(Request $request): string
    {
        $search = $request->query('q');
        return "search = [$search]";
    }

    // /parameters/action06?name=martin&age=42: todos os parâmetros de uma vez, como um array
    public function action06(Request $request): array
    {
        return $request->query();
    }
}
  • linha 14: o método [query] da requisição retorna o valor de um parâmetro da URL, já decodificado, ou [null] se ele estiver ausente; nunca causa um erro;
  • Linha 15: a action exibe o valor e seu tipo: a função [get_debug_type] retorna o nome do tipo de um valor. Um valor obtido da URL é sempre uma string ([string]). O operador [.] concatena a string interpolada e o tipo;
  • linha 22: o método [integer] lê o parâmetro e o converte em um inteiro. Se a conversão falha ([abc]) ou se o parâmetro está ausente, ele retorna 0: a action não consegue distinguir esses casos de uma idade 0 realmente informada, e o erro de entrada passa despercebido. Da mesma forma, existem [float], [boolean] ([1], [true], [on], [yes] são válidos), [string], [date] (exemplo 12), [enum];
  • linhas 30–40: um parâmetro obrigatório e uma conversão manual que distingue os dois erros possíveis. [abort(400, message)] encerra a action com uma resposta 400 (*Bad Request*, a requisição é inválida), acompanhada da mensagem (veja o exemplo 03). A função [filter_var] do [PHP], com o filtro [FILTER_VALIDATE_INT], retorna o inteiro contido na string, ou [false] se a string não for um inteiro;
  • linha 46: o segundo parâmetro de [integer] é um valor padrão, usado se o parâmetro estiver ausente. Esse é tipicamente o caso do número de página em uma listagem;
  • linha 54: não é obrigatório dar à variável [PHP] o mesmo nome do parâmetro da URL. Os mecanismos de busca costumam usar um parâmetro curto, como [q] (*query*);
  • linha 61: sem parâmetro, [query] retorna todos os parâmetros da URL em um array associativo, que a action retorna: o [Laravel] o transforma em JSON (veja o exemplo 03).

A tabela de roteamento declara as seis rotas por meio de um laço:

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

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

Route::prefix('parameters')->controller(ParametersController::class)->group(function () {
    foreach (['action01', 'action02', 'action03', 'action04', 'action05', 'action06'] as $action) {
        Route::get($action, $action);
    }
});
  • Linha 8: o laço [foreach] percorre um array: a cada iteração, a variável [$action] assume o valor do próximo elemento. Cada rota recebe o nome de sua action: [Route::get('action01', 'action01')]... A tabela de roteamento é apenas mais um arquivo [PHP]: você pode escrever nela o código que quiser.

Vamos testar cada action com o [curl]. Um parâmetro presente e, depois, ausente:

curl -i "http://localhost:8000/parameters/action01?name=martin"
curl http://localhost:8000/parameters/action01
1
2
3
4
5
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8

name = [martin], of type string
name = [], of type null

As aspas em torno de "URL" são necessárias em um terminal: sem elas, o shell interpretaria [&] (que executa um comando em segundo plano no [Linux]) e [?]. O valor [null], quando inserido em uma string, se torna uma string vazia. Um valor que contenha espaços ou caracteres especiais deve ser codificado na URL: um espaço se torna [%20], e [&] se torna [%26] (caso contrário, separaria dois parâmetros). O navegador faz isso automaticamente; com o [curl], é preciso escrevê-lo por extenso. [PHP] decodifica o valor antes que a action o leia:

curl "http://localhost:8000/parameters/action01?name=jean%20dupont%20%26%20sons"
name = [jean dupont & sons], of type string

Conversão com [integer] — bem-sucedida, com falha e, depois, sem parâmetros:

1
2
3
curl "http://localhost:8000/parameters/action02?age=42"
curl "http://localhost:8000/parameters/action02?age=abc"
curl http://localhost:8000/parameters/action02
1
2
3
age = [42], of type int
age = [0], of type int
age = [0], of type int

O parâmetro obrigatório da action 03 está ausente e, depois, inválido. Solicitamos uma resposta JSON (cabeçalho [Accept], veja o exemplo 03), que contém a mensagem de [abort]:

curl -i -H "Accept: application/json" http://localhost:8000/parameters/action03
curl -H "Accept: application/json" "http://localhost:8000/parameters/action03?age=abc"
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "the [age] parameter is required",
    "exception": "Symfony\\Component\\HttpKernel\\Exception\\HttpException",
    ...
}
{
    "message": "[abc] is not an integer",
    "exception": "Symfony\\Component\\HttpKernel\\Exception\\HttpException",
    ...
}

Em um navegador, no modo de depuração, uma resposta 400 exibe a página de erro do [Laravel], com a mensagem:

Image

O valor padrão e o parâmetro renomeado:

1
2
3
curl http://localhost:8000/parameters/action04
curl "http://localhost:8000/parameters/action04?page=3"
curl "http://localhost:8000/parameters/action05?q=laravel"
1
2
3
page = [1]
page = [3]
search = [laravel]

Por fim, todos os parâmetros de uma vez. O parâmetro [name] aparece duas vezes:

curl "http://localhost:8000/parameters/action06?name=martin&age=42&name=durand"
1
2
3
4
{
    "name": "durand",
    "age": "42"
}

O parâmetro [name] mantém apenas seu último valor: essa é uma regra do [PHP], que veremos novamente no exemplo 10. A idade continuou sendo uma string (["42"], entre aspas no JSON): nenhuma conversão foi solicitada. Em um navegador (aqui, o [Chromium]), o JSON é exibido exatamente como o servidor o formatou; a caixa de seleção “Pretty-print” o indentaria se ele já não estivesse indentado. A barra de endereço também mostra a codificação dos caracteres acentuados na URL ([é] se torna [%C3%A9], com seus dois bytes em [UTF-8]):

Image

Este primeiro exemplo ilustra os limites da abordagem manual: para cada parâmetro, é preciso escrever a leitura, a conversão e o tratamento de valores ausentes e de erros. Com dez parâmetros, o código da action ficaria sobrecarregado por essas verificações. É melhor descrever o que se espera e deixar o framework verificar. Esse é o objetivo do exemplo seguinte.

3.2. Exemplo 08: Um modelo de action descrito por uma classe

[Laravel] valida os dados da requisição por meio de regras de validação. Uma regra tem um nome ([required], [integer], [email]...) e, às vezes, parâmetros ([min:2], [between:0,150]); as regras de um campo são escritas como uma string, separadas por [|], ou como um array. [Laravel] fornece cerca de cem delas. O lugar natural para descrever o modelo de uma action é uma requisição de formulário (*form request*): uma classe que herda de [FormRequest] e cujo método [rules] retorna as regras de cada parâmetro.

3.2.1. O modelo: app/Http/Requests/PersonRequest.php

<?php
// app/Http/Requests/PersonRequest.php: o modelo da action, uma classe que
// descreve os parâmetros esperados e suas restrições

namespace App\Http\Requests;

use App\Models\Person;
use Illuminate\Foundation\Http\FormRequest;

class PersonRequest extends FormRequest
{
    // as REGRAS de validação, parâmetro por parâmetro
    public function rules(): array
    {
        return [
            // obrigatório, uma string de 2 a 20 caracteres
            'name' => 'required|string|min:2|max:20',
            // obrigatório, um inteiro entre 0 e 150
            'age' => 'required|integer|between:0,150',
            // somente um destes três valores
            'title' => 'required|in:Mr,Mme,Melle',
            // opcional (nullable); se presente, um endereço de e-mail válido
            'email' => 'nullable|email',
        ];
    }

    // os parâmetros validados, na forma de um objeto tipado
    public function person(): Person
    {
        $values = $this->validated();
        return new Person($values['name'], (int) $values['age'], $values['title'],
            $values['email'] ?? null);
    }
}
  • Linha 10: a classe ([extends]) herda de [FormRequest], que por sua vez herda de [Request]: um objeto [PersonRequest] é uma requisição, com todos os métodos do exemplo 07, mais regras de validação;
  • linhas 13–24: as regras, em um array associativo: para cada parâmetro, a string que contém suas regras;
  • linha 17: [required]: o parâmetro é obrigatório (se estiver ausente ou vazio, é rejeitado); [string]: uma string; [min:2] e [max:20]: para uma string, seu comprimento deve estar entre 2 e 20 caracteres;
  • linha 19: [integer]: o valor deve ser um inteiro (["42"] é válido, ["abc"] não é); [between:0,150]: para um número, seu valor deve estar entre 0 e 150. As regras [min], [max] e [between] se adaptam, assim, ao tipo do valor: um comprimento para uma string, um valor para um número e um número de elementos para um array (por exemplo, 10);
  • linha 21: [in:Mr,Mme,Melle]: um dos três valores listados, e somente esses;
  • linha 23: [nullable]: o parâmetro é opcional (é aceito se estiver ausente ou vazio); [email]: se presente, um endereço de e-mail válido;
  • linhas 28–33: um método adicionado à classe: ele retorna os dados validados na forma de um objeto [Person] (veja abaixo). [$this->validated()] retorna apenas os dados que foram validados: um parâmetro sem regra não é incluído. A validação realizada pelo [Laravel] verifica os dados, mas não os converte: a idade validada continua sendo a string ["42"]. É o operador de conversão [(int)] que a converte em inteiro. O operador [??] retorna seu operando esquerdo se ele existir e não for [null]; caso contrário, retorna o operando direito: [$values['email'] ?? null] resulta em [null] se o endereço não estiver no array.

Este modelo descreve os dados esperados; ele não contém nenhuma instrução de validação. Isso é conhecido como um estilo declarativo. A classe [Person] é uma classe imutável, nos moldes da do exemplo 03:

<?php
// app/Models/Person.php: uma pessoa

namespace App\Models;

readonly class Person
{
    public function __construct(
        public string $name,
        public int $age,
        public string $title,
        public ?string $email,
    ) {
    }
}
  • linha 12: [?string]: uma string, ou [null].

3.2.2. A action: app/Http/Controllers/PersonsController.php

<?php
// app/Http/Controllers/PersonsController.php: uma action cujo modelo é uma classe FormRequest

namespace App\Http\Controllers;

use App\Http\Requests\PersonRequest;

class PersonsController
{
    // /persons/action01?name=martin&age=42&title=Mr
    // O parâmetro do tipo PersonRequest é VALIDADO pelo Laravel ANTES da chamada da
    // action: um modelo inválido lança uma ValidationException, transformada em uma
    // resposta 400 por bootstrap/app.php, e a action nunca é chamada
    public function action01(PersonRequest $request): array
    {
        $person = $request->person();
        return [
            'received' => $request->validated(),
            'person' => $person,
            'ageType' => get_debug_type($person->age),
        ];
    }
}
  • Linha 14: a action exige um parâmetro do tipo [PersonRequest], enquanto o exemplo 07 exigia um [Request]. O [Laravel] então cria um objeto [PersonRequest] a partir da requisição atual e o valida antes de chamar a action: ele verifica cada regra de cada parâmetro. Se todas as regras forem cumpridas, a action é chamada. Caso contrário, o [Laravel] lança uma exceção [ValidationException], que contém uma lista de todos os erros (não apenas o primeiro), e a action nunca é chamada: ela, portanto, não precisa lidar com dados inválidos;
  • Linhas 16–20: a action retorna os dados validados como estão e, depois, como um objeto [Person], junto com o tipo da idade, para ilustrar a diferença.

Quem trata a exceção [ValidationException]? Por padrão, o próprio [Laravel] , e sua resposta depende do cliente. Para uma requisição que espera JSON (cabeçalho [Accept: application/json]), a resposta é um 422 (*Unprocessable Content*), que descreve os erros em JSON. Para uma requisição comum, originada de um formulário HTML, a resposta é um redirecionamento para a página anterior, com os erros preservados para o formulário que será reexibido (veremos isso no próximo capítulo). Aqui, queremos uma resposta de erro em JSON, em todos os casos, com o código 400. Esse é o papel do [bootstrap/app.php].

3.2.3. Tratamento de erros: bootstrap/app.php

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

use App\Http\Middleware\ReadableJson;
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;
use Illuminate\Validation\ValidationException;

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

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(web: __DIR__.'/../routes/web.php')
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->append(ReadableJson::class);
    })
    ->withExceptions(function (Exceptions $exceptions): void {
        // um modelo inválido: a exceção ValidationException se torna, para
        // a aplicação INTEIRA, uma resposta 400 que detalha os erros
        $exceptions->render(function (ValidationException $e) {
            $errors = [];
            // errors(): campo -> lista de suas mensagens de erro
            foreach ($e->errors() as $field => $messages) {
                foreach ($messages as $message) {
                    $errors[] = ['field' => $field, 'message' => $message];
                }
            }
            return response()->json(['status' => 400, 'errors' => $errors], 400);
        });
    })
    ->create();
  • Linhas 17–30: o método [withExceptions] agora recebe uma função, que recebe o objeto [$exceptions] que descreve o tratamento de exceções da aplicação;
  • linhas 20–29: o método [render] registra um tratador de exceção: uma função que o [Laravel] chama quando uma action lança uma exceção do mesmo tipo que seu parâmetro (aqui, [ValidationException] ou uma classe derivada), e cujo valor de retorno é a resposta enviada. O [Laravel] identifica o tipo da exceção tratada com base no tipo do parâmetro da função. Declarado em [bootstrap/app.php], o tratador se aplica a todas as actions da aplicação: toda action que valida um modelo se beneficia dele, sem precisar escrever uma única linha de código de tratamento de erros;
  • linhas 23–27: [$e->errors()] retorna os erros em um array associativo: para cada campo com erro, a lista de suas mensagens de erro. O laço [foreach ($array as $key => $value)] percorre tanto as chaves quanto os valores. [$errors[] = ...] adiciona um elemento ao final do array [$errors];
  • linha 28: uma resposta JSON, com código de status 400.

3.2.4. Execução

Um modelo válido:

curl -i "http://localhost:8000/persons/action01?name=martin&age=42&title=Mr"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "received": {
        "name": "martin",
        "age": "42",
        "title": "Mr"
    },
    "person": {
        "name": "martin",
        "age": 42,
        "title": "Mr",
        "email": null
    },
    "ageType": "int"
}

Os dados validados contêm apenas os parâmetros recebidos; a idade está no formato string; o objeto [Person] contém a idade como inteiro (sem aspas no JSON), e o endereço ausente é [null]. Um nome cercado por espaços ([%20]) e um endereço presente:

curl "http://localhost:8000/persons/action01?name=%20%20martin%20&age=42&title=Mme&email=martin@example.com"
{
    "received": {
        "name": "martin",
        "age": "42",
        "title": "Mme",
        "email": "martin@example.com"
    },
    "person": {
        "name": "martin",
        "age": 42,
        "title": "Mme",
        "email": "martin@example.com"
    },
    "ageType": "int"
}

Os espaços em torno do nome desapareceram sem que o pedíssemos: dois middlewares, executados pelo [Laravel] para todas as requisições, transformam os parâmetros recebidos antes que uma action os leia. [TrimStrings] remove os espaços em torno de cada string; [ConvertEmptyStringsToNull] substitui cada string vazia por [null]. Agora não há nenhum parâmetro: os três campos obrigatórios estão ausentes.

curl -i http://localhost:8000/persons/action01
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "status": 400,
    "errors": [
        {
            "field": "name",
            "message": "The name field is required."
        },
        {
            "field": "age",
            "message": "The age field is required."
        },
        {
            "field": "title",
            "message": "The title field is required."
        }
    ]
}

Quatro campos inválidos de uma só vez:

curl "http://localhost:8000/persons/action01?name=m&age=abc&title=Mlle&email=xx"
{
    "status": 400,
    "errors": [
        {
            "field": "name",
            "message": "The name field must be at least 2 characters."
        },
        {
            "field": "age",
            "message": "The age field must be an integer."
        },
        {
            "field": "title",
            "message": "The selected title is invalid."
        },
        {
            "field": "email",
            "message": "The email field must be a valid email address."
        }
    ]
}

Todos os erros são informados de uma só vez, permitindo que o usuário corrija tudo de uma vez. Para o campo de idade [abc], apenas a regra [integer] é sinalizada: a regra [between] não se aplica a um valor que não é um número. As mensagens estão em inglês, o idioma padrão do [Laravel]. O exemplo seguinte as substitui por mensagens personalizadas.

3.3. Exemplo 09: Validação realizada pela action

No exemplo 08, um modelo inválido encerra a action, e o tratador da aplicação responde. Isso é conveniente para uma API, cujos clientes são programas que esperam uma resposta de erro padronizada. No entanto, uma página web costuma preferir reexibir o formulário com as mensagens de erro: nesse caso, a action deve decidir como tratar um modelo inválido. As classes [PersonRequest] e [Person] são as do exemplo 08.

09-action-validation/
├── app/
│   ├── Http/
│   │   ├── Controllers/
│   │   │   └── PersonsController.php
│   │   └── Requests/
│   │       └── PersonRequest.php
│   └── Models/
│       └── Person.php
├── lang/
│   └── en/
│       └── validation.php
└── ...

3.3.1. Mensagens personalizadas: lang/en/validation.php

As mensagens de erro do [Laravel] não estão fixas no código: cada mensagem é identificada por uma chave, e um arquivo de idioma associa um texto a cada chave. Os arquivos em inglês são incluídos com o framework; a aplicação pode fornecer seus próprios arquivos na pasta [lang], com uma subpasta por idioma, para substituir essas mensagens ou para adicionar outros idiomas. O idioma da aplicação é definido pelo arquivo [.env]:

APP_LOCALE=en

O arquivo de mensagens de validação se chama [validation.php]:

<?php
// lang/en/validation.php: as mensagens dos erros de validação, em inglês.
// Cada mensagem é designada pelo nome da sua REGRA (required, min...). Os
// marcadores :attribute, :min, :max... são substituídos pelo nome do campo e pelos
// parâmetros da regra
return [
    'required' => 'the field is required',
    'string' => 'a string is expected',
    'integer' => 'an integer is expected',
    'email' => 'invalid email address',
    'in' => 'unknown value',
    // algumas regras têm uma mensagem por tipo de valor: para uma string, min
    // se aplica ao seu comprimento; para um número, ao seu valor; para um array, ao
    // seu número de itens
    'min' => [
        'string' => ':min character(s) at least',
        'numeric' => 'the value must be greater than or equal to :min',
        'array' => ':min item(s) at least',
    ],
    'max' => [
        'string' => ':max character(s) at most',
        'numeric' => 'the value must be less than or equal to :max',
    ],
    'between' => [
        'numeric' => 'the value must be between :min and :max',
    ],
    'array' => 'a list is expected',
];
  • Linha 6: um arquivo de idioma é um arquivo [PHP] que retorna um array associativo: para cada chave, seu texto correspondente;
  • linhas 7–11: a chave de uma mensagem de validação é o nome da regra que falhou. Essa técnica (traduzir com base no nome do erro, e não em seu texto em inglês) é a usada no estudo de caso: os textos ali são identificados por chaves, que são traduzidas para o idioma do usuário;
  • linhas 15–19: as regras que se adaptam ao tipo do valor (por exemplo, a 08) têm uma mensagem para cada tipo: [string], [numeric], [array]. Os identificadores [:min] e [:max] são substituídos pelos parâmetros da regra ([min:2] significa “pelo menos 2 caracteres”). A tag [:attribute], que não usamos, seria substituída pelo nome do campo.

Uma chave ausente deste arquivo mantém a mensagem em inglês do framework: o [Laravel] mescla o arquivo da aplicação com o seu próprio. Para outro idioma, uma chave ausente recorre ao idioma de contingência, [APP_FALLBACK_LOCALE], que por padrão é o inglês. Traduções completas das mensagens do [Laravel], em muitos idiomas, são publicadas pela comunidade (o pacote [laravel-lang]).

3.3.2. A action: app/Http/Controllers/PersonsController.php

<?php
// app/Http/Controllers/PersonsController.php: é a action que decide o que fazer com um modelo inválido

namespace App\Http\Controllers;

use App\Http\Requests\PersonRequest;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Validator;

class PersonsController
{
    public function action01(Request $request): string
    {
        // um VALIDATOR: os dados a validar e as regras (as da
        // classe PersonRequest do exemplo 08)
        $validator = Validator::make($request->query(), (new PersonRequest())->rules());
        if ($validator->fails()) {
            // os erros, campo por campo: errors()->messages() fornece sua lista
            $items = '';
            foreach ($validator->errors()->messages() as $field => $messages) {
                $items .= "<li>$field: $messages[0]</li>";
            }
            return "<p>The form contains errors:</p><ul>$items</ul>";
        }
        // os dados validados
        $person = $validator->validated();
        // e(): o nome digitado é inserido no HTML; seus caracteres < > & " '
        // são substituídos por &lt; &gt;... (caso contrário, uma entrada poderia injetar HTML)
        return "<p>Welcome {$person['title']} ".e($person['name'])
            ." ({$person['age']} years old)</p>";
    }
}
  • Linha 16: a fachada [Validator] cria um validador — um objeto que aplica regras a dados. Os dados são os parâmetros da URL; as regras são as da classe [PersonRequest] do exemplo 08. Uma requisição de formulário é uma classe como qualquer outra: é possível criar uma instância dela, por meio de [new], para ler suas regras;
  • linha 17: [fails()] executa a validação e retorna [true] se pelo menos uma regra falhar. A própria action determina o que acontece em seguida: nenhuma exceção é lançada;
  • Linhas 19–23: os erros, campo por campo. [errors()] retorna um objeto [MessageBag] (uma “sacola” de mensagens), cujo método [messages()] retorna o array associativo campo → lista de mensagens. Para cada campo, a primeira mensagem, [$messages[0]], é colocada em uma tag [<li>]. O operador [.=] acrescenta uma string ao final de outra;
  • linha 26: os dados validados, em um array associativo;
  • linhas 29–30: em caso de sucesso, uma mensagem de boas-vindas. Dentro de uma string entre aspas, [{$person['title']}] insere um elemento do array (as chaves delimitam a expressão). O nome passa pela função [e] do [Laravel] (de *escape*), que substitui os caracteres com significado especial em HTML ([<], [>], [&], ["], [']) por suas entidades ([&lt;], [&gt;]...): elas serão exibidas como estão, em vez de interpretadas. Sem essa precaução, um usuário poderia informar um “nome” contendo HTML, ou até mesmo [JavaScript], que seria executado no navegador de qualquer pessoa que visualizasse a página. Essa é a vulnerabilidade de segurança mais comum na web: a injeção de script (*XSS*, *cross-site scripting*). O título e a idade não precisam dessa proteção: seus valores foram validados pelas regras (um de três valores permitidos, um inteiro). No próximo capítulo, a engine de views [Blade] fará esse escape automaticamente para qualquer valor inserido em uma página.

Uma entrada válida, seguida de uma entrada contendo quatro erros:

Image

Image

A resposta bruta à segunda requisição e a resposta para um nome contendo HTML:

curl "http://localhost:8000/persons/action01?name=m&age=abc&title=Mx&email=xx"
curl "http://localhost:8000/persons/action01?name=%3Cb%3Emartin%3C/b%3E&age=42&title=Mr"
<p>The form contains errors:</p><ul><li>name: 2 character(s) at least</li><li>age: an integer is expected</li><li>title: unknown value</li><li>email: invalid email address</li></ul>
<p>Welcome Mr &lt;b&gt;martin&lt;/b&gt; (42 years old)</p>

O nome [<b>martin</b>] (codificado como [%3Cb%3E...] na URL) é exibido como está, sem ficar em negrito: suas tags foram neutralizadas. Observe que a resposta, desta vez, tem código de status 200: foi a action que escolheu retornar uma página normal contendo os erros.

3.4. Exemplo 10: Parâmetros múltiplos

Um mesmo parâmetro pode aparecer várias vezes em uma URL: [?color=red&color=green]. É isso que um navegador envia para um grupo de caixas de seleção com o mesmo nome ou para uma lista de seleção múltipla (veja o próximo capítulo). O [PHP] trata esse caso à sua maneira. O controller [ArraysController]:

<?php
// app/Http/Controllers/ArraysController.php: um parâmetro que aparece várias vezes na URL

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Validator;

class ArraysController
{
    // /arrays/action01?color=red&color=green: para o PHP, o segundo parâmetro
    // SUBSTITUI o primeiro: apenas o ÚLTIMO valor é mantido
    public function action01(Request $request): array
    {
        return ['color' => $request->query('color'), 'raw' => $request->server('QUERY_STRING')];
    }

    // /arrays/action02?color[]=red&color[]=green: os colchetes pedem ao
    // PHP que armazene TODOS os valores em um array
    public function action02(Request $request): array
    {
        // array: o parâmetro na forma de um array (vazio se estiver ausente)
        $colors = $request->array('color');
        return ['color' => $colors, 'count' => count($colors)];
    }

    // /arrays/action03?color[]=red: um array, validado item por item
    public function action03(Request $request): array
    {
        $colors = $request->array('color');
        $validator = Validator::make(['color' => $colors], [
            // uma lista com pelo menos um item
            'color' => 'array|min:1',
            // cada item (*): "red", "green" ou "blue"
            'color.*' => 'in:red,green,blue',
        ]);
        $errors = [];
        foreach ($validator->errors()->messages() as $field => $messages) {
            $errors[] = "$field: $messages[0]";
        }
        return ['colors' => $colors, 'valid' => ! $errors, 'errors' => $errors];
    }
}
  • linha 15: para o [PHP], os parâmetros da URL formam um array associativo, em que cada chave tem apenas um valor: um parâmetro repetido substitui o anterior, e somente o último valor é mantido. A action também retorna, para comparação, a string bruta de parâmetros como enviada pelo navegador: [$request->server(...)] lê as variáveis que o servidor web transmite ao [PHP], incluindo [QUERY_STRING];
  • linhas 20–24: para obter todos os valores, o nome do parâmetro deve terminar com colchetes: [?color[]=red&color[]=green]. O [PHP] então armazena os valores em um array, e o valor do parâmetro [color]. O método [array] da requisição retorna o parâmetro como um array: vazio se estiver ausente, com um único elemento se tiver apenas um valor sem colchetes;
  • Linhas 31–36: o array é validado por regras. [array|min:1]: um array com pelo menos um elemento (a regra [min] se aplica ao número de elementos de um array; veja o exemplo 08). A chave [color.*] identifica cada elemento do array: cada um deve ser uma das três cores;
  • linha 41: o operador [!] (não) resulta em [true] para um array vazio, que equivale a “falso” em uma condição.

O arquivo [lang/en/validation.php] é o do exemplo 09. Os resultados:

1
2
3
curl "http://localhost:8000/arrays/action01?color=red&color=green"
curl -g "http://localhost:8000/arrays/action02?color[]=red&color[]=green"
curl http://localhost:8000/arrays/action02
{
    "color": "green",
    "raw": "color=red&color=green"
}
{
    "color": [
        "red",
        "green"
    ],
    "count": 2
}
{
    "color": [],
    "count": 0
}

A opção [-g] do [curl] o impede de interpretar por conta própria os colchetes da URL. Um navegador, por outro lado, os codifica ([color%5B%5D=red]), o que o [PHP] também entende. Quanto ao HTML, basta nomear as caixas de seleção de um grupo como [color[]]: é isso que o exemplo 18 fará. Essa regra se aplica especificamente ao [PHP]: os frameworks de outras linguagens ([Flask], [Spring MVC], [ASP.NET Core]) mantêm todos os valores de um parâmetro repetido, sem colchetes.

Validação: bem-sucedida, depois com falha por cor desconhecida e, depois, por lista vazia:

1
2
3
curl -g "http://localhost:8000/arrays/action03?color[]=red&color[]=blue"
curl -g "http://localhost:8000/arrays/action03?color[]=red&color[]=yellow"
curl http://localhost:8000/arrays/action03
{
    "colors": [
        "red",
        "blue"
    ],
    "valid": true,
    "errors": []
}
{
    "colors": [
        "red",
        "yellow"
    ],
    "valid": false,
    "errors": [
        "color.1: unknown value"
    ]
}
{
    "colors": [],
    "valid": false,
    "errors": [
        "color: 1 item(s) at least"
    ]
}

O erro referente à cor desconhecida menciona [color.1]: o campo e o índice do elemento problemático no array (o segundo, com índices começando em 0).

3.5. Exemplo 11: Parâmetros de uma requisição POST

Os exemplos anteriores usavam requisições GET, cujos parâmetros estão contidos na URL. Uma requisição POST transporta seus dados no corpo, em duas formas principais:

  • campos de um formulário HTML: o corpo tem a mesma sintaxe de uma query string ([name=martin&age=42]), e seu tipo (cabeçalho [Content-Type]) é [application/x-www-form-urlencoded];
  • um documento JSON, enviado por um programa ([JavaScript] em uma página, cliente de uma API...): o tipo é [application/json].

O controller [PostController]:

<?php
// app/Http/Controllers/PostController.php: os parâmetros de uma requisição POST

namespace App\Http\Controllers;

use App\Http\Requests\PersonRequest;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Validator;
use JsonException;

class PostController
{
    // os campos de um formulário HTML (corpo application/x-www-form-urlencoded):
    // post() retorna os parâmetros do CORPO da requisição, na forma de um array
    public function action01(Request $request): array
    {
        return [
            'receivedType' => $request->header('Content-Type'),
            'fields' => $request->post(),
        ];
    }

    // um corpo JSON: json() o desserializa; isJson() testa o tipo anunciado
    public function action02(Request $request): array
    {
        if (! $request->isJson()) {
            abort(415, 'the body of the request must be JSON');
        }
        // json_decode, com JSON_THROW_ON_ERROR: um JSON malformado lança uma exceção
        try {
            $body = json_decode($request->getContent(), true, flags: JSON_THROW_ON_ERROR);
        } catch (JsonException $e) {
            abort(400, 'Malformed JSON: '.$e->getMessage());
        }
        return ['receivedType' => $request->header('Content-Type'), 'body' => $body,
            'name' => $request->input('name')];
    }

    // um único campo do formulário
    public function action03(Request $request): string
    {
        $name = $request->input('name');
        return "name = [$name]";
    }

    // os campos do formulário, validados pelas regras da classe PersonRequest
    public function action04(Request $request): array
    {
        $validator = Validator::make($request->post(), (new PersonRequest())->rules());
        $errors = [];
        foreach ($validator->errors()->messages() as $field => $messages) {
            $errors[] = "$field: $messages[0]";
        }
        sort($errors);
        return ['person' => $errors ? null : $validator->validated(),
            'valid' => ! $errors, 'errors' => $errors];
    }
}
  • linha 18: o cabeçalho [Content-Type] da requisição;
  • linha 19: o método [post] retorna os parâmetros do corpo da requisição em um array associativo; [post('name')] retornaria um único parâmetro. Os campos de formulário seguem as regras do exemplo 10: um campo repetido deve ter um nome terminado em [[]];
  • linhas 26–27: [isJson()] verifica o tipo declarado pelo cabeçalho [Content-Type]. Um corpo que não é declarado como JSON é rejeitado com um erro 415 (*Unsupported Media Type*);
  • linhas 30–34: [getContent()] retorna o corpo bruto da requisição, uma string; a função [json_decode] do [PHP] a desserializa: o texto JSON se torna um valor [PHP] (o segundo parâmetro, [true], exige arrays associativos para os objetos JSON). Com a opção [JSON_THROW_ON_ERROR] (um parâmetro nomeado), um texto malformado gera uma exceção [JsonException], que o [try] / [catch] intercepta para retornar um erro 400. O método [json()] da requisição faria a mesma coisa, mas, para um JSON malformado, simplesmente retornaria um resultado vazio;
  • Linha 36: o método [input] procura um parâmetro em todos os lugares: no corpo da requisição — seja um formulário ou JSON — e, depois, na URL. Esse é o método mais usado, porque não depende do formato da requisição;
  • linha 42: um campo de formulário, lido por [input];
  • linhas 49–56: as regras da classe [PersonRequest] do exemplo 08, aplicadas desta vez aos campos do formulário. O código é o mesmo dos parâmetros da URL: apenas a origem dos dados muda. [sort] ordena as mensagens para garantir uma resposta consistente. O operador ternário [condition ? a : b] retorna [a] se a condição for verdadeira e [b] caso contrário.

A tabela de roteamento declara rotas POST, e o [bootstrap/app.php] desativa a proteção CSRF para essas URLs, como mostrado no exemplo 02:

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

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

Route::prefix('post')->controller(PostController::class)->group(function () {
    Route::post('action01', 'action01');
    Route::post('action02', 'action02');
    Route::post('action03', 'action03');
    Route::post('action04', 'action04');
});
<?php
// bootstrap/app.php: a aplicação do exemplo 11

use App\Http\Middleware\ReadableJson;
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Middleware;

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

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(web: __DIR__.'/../routes/web.php')
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->append(ReadableJson::class);
        // as requisições POST enviadas pelo curl não passariam pela proteção
        // anti-CSRF (exemplo 21)
        $middleware->preventRequestForgery(except: ['post/*']);
    })
    ->withExceptions()
    ->create();

Com o [curl], a opção [-d] (*data*) envia um corpo; a requisição passa então a ser uma requisição POST, do tipo [application/x-www-form-urlencoded], a menos que a opção [-H] (*header*) especifique um tipo diferente. A opção [-X POST] define explicitamente o método (aqui, ela é opcional). Os campos de um formulário, incluindo um campo repetido:

curl -i -g -X POST -d "name=martin&age=42&hobby[]=tennis&hobby[]=piano" http://localhost:8000/post/action01
HTTP/1.1 200 OK
Content-Type: application/json

{
    "receivedType": "application/x-www-form-urlencoded",
    "fields": {
        "name": "martin",
        "age": "42",
        "hobby": [
            "tennis",
            "piano"
        ]
    }
}

Um corpo JSON, que contém um inteiro e um array:

curl -i -H "Content-Type: application/json" -d "{\"name\": \"martin\", \"age\": 42, \"children\": [\"léa\", \"tom\"]}" http://localhost:8000/post/action02
HTTP/1.1 200 OK
Content-Type: application/json

{
    "receivedType": "application/json",
    "body": {
        "name": "martin",
        "age": 42,
        "children": [
            "léa",
            "tom"
        ]
    },
    "name": "martin"
}

As aspas do JSON são precedidas por [\] para evitar que a string do comando termine; no caso do [Linux] e do [macOS], também é possível delimitar o JSON com apóstrofos: [-d '{"name": "martin"}']. Ao contrário dos campos de formulário, o JSON carrega tipos de dados: a idade já é um inteiro. Um corpo que não é JSON, seguido de um JSON malformado (solicitando uma resposta JSON para ver a mensagem):

curl -i -H "Accept: application/json" -d "name=martin" http://localhost:8000/post/action02
curl -i -H "Accept: application/json" -H "Content-Type: application/json" -d "{\"name\": " http://localhost:8000/post/action02
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json

{
    "message": "the body of the request must be JSON",
    ...
}
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "Malformed JSON: Syntax error",
    ...
}

Um único campo e, depois, a mesma URL solicitada como GET:

curl -d "name=jean%20dupont" http://localhost:8000/post/action03
curl -i "http://localhost:8000/post/action03?name=martin"
1
2
3
4
5
name = [jean dupont]
HTTP/1.1 405 Method Not Allowed
allow: POST
Content-Type: text/html; charset=utf-8
...

A URL existe, mas não para o método GET: o [Laravel] retorna um 405 (*Method Not Allowed*), e seu cabeçalho [allow] lista os métodos aceitos. Por fim, as regras aplicadas aos campos do formulário, que primeiro foram satisfeitas e depois não:

curl -d "name=martin&age=42&title=Mr" http://localhost:8000/post/action04
curl -d "name=m&age=200" http://localhost:8000/post/action04
{
    "person": {
        "name": "martin",
        "age": "42",
        "title": "Mr"
    },
    "valid": true,
    "errors": []
}
{
    "person": null,
    "valid": false,
    "errors": [
        "age: the value must be between 0 and 150",
        "name: 2 character(s) at least",
        "title: the field is required"
    ]
}

3.6. Exemplo 12: Binding e validação personalizados

Os tipos e as regras padrão nem sempre são suficientes. Este exemplo mostra três maneiras de estender o binding e a validação:

  • um tipo vinculado a um parâmetro de rota: uma data em formato francês, [23-09-2026], no caminho da URL;
  • um middleware que fornece à action um parâmetro que não vem da URL, mas de um cabeçalho HTTP;
  • uma regra de validação personalizada (sem espaços) e a conversão de uma data [dd/mm/yyyy].
12-custom-binding/
├── app/
│   ├── Http/
│   │   ├── Controllers/
│   │   │   └── ExamplesController.php
│   │   └── Requests/
│   │       └── SearchRequest.php
│   └── Binding/
│       ├── DetectLanguage.php
│       ├── DayFr.php
│       └── NoSpace.php
├── lang/
│   └── en/
│       └── validation.php
└── ...

3.6.1. Um tipo vinculado a um parâmetro de rota: app/Binding/DayFr.php

Vimos no exemplo 02 que um parâmetro de rota é passado à action como string, ou como inteiro se o parâmetro da action for do tipo [int]. O [Laravel] também pode converter um parâmetro de rota em um objeto se a action exigir um parâmetro cuja classe implemente a interface [UrlRoutable]. Esse é o binding de rota (*route model binding*), que o [Laravel] usa principalmente para entidades de banco de dados (um identificador na URL se torna o objeto correspondente; veja o capítulo 9). Aqui, nós o usamos para uma data.

<?php
// app/Binding/DayFr.php: uma data francesa "23-09-2026" no caminho da URL

namespace App\Binding;

use Carbon\CarbonImmutable;
use Illuminate\Contracts\Routing\UrlRoutable;

// um tipo que sabe se VINCULAR a um parâmetro de rota (resolveRouteBinding) e
// voltar a ser um pedaço de URL (getRouteKey): a interface UrlRoutable
class DayFr implements UrlRoutable
{
    public function __construct(public ?CarbonImmutable $date = null)
    {
    }

    // texto do caminho -> objeto DayFr; null: o valor não é adequado (erro 404)
    public function resolveRouteBinding($value, $field = null): ?static
    {
        // o ! de "!d-m-Y" zera a hora (caso contrário, seria a hora atual)
        $date = CarbonImmutable::createFromFormat('!d-m-Y', $value);
        // createFromFormat aceita "31-02-2026" (e o transforma em 3 de março):
        // verificamos que a data, formatada novamente, devolve o texto recebido
        if ($date === null || $date->format('d-m-Y') !== $value) {
            return null;
        }
        return new static($date);
    }

    // objeto DayFr -> texto do caminho (usado pela função route)
    public function getRouteKey(): string
    {
        return $this->date->format('d-m-Y');
    }

    public function getRouteKeyName(): string
    {
        return 'day';
    }

    public function resolveChildRouteBinding($childType, $value, $field): ?static
    {
        return null;
    }
}
  • linha 11: a classe implementa a interface [UrlRoutable], cujos quatro métodos são os seguintes;
  • linha 13: a data, um objeto [CarbonImmutable]. [Carbon] é a biblioteca de datas do [Laravel]; ela estende a classe [DateTime] do [PHP] com centenas de métodos. A versão [Immutable] cria um novo objeto a cada modificação ([$date->addDay()] retorna uma nova data), em vez de modificar o objeto existente. O construtor tem um valor padrão, [null]: o [Laravel] precisa poder criar um objeto [DayFr] vazio, cujo método [resolveRouteBinding] ele chamará em seguida;
  • linhas 18–27: [resolveRouteBinding] converte o texto do caminho em um objeto: retorna o objeto vinculado ou [null] se o valor for inválido. [CarbonImmutable::createFromFormat] analisa uma string de acordo com um formato: [d] para o dia, [m] para o mês e [Y] para o ano com quatro dígitos; o [!] inicial zera a hora. [createFromFormat] é tolerante: aceita [31-02-2026] e o interpreta como 3 de março. A validação da linha 24 rejeita esse caso: a data, depois de reformatada, deve corresponder exatamente ao texto recebido. [new static(...)] cria um objeto da classe atual. Quando o método retorna [null], o [Laravel] responde com um erro 404: a URL não se refere a nada;
  • linhas 31–34: a operação inversa, usada pela função [route] para construir uma URL a partir de um objeto [DayFr]. [format] formata uma data;
  • linhas 36–41: os dois últimos métodos da interface, usados para entidades de banco de dados, não têm função aqui.

3.6.2. Um parâmetro fornecido por um middleware: app/Binding/DetectLanguage.php

Uma action do [Laravel] recebe como parâmetros os parâmetros da rota e os objetos que o container pode fornecer (a requisição, os serviços). Para fornecer a ela uma informação adicional, calculada a partir da requisição, podemos fazer com que seja calculada por um middleware (exemplo 03), que a inclui na requisição antes da action:

<?php
// app/Binding/DetectLanguage.php: um middleware que CALCULA uma informação para a action

namespace App\Binding;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class DetectLanguage
{
    public function handle(Request $request, Closure $next): Response
    {
        // o cabeçalho "Accept-Language: fr-FR,fr;q=0.9,en;q=0.8" -> "fr": o idioma
        // preferido do navegador entre os oferecidos (o primeiro por padrão)
        $language = $request->getPreferredLanguage(['fr', 'en']);
        // os ATRIBUTOS da requisição: informações que a aplicação armazena ali
        // para as funções que tratarão a requisição depois dele
        $request->attributes->set('language', $language);
        return $next($request);
    }
}
  • linha 16: o cabeçalho de requisição [Accept-Language] especifica os idiomas do usuário, em ordem de preferência: [fr-FR,fr;q=0.9,en;q=0.8] (o coeficiente [q] mede a preferência, em uma escala de 0 a 1). [getPreferredLanguage] seleciona, entre os idiomas oferecidos pela aplicação, aquele que o usuário prefere; se nenhum cabeçalho for fornecido, é o primeiro da lista;
  • linha 19: a requisição tem atributos, um array de informações que a aplicação armazena ali para as funções que processarão a requisição em seguida. O idioma é armazenado ali sob o nome [language];
  • linha 20: a requisição segue para a action.

A action receberá essa informação por meio de um atributo [PHP] colocado antes de seu parâmetro (veja o controller).

3.6.3. Uma regra “personalizada” e uma conversão: NoSpace.php e SearchRequest.php

<?php
// app/Binding/NoSpace.php: uma regra de validação "caseira"

namespace App\Binding;

use Closure;
use Illuminate\Contracts\Validation\ValidationRule;

class NoSpace implements ValidationRule
{
    // o valor não é adequado: chamamos $fail com a mensagem de erro
    public function validate(string $attribute, mixed $value, Closure $fail): void
    {
        if (str_contains((string) $value, ' ')) {
            $fail('the field must not contain a space');
        }
    }
}
  • linha 9: uma regra de validação “personalizada” é uma classe que implementa a interface [ValidationRule];
  • linhas 12–17: seu método [validate] recebe o nome do campo, seu valor e uma função, [$fail], que ele chama com a mensagem de erro se o valor for inválido. [str_contains] verifica a presença de um texto em uma string; [(string)] converte o valor em string. O tipo [mixed] designa qualquer tipo.

A regra é usada pela requisição do formulário de busca:

<?php
// app/Http/Requests/SearchRequest.php: o modelo da busca

namespace App\Http\Requests;

use App\Binding\NoSpace;
use Carbon\CarbonImmutable;
use Illuminate\Contracts\Validation\Validator;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Http\Exceptions\HttpResponseException;

class SearchRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            // uma regra "caseira": um objeto, em uma lista de regras
            'keyword' => ['nullable', new NoSpace()],
            // date_format: uma data no formato dd/mm/yyyy
            'since' => 'nullable|date_format:d/m/Y',
        ];
    }

    // a data, CONVERTIDA em um objeto de data (null se estiver ausente)
    public function since(): ?CarbonImmutable
    {
        return $this->date('since', 'd/m/Y')?->toImmutable();
    }

    // a resposta a uma validação que falhou, somente para ESTA classe: a mensagem
    // do primeiro erro, como texto simples, com o código 400
    protected function failedValidation(Validator $validator): never
    {
        throw new HttpResponseException(response($validator->errors()->first(), 400,
            ['Content-Type' => 'text/plain; charset=utf-8']));
    }
}
  • linha 18: as regras de um campo podem ser especificadas em um array em vez de uma string; isso é essencial para uma regra “personalizada”, que é um objeto;
  • linha 20: a regra [date_format:d/m/Y] verifica se o valor é uma data no formato especificado e se essa data existe;
  • linhas 25–28: conversão de data: o método [date] de uma requisição lê um parâmetro e o converte em uma data ([Carbon]) de acordo com o formato especificado; retorna [null] se o parâmetro estiver ausente. O operador [?->] chama um método se o objeto não for [null]e retorna [null] caso contrário; [toImmutable] converte a data em [CarbonImmutable];
  • linhas 32–36: o método [failedValidation], herdado de [FormRequest], é chamado quando a validação falha; o método de [FormRequest] lança a exceção [ValidationException] (exemplo 08). Nós a redefinimos apenas para esta classe: ela lança uma [HttpResponseException], uma exceção que carrega uma resposta predefinida, que o [Laravel] envia tal como está. A resposta contém a primeira mensagem de erro ([first()]), em texto simples, com o código de status 400. Essa é uma forma de tratar os erros de validação de uma action de maneira diferente dos do restante da aplicação.

A mensagem da regra [date_format] é personalizada pelo arquivo [lang/en/validation.php]:

1
2
3
4
5
6
<?php
// lang/en/validation.php: as mensagens dos erros de validação, em inglês
return [
    // :input: o valor recebido
    'date_format' => '[:input] is not a valid dd/mm/yyyy date',
];
  • linha 5: a tag [:input] é substituída pelo valor recebido.

3.6.4. O controller: app/Http/Controllers/ExamplesController.php

<?php
// app/Http/Controllers/ExamplesController.php: binding e validação personalizados

namespace App\Http\Controllers;

use App\Http\Requests\SearchRequest;
use App\Binding\DayFr;
use Illuminate\Container\Attributes\RequestAttribute;

class ExamplesController
{
    // /examples/schedule/23-09-2026: o parâmetro de rota {day} é VINCULADO a um objeto
    // DayFr, porque a action pede um parâmetro desse tipo
    public function schedule(DayFr $day): string
    {
        // route() usa o método getRouteKey de DayFr: objeto -> "23-09-2026"
        return "schedule for the day [{$day->date->toDateString()}], of type "
            .get_debug_type($day->date).', URL: '.route('schedule', $day, false);
    }

    // /examples/hello: um parâmetro que não vem da URL, mas de um cabeçalho,
    // calculado pelo middleware DetectLanguage e armazenado nos atributos da requisição
    public function hello(#[RequestAttribute('language')] string $language): string
    {
        return $language === 'en' ? 'Hello!' : 'Bonjour !';
    }

    // /examples/search?keyword=laravel&since=01/09/2026
    public function search(SearchRequest $request): string
    {
        $keyword = $request->validated('keyword');
        $since = $request->since()?->toDateString();
        return "search for [$keyword] since [$since]";
    }
}
  • linhas 14–18: o parâmetro [$day] é do tipo [DayFr]: o [Laravel] vincula o parâmetro de rota [{day}] a um objeto [DayFr] por meio de seu método [resolveRouteBinding]. [toDateString()] escreve a data no formato internacional ([2026-09-23]). A função [route] constrói a URL desta mesma action a partir do objeto, por meio de seu método [getRouteKey]; seu terceiro parâmetro, [false], solicita uma URL relativa (sem o protocolo nem a máquina);
  • linhas 23–25: o parâmetro [$language] é precedido por um atributo [PHP], escrito como [#[...]]: uma informação anexada ao código, que o [PHP] ignora, mas que as bibliotecas leem (o equivalente das anotações do [Java]). O atributo [RequestAttribute('language')] instrui o container a fornecer, para esse parâmetro, o atributo [language] da requisição, calculado pelo middleware [DetectLanguage];
  • linhas 29–33: a action recebe a requisição de formulário, que já foi validada (exemplo 08). [validated('keyword')] retorna um único campo validado; [since()] retorna a data convertida.

A tabela de roteamento:

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

use App\Http\Controllers\ExamplesController;
use App\Binding\DetectLanguage;
use Illuminate\Support\Facades\Route;

Route::prefix('examples')->controller(ExamplesController::class)->group(function () {
    // where: apenas um pedaço de caminho da forma dd-mm-yyyy é oferecido ao DayFr
    Route::get('schedule/{day}', 'schedule')->name('schedule')
        ->where('day', '[0-9]{2}-[0-9]{2}-[0-9]{4}');
    // middleware: DetectLanguage é executado antes da action
    Route::get('hello', 'hello')->middleware(DetectLanguage::class);
    Route::get('search', 'search');
});
  • linhas 10–11: a rota do calendário recebe um nome (para a função [route]), e seu parâmetro é restringido por uma expressão regular: [[0-9]] designa um único dígito, [{2}] designa a repetição do padrão anterior: dois dígitos, um hífen, dois dígitos, um hífen, quatro dígitos. Um segmento de caminho com outro formato não corresponde à rota (404), sem sequer consultar [DayFr];
  • linha 13: o método [middleware] associa um middleware a uma rota: ele é executado somente para essa rota, antes da action. Veremos esse mecanismo ao longo do curso: os middlewares que exigem um usuário autenticado, no capítulo sobre autenticação, são associados às rotas da mesma maneira.

3.6.5. Execução

O tipo associado ao parâmetro de rota:

curl "http://localhost:8000/examples/schedule/23-09-2026"
curl -i "http://localhost:8000/examples/schedule/31-02-2026"
1
2
3
4
schedule for the day [2026-09-23], of type Carbon\CarbonImmutable, URL: /examples/schedule/23-09-2026
HTTP/1.1 404 Not Found
Content-Type: text/html; charset=utf-8
...

A data é exibida no formato internacional, mas a URL construída por [route] voltou ao formato francês. 31 de fevereiro não existe: 404. Uma data no formato internacional, [2026-09-23], não corresponde ao padrão descrito pela expressão regular: também 404.

O middleware. A opção [-H] do [curl] define o cabeçalho [Accept-Language]:

1
2
3
curl -H "Accept-Language: en-US,en;q=0.9,fr;q=0.8" http://localhost:8000/examples/hello
curl -H "Accept-Language: fr-FR,fr;q=0.9" http://localhost:8000/examples/hello
curl http://localhost:8000/examples/hello
1
2
3
Hello!
Bonjour !
Bonjour !

Sem o cabeçalho [Accept-Language] (o [curl] não envia nenhum), usa-se o primeiro idioma da lista. O capítulo sobre internacionalização retomará essa questão, com o usuário selecionando o idioma.

A regra “da casa” e a conversão de data:

1
2
3
4
5
curl "http://localhost:8000/examples/search?keyword=laravel&since=01/09/2026"
curl "http://localhost:8000/examples/search"
curl -i "http://localhost:8000/examples/search?keyword=laravel%20mvc"
curl "http://localhost:8000/examples/search?since=2026-09-01"
curl "http://localhost:8000/examples/search?since=31/02/2026"
1
2
3
4
5
6
7
8
search for [laravel] since [2026-09-01]
search for [] since []
HTTP/1.1 400 Bad Request
Content-Type: text/plain; charset=utf-8

the field must not contain a space
[2026-09-01] is not a valid dd/mm/yyyy date
[31/02/2026] is not a valid dd/mm/yyyy date

3.6.6. Conclusão

Resumindo os meios de que uma action dispõe para obter seu modelo:

Parâmetros de rota
os parâmetros da action, que têm o mesmo nome; convertidos por seu tipo ([int $id]), restringidos por [whereNumber], [where]...; vinculados a um objeto por [UrlRoutable]
Parâmetros da URL
[$request->query(...)], [integer], [array], [date]...; um parâmetro repetido é escrito como [name[]]
Campos de um formulário POST
[$request->post(...)], ou [$request->input(...)], que busca em todos os lugares
Corpo JSON
[$request->input(...)], [$request->json()] ou [json_decode($request->getContent())]
Cabeçalhos
[$request->header(...)] e métodos que os analisam, como [getPreferredLanguage]
Validação
de regras: uma [FormRequest] (validação antes da action) ou [Validator::make] (validação pela action); regras “personalizadas” ([ValidationRule])
Mensagens
os arquivos [lang/xx/validation.php] e o arquivo de idioma [APP_LOCALE]
Erros comuns
[$exceptions->render(...)] em [bootstrap/app.php] (toda a aplicação), [failedValidation] (uma requisição de formulário)
Parâmetro calculado
Um middleware que armazena uma informação em os atributos da requisição, [#[RequestAttribute]]

Os formulários HTML, por outro lado, exigem mais do que apenas validação: eles precisam ser exibidos, reexibidos com os dados digitados pelo usuário e os eventuais erros, e protegidos contra requisições forjadas. Esse é o assunto do próximo capítulo, depois que as views forem apresentadas.