Requests e FormRequest · PHP MVC Framework

Framework\Http\Request

Fornece método e URI, leitura de query/form/JSON, cabeçalhos, IP, user-agent e acesso a arquivos. Métodos de conveniência incluem method(), uri(), get(), post(), all(), raw(), input(), json(), file(), hasFile() e header(). A implementação também reconhece override de método via campo _method.

FormRequest

App\Http\Requests\FormRequest é classe da aplicação de exemplo, não do namespace Framework. Subclasses implementam authorize(): bool e rules(): array; podem sobrescrever messages() e sanitize(). O construtor captura entrada, autoriza, sanitiza e valida imediatamente.

namespace App\Http\Requests\Auth;

use App\Http\Requests\FormRequest;

class LoginRequest extends FormRequest
{
    public function authorize(): bool { return true; }

    public function rules(): array
    {
        return ['email' => 'required|email', 'password' => 'required'];
    }

    public function messages(): array
    {
        return [
            'email.required' => 'Informe seu e-mail.',
            'email.email' => 'O e-mail informado não é válido.',
            'password.required' => 'Informe sua senha.',
        ];
    }

    public function sanitize(): array
    {
        return [
            'email' => strtolower(trim($this->input['email'] ?? '')),
            'password' => trim($this->input['password'] ?? ''),
        ];
    }
}

JSON e arquivos

O FormRequest captura body JSON quando CONTENT_TYPE inclui application/json; caso contrário combina $_POST com nomes em $_FILES. Para validação de conteúdo/tamanho real do arquivo, use Validator com os dados de arquivos ou Upload; o FormRequest base só adiciona o nome enviado aos dados capturados.

Parâmetros de rota

Subclasses podem declarar placeholder de regra como unique:posts,slug,{id}. O Router fornece os parâmetros nomeados; placeholders sem resolução geram RuntimeException intencionalmente.

API pública

fails(), passes(), errors(), firstError(?string $field = null), validated(), get($field,$default=null), old($field,$default=''), all(). Consulte também Validação.

Request ou FormRequest?

Necessidade	Use	O que recebe
Ler query/form/header/status do request atual	Framework\Http\Request	Valores brutos ou sanitizados conforme o método
Declarar regra e autorização reutilizável	App\Http\Requests\FormRequest	Subclasse que resolve ao ser instanciada e oferece validated()
Validar upload real	Framework\Support\Validator + $_FILES ou Upload	O array real de arquivo; FormRequest base só incorpora nomes à entrada

Request::get() lê query string; post()/all() leem POST; input() procura POST e depois GET. Esses getters sanitizam texto. `raw()` preserva o valor original e é necessário para campos como senha quando a aplicação lê diretamente o Request. `json()` decodifica php://input; corpo inválido vira array vazio, não erro automático.

Método	Retorno / uso	Observação
method(), uri()	Verbo efetivo e caminho sem query string	method() também reconhece POST + _method PUT/PATCH/DELETE.
get($key,$default), post($key,$default)	mixed sanitizado	Não substituem validação de domínio.
all()	array de $_POST sanitizado	Não mescla query string.
input($key,$default), has($key)	Consulta POST/GET	input prioriza POST; has verifica presença.
raw($key,$default)	mixed sem sanitização	Restrinja o uso a credenciais/tokens que precisam dos bytes exatos.
json($key = null,$default = null)	array ou valor	Apenas lê/decode; valide antes de confiar.
file($key), hasFile($key)	array\|null e bool	Estrutura vem de $_FILES; processar exige upload válido.
header($name,$default), ip(), userAgent()	string	IP respeita TRUSTED_PROXIES; cabeçalhos encaminhados não são confiáveis por padrão.

Exemplo progressivo · o LoginRequest real

Cenário: o login web e o login da API precisam validar os mesmos campos, mas o e-mail deve ser normalizado e a senha deve conservar caracteres especiais. A aplicação centraliza esse contrato em App\Http\Requests\Auth\LoginRequest.

namespace App\Http\Requests\Auth;

use App\Http\Requests\FormRequest;

class LoginRequest extends FormRequest
{
    public function authorize(): bool { return true; }

    public function rules(): array
    {
        return ['email' => 'required|email', 'password' => 'required'];
    }

    public function sanitize(): array
    {
        return [
            'email' => strtolower(trim($this->input['email'] ?? '')),
            'password' => trim($this->input['password'] ?? ''),
        ];
    }
}

Ao construir o objeto, FormRequest captura entrada, chama authorize(), sanitize(), rules() e messages(). `validated()` contém somente as chaves declaradas em rules; não use `all()` para gravar, pois ele é sanitizado, porém pode conter chaves não validadas. `old()`/`all()` são voltados à repopulação de formulário.

Parâmetros de rota e arquivos

Quando uma action recebe uma subclasse FormRequest tipada, o Router injeta os parâmetros nomeados da URL no construtor. Isso permite regras como `unique:users,email,{id}` em uma rota com `{id}`; placeholder sem correspondente gera RuntimeException para sinalizar erro de configuração.

Arquivos são outra entrada. FormRequest coleta apenas o nome do upload em seus dados; para regras `file`, `image` e `mimes`, use Validator passando também `$_FILES`, ou use Upload para validar e mover o arquivo. Consulte Validação e Uploads.

Ciclo, dados disponíveis e limites

FormRequest::__construct(array $routeParams = []) captura e resolve a requisição imediatamente: captura entrada, chama authorize(), sanitize(), rules() e messages(). Se authorize() retorna false, responde HTTP 403 (JSON para Accept/Content-Type JSON, caso contrário flash + redirect) e encerra com exit; não é um retorno false que o Controller possa ignorar.

Para uma regra dependente do ID da URL, o Router repassa os parâmetros nomeados ao construir um argumento de action tipado como subclasse FormRequest. Os placeholders em rules() usam a mesma grafia da rota. Placeholder que não puder ser substituído lança RuntimeException, sinalizando configuração incompatível.

// Exemplo estrutural: rota e regra precisam compartilhar o nome {id}.
$router->put('/users/{id}', [UserController::class, 'update']);

final class UpdateUserRequest extends FormRequest
{
    public function authorize(): bool { return auth(); }

    public function rules(): array
    {
        return ['email' => 'required|email|unique:users,email,{id}'];
    }
}

Esse padrão ilustra somente as APIs presentes em Router/FormRequest; uma request concreta precisa corresponder às regras e à política de autorização do recurso. As requests de usuário existentes devem ser chamadas pela action correspondente, com a rota que fornece {id}.

Campos e arquivos

Corpo application/json: decodificado como array; se inválido, a captura resulta em array vazio.
Formulário: começa por $_POST; para cada $_FILES, FormRequest acrescenta apenas o nome original do arquivo quando a chave ainda não existe.
validated() contém somente as chaves declaradas em rules(); all() devolve todos os dados sanitizados, que não necessariamente passaram pelas regras.
O Validator usado internamente pelo FormRequest recebe apenas dados; para regras de arquivo é preciso fornecer arquivos ao Validator diretamente ou usar Upload.

Em Controllers Web, validateRequest($request, $redirectBack, $flashOnly) é o adaptador real para erro + flash + redirect. Para API, o helper ApiController::validated() responde 422 quando inválido; veja Respostas e regras do Validator.

Formato JSON esperado e FormRequest

Para endpoints JSON, envie um objeto JSON com Content-Type: application/json e valide sua forma antes de tratá-lo como mapa de campos. Bodies JSON escalares (por exemplo, true, 42 ou null) não são um contrato seguro para FormRequest, que processa campos como estrutura associativa; use objeto/campos ou leia com Request::json() e trate explicitamente o tipo. O leitor JSON retorna o default (por padrão, array vazio) quando não há body decodificável como array e mantém o resultado decodificado em cache na instância.

Uploads e FormRequest

As regras declaradas em FormRequest são aplicadas aos dados que ele coleta; não presuma que os arquivos de $_FILES são automaticamente incluídos. Para upload, passe $_FILES ao Validator::make($data, $rules, $_FILES) ou adapte explicitamente o FormRequest para executar setFiles($_FILES) antes de validar. Veja Uploads.

Requests concretas de usuários

StoreUserRequest e UpdateUserRequest são contratos distintos, mas a existência dessas classes não registra automaticamente rotas nem associa request/controller. Instancie e execute a request na action/Controller correspondente, confirme os campos liberados por validated() e registre a rota explicitamente. Não use o exemplo de store para update: os campos e as regras (inclusive ID de rota/unique) diferem.

Consumo de mensagens de validação

Mensagens/erros são estado da validação da requisição atual e o fluxo de redirecionamento usa flash/session para exibi-los depois. Leia os métodos da instância uma vez por ciclo e não dependa de um getter que consome a mensagem para montar várias partes da página; se precisar de duas saídas, copie o array antes de consumi-lo.