DEV Community: Denis Augusto

Deixei um bot derrubar minha API antes de descobrir o throttle

Denis Augusto — Thu, 16 Jul 2026 13:59:34 +0000

Segunda de manhã, servidor no chão, e eu sem entender nada

A cena: segunda-feira, 8h. Abro o monitoramento e o servidor está gritando. CPU no talo, banco engasgado, aplicação lenta pra todo mundo.

Meu primeiro palpite? "Bombou o projeto, viralizou!" 🎉

Aí olhei o log. Não era gente. Era um único IP batendo no meu endpoint de login. Milhares de requisições por minuto, tentando senha atrás de senha. Um bot fazendo força bruta enquanto eu dormia.

A pior parte: eu não tinha nada pra segurar isso. Meu endpoint aceitava requisição de quem quisesse, quantas vezes quisesse. A porta estava escancarada.

Já parou pra pensar quantas requisições um usuário consegue disparar na sua API agora, sem nenhum limite? Pois é.

O problema: sua API confia em todo mundo

Por padrão, uma rota Laravel não tem limite nenhum. Ela responde a qualquer um, o quanto vier:

Route::post('/login', [AuthController::class, 'login']);
// Pode receber 5 requisições por dia ou 50 mil por minuto.
// Pra ela tanto faz. 🤷

Isso é convite pra três dores de cabeça:

Força bruta no login, tentando senha até acertar.
Scraping dos seus dados, alguém raspando tudo de uma vez.
Custo: cada requisição gasta CPU, banco e, se você estiver na nuvem, dinheiro.

A solução tem nome e é embutida no Laravel: rate limiting. Ou seja, "você só pode fazer X requisições por minuto. Passou disso, toma um 429 e espera".

A versão de 3 linhas: middleware `throttle`

O jeito mais rápido de proteger uma rota é o middleware throttle. Você diz quantas requisições por quantos minutos:

Route::middleware('throttle:60,1')->group(function () {
    Route::apiResource('posts', PostController::class);
});
// 60 requisições por 1 minuto, por usuário/IP. Passou disso, 429.

Pronto. Se um IP passar de 60 requisições no minuto, o Laravel responde com 429 Too Many Requests sozinho, sem você escrever uma linha de lógica. O bot que estava me atormentando teria batido na parede.

E se você tem uma API, provavelmente já tem um limiter chamado api funcionando sem você saber, aplicado no grupo de rotas de routes/api.php. Vale conferir.

A versão profissional: named limiters

O throttle:60,1 resolve o básico. Mas e quando você quer regras diferentes por tipo de rota, ou por tipo de usuário? Aí entram os named limiters.

Você define a regra num lugar central (no boot() do seu AppServiceProvider) e dá um nome pra ela:

use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\RateLimiter;

public function boot(): void
{
    RateLimiter::for('api', function (Request $request) {
        // 60 por minuto, contados por usuário logado — ou por IP se for visitante
        return Limit::perMinute(60)->by($request->user()?->id ?: $request->ip());
    });
}

Repara no ->by(): é ele que decide quem conta pra cota. Usando o ID do usuário, cada pessoa tem sua própria cota; caindo pro IP quando é visitante. Sem isso, todo mundo dividiria o mesmo balde — um abusador estouraria o limite de todos os outros.

Depois é só apontar a rota pro limiter pelo nome:

Route::middleware('throttle:api')->group(function () {
    // suas rotas protegidas
});

Como usar na prática

Protegendo o login (o meu caso). Aqui o pulo do gato é contar por e-mail, não só por IP, pra travar força bruta mesmo que o bot troque de IP:

RateLimiter::for('login', function (Request $request) {
    return [
        Limit::perMinute(500),                          // teto geral da rota
        Limit::perMinute(5)->by($request->input('email')), // 5 tentativas por e-mail
    ];
});

Cinco tentativas erradas naquele e-mail e a conta fica trancada por um minuto. Bot de força bruta chora.

Limite diferente por plano. Cliente VIP não deveria ter a mesma cota do plano grátis. Dá pra decidir na hora:

RateLimiter::for('uploads', function (Request $request) {
    return $request->user()->vip
        ? Limit::none()          // VIP sem limite
        : Limit::perHour(10);    // grátis, 10 por hora
});

Mensagem de erro amigável. Em vez do 429 seco, você pode devolver uma resposta customizada:

RateLimiter::for('api', function (Request $request) {
    return Limit::perMinute(60)->response(function (Request $request, array $headers) {
        return response()->json(['message' => 'Calma lá! Tenta de novo em instantes.'], 429, $headers);
    });
});

Pegadinha: os headers que ninguém lê (mas deveria)

Toda resposta com rate limit vem com headers que contam a história: X-RateLimit-Limit (seu teto) e X-RateLimit-Remaining (quanto ainda sobra). Quando estoura, vem também o Retry-After, dizendo em quantos segundos pode tentar de novo.

Se você consome uma API de terceiros e vive tomando 429, é aí que você olha. E se você expõe uma API, esses headers são o que permite o cliente se comportar bem sozinho, sem ficar batendo na parede.

Outra pegadinha: rate limiting usa o cache pra contar. Em produção, garante que seu cache está num driver de verdade (Redis, de preferência), não no array, senão a contagem se perde a cada requisição.

Bônus: e agora?

Rate limiting é a porta de entrada de uma API saudável, mas não para por aí:

Combine com throttle no login e você já matou 90% dos ataques de força bruta.
Use limites diferentes pra rotas públicas (mais apertado) e autenticadas (mais folgado).
Se sua fila (queue) chama APIs externas, aplique rate limiting nos jobs também — o Laravel tem Redis::throttle() pra isso.

Não precisa fazer tudo de uma vez. Começa protegendo o login e as rotas mais sensíveis. O resto vem depois.

Antes de você fechar a aba

Eu aprendi na marra: API sem rate limiting é porta destrancada. Funciona lindamente até o dia que um bot resolve entrar.

O melhor de tudo? A proteção básica é literalmente uma linha de middleware. Não tem desculpa pra deixar a porta aberta.

E aí, suas rotas de login e API já têm rate limiting? Ou você também só vai descobrir isso quando o servidor cair numa segunda de manhã? Conta nos comentários. 🔒

Curtiu? Tem mais conteúdo sobre Laravel limpo e seguro por aqui. Me segue pra não perder os próximos.

Funciona na minha máquina: o mistério do env() que some em produção

Denis Augusto — Mon, 13 Jul 2026 17:00:41 +0000

"Mas aqui na minha máquina roda perfeitamente"

Você terminou a feature. Testou local, passou. Subiu pra produção.

E aí, do nada, algo que dependia de uma variável de ambiente simplesmente… parou de funcionar. Sua integração com o gateway de pagamento agora usa uma chave vazia. O client de uma API externa aponta pra lugar nenhum.

Você abre o log, confere o .env, a variável tá lá, certinha. Roda local de novo: funciona. Em produção: null. 🙃

Se você já viveu essa cena de terror, provavelmente o culpado é um só: você usou env() num lugar que não devia.

O código que parece inofensivo

Digamos que você criou um service pra falar com uma API de frete. Precisa da chave, então você faz o óbvio:

class FreteService
{
    public function __construct()
    {
        // parece certo, né? peguei do .env e pronto
        $this->apiKey = env('FRETE_API_KEY');
        $this->baseUrl = env('FRETE_API_URL', 'https://api.frete.com');
    }
}

Local, isso funciona lindamente. O Laravel lê o .env, encontra FRETE_API_KEY, e a vida segue.

O problema é que esse código carrega uma bomba-relógio. E o pino é puxado por um comando que todo deploy sério roda.

O que o config:cache faz (e por que ele te trai)

Ler o arquivo .env do disco e parsear tudo a cada request é lento. Por isso, em produção, a recomendação oficial é rodar:

php artisan config:cache

Esse comando junta todos os seus arquivos de config/ num único arquivo PHP otimizado e cacheado. A partir daí, o Laravel nunca mais lê o .env — ele lê o cache.

E aqui tá a pegadinha: quando o config está cacheado, a função env() passa a retornar null pra tudo que não estava dentro dos arquivos de config.

Ou seja, aquele env('FRETE_API_KEY') lá no seu service vira null em produção. Local você provavelmente nunca rodou config:cache, por isso "funciona na sua máquina". O bug estava dormindo o tempo todo.

A regra de ouro

env() só deve ser chamado dentro dos arquivos da pasta config/. Nunca em services, controllers, models, jobs ou qualquer outro lugar.

O jeito certo é: você lê o env() no config, e no resto da aplicação você lê o config com config().

Primeiro, cria (ou usa) um arquivo de config:

// config/frete.php
return [
    'api_key'  => env('FRETE_API_KEY'),
    'base_url' => env('FRETE_API_URL', 'https://api.frete.com'),
];

Depois, no service, você troca env() por config():

class FreteService
{
    public function __construct()
    {
        // agora lê do config — que sobrevive ao cache
        $this->apiKey  = config('frete.api_key');
        $this->baseUrl = config('frete.base_url');
    }
}

Pronto. Agora o env() mora onde deve, o config:cache empacota o valor junto, e produção passa a se comportar igual ao seu local.

Como usar na prática

O padrão é sempre o mesmo, em qualquer contexto:

Chave de API num service → cria uma entrada em config/services.php e lê com config('services.frete.key'). Aliás, o config/services.php já existe justamente pra isso.
Feature flag num controller → config('app.features.novo_checkout') em vez de env('NOVO_CHECKOUT').
Timeout de um job → coloca em config/queue.php ou num config seu e chama config('...') lá dentro.

Regra mental simples: se você tá prestes a escrever env() e o arquivo não está dentro de config/, para. Tá quase virando bug de produção.

A pegadinha da pegadinha

"Mas eu uso env() fora do config e funciona!" — sim, funciona enquanto você não rodar config:cache.

O perigo é justamente esse: em desenvolvimento tudo passa, os testes passam, o PR é aprovado. O bug só nasce no primeiro deploy que roda o cache. E aí você vai debugar em produção, no pior momento possível.

Quer testar se seu código tá limpo agora? Roda isso local:

php artisan config:cache

Se algo quebrar depois disso, achou seus env() mal colocados. Pra voltar ao normal no dev:

php artisan config:clear

Bônus: e agora?

Passa um grep no seu projeto atrás de env( fora da pasta config/. Aposto que tem pelo menos um escondido por aí — geralmente num service antigo que "sempre funcionou".

Enquanto tá nisso, dá uma olhada no config/services.php. Ele foi feito pra guardar credenciais de serviços de terceiros, e muita gente ignora que ele existe.

Antes de você fechar a aba

O env() fora do config é aquele bug educado: ele espera você virar as costas pra produção pra dar as caras.

Já perdeu uma tarde caçando um valor que sumia em produção? Conta aí nos comentários qual foi o seu — quero saber se fui só eu. 👀

Se esse tipo de armadilha de Laravel te ajuda, salva o post e me segue: tem mais dessas por aqui.

API Resources no Laravel: pare de dar return no seu Model cru

Denis Augusto — Wed, 08 Jul 2026 15:10:59 +0000

Sua API tá contando segredo pro mundo inteiro

Você monta o endpoint, testa no Insomnia, o JSON volta bonitinho e você segue a vida. Deploy feito, tá funcionando.

Só que naquele JSON, junto com o name e o email que você queria mostrar, foi também o password (mesmo que hasheado), o remember_token, o stripe_id do cliente e aquele campo internal_notes que só o time devia ver.

Ninguém reparou. Até alguém reparar. 😬

Esse é o preço de retornar o Model direto. E a solução no Laravel tem nome: API Resources.

O código que todo mundo já escreveu

Olha esse controller. Aposto que você já fez algo parecido:

public function show(User $user)
{
    return response()->json($user);
}

// ou a versão "prática":
public function index()
{
    return User::all();
}

Funciona. Retorna o usuário. Mas quando você faz return $user, o Laravel chama toArray() no Model e despeja todas as colunas que vieram do banco no JSON.

Toda coluna. A que você quer e a que você esqueceu que existia. Se amanhã alguém adicionar um campo documento ou salario na tabela, ele vai vazar de graça na sua API sem ninguém pedir.

Você não tem controle nenhum sobre o formato da resposta. E API é contrato — sair jogando o banco cru é o oposto de contrato.

O `$hidden` ajuda, mas não resolve

"Ah, mas eu uso $hidden no Model." Ótimo, é melhor que nada:

protected $hidden = ['password', 'remember_token'];

O problema é que $hidden é uma blacklist. Você precisa lembrar de esconder cada campo sensível novo. Esqueceu um? Vazou.

E tem outro detalhe: o mesmo Model serve pra vários lugares. Às vezes você quer o email na resposta, às vezes não. O $hidden é global demais pra essa decisão, que na real é por endpoint.

A solução: uma camada só pra montar a resposta

API Resource é uma classe que fica entre o seu Model e o JSON. Ela decide, campo a campo, o que vira resposta. É uma whitelist: só sai o que você escreveu ali.

Cria com um comando:

php artisan make:resource UserResource

E define o formato no toArray():

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id'         => $this->id,
            'nome'       => $this->name,
            'email'      => $this->email,
            'criado_em'  => $this->created_at->format('d/m/Y'),
        ];
    }
}

Repara no que ganhou de brinde: se não tá na lista, não sai. password nunca vai vazar porque você simplesmente não escreveu ele ali. É seguro por padrão, não por você lembrar de esconder.

E de bônus você controla o formato: renomeou name pra nome, formatou a data. A resposta é sua, não um reflexo direto da tabela.

Como usar no controller

Aí no controller você embrulha o Model no Resource:

public function show(User $user)
{
    return new UserResource($user);
}

Pra uma lista, usa o collection():

public function index()
{
    return UserResource::collection(User::all());
}

Mesmo Resource, seja um registro ou mil. O Laravel cuida de aplicar a transformação em cada item da coleção.

Por padrão a resposta vem embrulhada numa chave data — o que é ótimo, porque te dá espaço pra meta dados (paginação, links) sem quebrar o contrato lá na frente.

O pulo do gato: campos condicionais

Aqui é onde Resource passa longe do $hidden. Às vezes um campo deve aparecer só pra certas pessoas. Tipo um dado que o admin vê e o usuário comum não.

public function toArray(Request $request): array
{
    return [
        'id'    => $this->id,
        'nome'  => $this->name,
        'email' => $this->email,

        // só entra no JSON se quem pediu for admin
        'notas_internas' => $this->when(
            $request->user()?->isAdmin(),
            $this->internal_notes
        ),
    ];
}

O when() só inclui a chave se a condição for verdadeira. Pro usuário comum, o campo nem existe na resposta — não vem como null, não vem vazio, simplesmente não vem. Impossível vazar.

E pra relacionamentos, tem o whenLoaded(), que ainda te salva de N+1:

'posts' => PostResource::collection($this->whenLoaded('posts')),

O relacionamento só entra no JSON se você já tiver carregado ele com with('posts'). Não carregou? Não aparece — e o Laravel não dispara query extra tentando buscar. Segurança e performance no mesmo método.

A pegadinha que confunde muita gente

Dentro do Resource, você acessa os campos com $this->id, $this->name... e parece mágica, porque $this não é o Model, é o Resource.

O que rola é que o Resource encaminha o acesso pro Model que ele está embrulhando. Então $this->name na prática é $user->name. Funciona lindo.

O tropeço é achar que dá pra chamar qualquer método do Model direto no $this sem ele estar carregado, ou esquecer que numa coleção o $this representa cada item, um de cada vez — não a coleção inteira. Se você tentar tratar a coleção como um objeto só ali dentro, vai se enrolar.

Bônus: e agora?

Se você tem Service Layer, o controller fica magrinho: o service resolve a regra, o Resource formata a saída. Cada um no seu quadrado.

Vale também dar uma olhada em make:resource --collection (pra quando a coleção precisa de metadados próprios) e no método additional(), pra pendurar dados extras na resposta sem sujar o toArray().

Antes de você fechar a aba

Faz um teste rápido agora: pega o endpoint mais antigo do seu projeto, aquele que retorna o Model direto, e olha o JSON completo que ele devolve. Tem algum campo ali que não devia estar aparecendo?

Se tem, você acabou de achar seu próximo refactor. E se não tem, provavelmente é porque você teve sorte — não porque teve controle. 🙂

Você usa Resource em tudo ou só quando a resposta é complexa? Conta aí nos comentários como você organiza isso.

E se esse post te fez lembrar de um endpoint suspeito, compartilha com aquele colega que ainda dá return $model sem pensar duas vezes.

DB::transaction(): o try/catch que salva seu banco de dados

Denis Augusto — Tue, 07 Jul 2026 13:07:26 +0000

Salvou o pedido, mas não salvou os itens. E agora?

Imagina a cena: seu checkout cria o pedido, dá baixa no estoque e registra o pagamento. Três operações no banco, uma atrás da outra.

Aí no meio do caminho o banco cai. Ou uma validação estoura. Ou a API de pagamento dá timeout.

Resultado? O pedido foi criado, o estoque foi debitado, mas o pagamento nunca registrou. Você acabou de vender um produto de graça. 🎉

Esse é o pesadelo do dado inconsistente. E a solução tem nome: transaction.

O código que parece inofensivo (mas não é)

Olha esse controller bem comum:

public function store(Request $request)
{
    $pedido = Pedido::create($request->only('cliente_id', 'total'));

    foreach ($request->itens as $item) {
        $pedido->itens()->create($item);
        Produto::find($item['produto_id'])->decrement('estoque', $item['qtd']);
    }

    Pagamento::create([
        'pedido_id' => $pedido->id,
        'valor' => $pedido->total,
    ]);

    return response()->json($pedido);
}

Parece limpo, né? O problema é que cada linha grava no banco na hora.

Se der ruim na criação do pagamento, o pedido e os itens já estão salvos. Não tem volta. Seu banco fica com um Frankenstein: metade de uma operação que era pra ser uma coisa só.

O conceito por trás: atomicidade

Uma transaction resolve isso com uma ideia simples: tudo ou nada.

Ou todas as operações dão certo e são gravadas de vez (o commit), ou qualquer uma falha e o banco desfaz tudo como se nada tivesse acontecido (o rollback).

É o mesmo princípio de uma transferência bancária: não existe "saiu da minha conta mas não entrou na sua". Ou acontece por inteiro, ou não acontece.

A solução: DB::transaction()

O Laravel deixa isso ridiculamente fácil. Você embrulha o código num DB::transaction() e pronto:

use Illuminate\Support\Facades\DB;

public function store(Request $request)
{
    $pedido = DB::transaction(function () use ($request) {
        $pedido = Pedido::create($request->only('cliente_id', 'total'));

        foreach ($request->itens as $item) {
            $pedido->itens()->create($item);
            Produto::find($item['produto_id'])->decrement('estoque', $item['qtd']);
        }

        Pagamento::create([
            'pedido_id' => $pedido->id,
            'valor' => $pedido->total,
        ]);

        return $pedido;
    });

    return response()->json($pedido);
}

Só isso. Se qualquer linha dentro da closure lançar uma exception, o Laravel faz o rollback automático de tudo. Nada é gravado.

Se rodar até o fim sem erro, ele dá o commit. E de bônus: o que a closure retornar (return $pedido) vira o retorno do DB::transaction(). Prático demais.

Repara que não precisa de try/catch, nem de commit, nem de rollBack na mão. A closure faz o trabalho sujo pra você.

Como usar na prática

No checkout que a gente viu: garante que pedido, itens, estoque e pagamento vivem e morrem juntos. Nunca mais um pedido órfão.

Num cadastro com múltiplas tabelas: criar o usuário, o perfil e as configurações padrão. Se o perfil falhar, o usuário não fica solto no banco sem perfil.

Numa importação em lote: processar 500 linhas de uma planilha. Se a linha 480 tiver um erro, você não quer 479 registros pela metade. Ou entra tudo, ou você corrige a planilha e roda de novo.

A versão manual (pra quando você precisa de controle)

Às vezes a closure não dá conta — você precisa decidir quando fazer commit ou rollback com base em alguma lógica. Aí usa a forma manual:

DB::beginTransaction();

try {
    $pedido = Pedido::create($dados);
    // ... mais operações ...

    DB::commit();
} catch (\Throwable $e) {
    DB::rollBack();

    report($e); // loga o erro pra você investigar depois
    throw $e;   // relança pra não engolir o problema em silêncio
}

Funciona igual, só que você está no controle. Mas repara: se você usar essa versão, não engula a exception. Fazer o rollback e seguir a vida como se nada tivesse acontecido esconde o bug. Loga e relança.

Na dúvida, prefira o DB::transaction(). Menos código, menos chance de esquecer um rollBack.

A pegadinha que pega todo mundo

Transaction serve pra banco de dados. Só isso.

O erro clássico é enfiar coisas que não são banco dentro dela, achando que vão ser "desfeitas" também:

DB::transaction(function () use ($pedido) {
    Pedido::create($pedido);

    Mail::to($cliente)->send(new PedidoConfirmado); // ⚠️ perigo
    Storage::put('nota.pdf', $conteudo);            // ⚠️ perigo
});

Se a transaction der rollback depois disso, o pedido some do banco — mas o e-mail já foi enviado e o arquivo já foi salvo. Rollback não volta no tempo pro mundo real.

A regra de ouro: dentro da transaction, só banco. E-mail, envio de arquivo, chamada de API, disparo de job — deixa pra depois do commit.

O Laravel até te ajuda nisso com DB::afterCommit() (e jobs que implementam ShouldQueue já respeitam isso automaticamente se você configurar after_commit). Assim o e-mail só dispara quando o commit deu certo de verdade.

Bônus: e agora?

Se você trabalha com Service Layer, a transaction geralmente mora lá dentro do método do service — não no controller. O controller só orquestra, o service garante a consistência.

E vale abrir a doc pra dar uma olhada em retry (o segundo parâmetro do DB::transaction(), útil pra deadlocks) e em transactions aninhadas com savepoints. Assunto pra um próximo post. 😉

Antes de você fechar a aba

Se você tem algum fluxo que grava em várias tabelas seguidas e ainda não usa transaction, esse é o sinal pra revisar. É o tipo de bug que não aparece nos testes felizes e só dá as caras em produção, numa sexta à noite.

Você já tomou um susto com dado pela metade no banco? Conta aí nos comentários — aposto que tem história boa.

E se esse post te salvou de um checkout quebrado, compartilha com aquele colega que ainda faz três create() seguidos sem rede de proteção. 🙂

Soft Deletes no Laravel: apague sem apagar de verdade

Denis Augusto — Mon, 06 Jul 2026 21:50:00 +0000

"Some do banco" nem sempre é o que você quer

Imagina a cena: o cliente liga desesperado porque um funcionário apagou um pedido importante. Você abre o banco, e... não tem. Sumiu. DELETE é DELETE. Agora é backup ou choro.

Agora imagina a mesma cena, só que você digita $pedido->restore() e o registro volta como se nada tivesse acontecido. Herói do dia.

Essa é a proposta do Soft Delete: em vez de apagar a linha de verdade, o Laravel marca ela como apagada e finge que ela não existe mais nas consultas. Ela continua lá, só invisível. E dá pra trazer de volta quando quiser.

O problema: `delete()` é definitivo

Sem soft delete, isso aqui é irreversível:

$pedido->delete(); // tchau. pra sempre. 💀

Some do banco, some dos relatórios, some da vida. Se alguém apagou por engano, ou se você precisa de histórico pra auditoria, azar. E é impressionante como "apagou por engano" acontece com frequência em produção.

A solução: três passos e pronto

Primeiro, adiciona a coluna deleted_at na migration. O Laravel tem um helper só pra isso:

Schema::table('pedidos', function (Blueprint $table) {
    $table->softDeletes(); // cria a coluna deleted_at (nullable)
});

Depois, usa a trait SoftDeletes na model:

use Illuminate\Database\Eloquent\SoftDeletes;

class Pedido extends Model
{
    use SoftDeletes;
}

Pronto. Agora o delete() mudou de comportamento sem você tocar em mais nada:

$pedido->delete();
// não apaga a linha — só preenche deleted_at com a data/hora de agora

E o melhor: as consultas normais ignoram automaticamente os registros apagados. Pedido::all() não traz nada que foi soft-deletado. Você não precisa filtrar nada na mão.

Trazendo de volta e vendo os apagados

Restaurar é uma linha:

$pedido->restore(); // deleted_at volta pra null, registro "revive"

Pra incluir os apagados numa consulta, withTrashed:

Pedido::withTrashed()->get(); // traz tudo, apagados junto

Pra ver só os apagados (útil pra uma tela de "lixeira"):

Pedido::onlyTrashed()->get();

E se precisar apagar de verdade, aí sim, sem volta:

$pedido->forceDelete(); // agora foi pro além de verdade

Como usar na prática

Lixeira pro usuário. Uma tela onde ele apaga itens, mas tem 30 dias pra restaurar. onlyTrashed() lista, restore() recupera.

Auditoria e histórico. Setores como financeiro e jurídico costumam exigir que nada suma de verdade. Soft delete mantém o rastro sem poluir as telas do dia a dia.

Checar o estado no código. Dá pra saber se um registro tá apagado:

if ($pedido->trashed()) {
    // esse aqui tá na lixeira
}

Pegadinha 1: `unique` não sabe de soft delete

Essa pega muita gente. Você tem uma coluna email com índice unique. O usuário joao@email.com é soft-deletado. Ele tenta se cadastrar de novo... e o banco recusa, porque a linha antiga ainda está lá, ocupando o email.

O unique do banco não liga pro deleted_at — pra ele, a linha existe. Na validação, você precisa dizer isso explicitamente. Na Rule unique, ignore os apagados:

use Illuminate\Validation\Rule;

Rule::unique('usuarios', 'email')->whereNull('deleted_at');

Assim a validação só considera os registros ativos, e o email "liberado" pelo soft delete volta a funcionar.

Pegadinha 2: relacionamento com registro apagado

Outra que confunde. O pedido foi soft-deletado, mas você carrega ele por um relacionamento e o item some:

$cliente->pedidos; // não traz os pedidos apagados

Isso normalmente é o que você quer. Mas quando não for — tipo montar um histórico completo do cliente — o relacionamento também aceita withTrashed:

public function pedidos()
{
    return $this->hasMany(Pedido::class)->withTrashed();
}

Ou pontualmente, sem mexer na model:

$cliente->pedidos()->withTrashed()->get();

Bônus: e agora?

Olha as tabelas do seu projeto e pergunta pra cada uma: "se alguém apagar isso por engano, dói?" Pedido, fatura, contrato, usuário — provavelmente sim. Categoria de teste que você cria e joga fora — provavelmente não. Soft delete é ótimo, mas não precisa estar em tudo; coluna a mais e query um pouco mais complexa têm um custo.

E cuidado com a ideia de "guardar tudo pra sempre". Dependendo do dado (LGPD, por exemplo), você pode ser obrigado a apagar de verdade depois de um tempo. Aí um job periódico com forceDelete() nos registros antigos resolve.

Antes de você fechar a aba

Já perdeu algum registro importante em produção por causa de um delete() sem volta? Ou já foi salvo por um soft delete que alguém teve a sabedoria de colocar antes?

Me conta aí embaixo. E se esse post pode evitar um choro futuro no seu projeto, salva ele e manda pro colega que ainda apaga tudo direto no banco. 😅

Casts do Eloquent que você não sabia que existiam

Denis Augusto — Fri, 03 Jul 2026 15:09:26 +0000

Você ainda faz `json_decode` na mão, né?

Confessa. Tem um lugar no seu projeto onde você lê uma coluna do banco, dá um json_decode, mexe no array, dá json_encode de volta e salva. E toda vez você reza pra não esquecer o true no json_decode.

Ou pior: aquela coluna que guarda uma lista separada por vírgula e vive num vai-e-vem de explode e implode.

O Eloquent resolve isso há anos com casts. Só que a maioria dos devs conhece uns quatro (array, boolean, datetime, integer) e para por aí. O problema é que a lista é bem maior — e tem uns casts que são pura mão na roda esperando você descobrir.

Relembrando rapidinho: o que é um cast

Cast é uma tradução automática entre o formato que fica no banco e o formato que você quer usar no PHP. Você declara no model e o Eloquent faz a ponte sozinho, nos dois sentidos:

class Produto extends Model
{
    protected function casts(): array
    {
        return [
            'ativo'      => 'boolean',
            'preco'      => 'decimal:2',
            'publicado_em' => 'datetime',
        ];
    }
}

Até aqui, nada de novo. A graça começa nos casts que ninguém mostra.

`AsArrayObject`: array de verdade, mexível

O cast array clássico tem uma pegadinha chata: você não consegue mutar um item direto. Isso aqui não funciona como você espera:

$produto->options['cor'] = 'azul'; // ignorado silenciosamente 😑

Com AsArrayObject, funciona:

use Illuminate\Database\Eloquent\Casts\AsArrayObject;

protected function casts(): array
{
    return [
        'options' => AsArrayObject::class,
    ];
}

$produto->options['cor'] = 'azul';
$produto->options['tamanho'] = 'M';
$produto->save(); // salva certinho

Coluna JSON que você mexe direto, sem cerimônia.

`AsCollection`: sua coluna JSON vira Collection

Se você ama as Collections do Laravel (e você ama), por que trabalhar com aquele JSON como array cru? O AsCollection te devolve uma Collection completa, com map, filter, where, o pacote inteiro:

use Illuminate\Database\Eloquent\Casts\AsCollection;

protected function casts(): array
{
    return [
        'tags' => AsCollection::class,
    ];
}

$produto->tags->filter(fn ($tag) => $tag['ativo'])->pluck('nome');

E tem um detalhe pouco conhecido: dá pra apontar uma Collection customizada sua, com métodos próprios de negócio:

'options' => AsCollection::using(OptionCollection::class),

`AsEnumCollection`: lembra dos Enums? Agora um array deles

Já falei aqui sobre castar uma coluna pra Enum. Mas e quando a coluna guarda vários enums? Tipo as permissões de um usuário, os status pelos quais um pedido passou?

use App\Enums\Permissao;
use Illuminate\Database\Eloquent\Casts\AsEnumCollection;

protected function casts(): array
{
    return [
        'permissoes' => AsEnumCollection::of(Permissao::class),
    ];
}

Salva como JSON no banco, volta como uma Collection de enums tipados. Type-safety num array inteiro, de graça.

`AsStringable`: string com superpoderes

Toda vez que você faz Str::of($model->titulo)->slug(), tá tratando na mão o que o cast já faz. Com AsStringable, a coluna já sai como um objeto Stringable, pronto pra encadear:

use Illuminate\Database\Eloquent\Casts\AsStringable;

protected function casts(): array
{
    return [
        'titulo' => AsStringable::class,
    ];
}

$post->titulo->slug();      // já é fluente
$post->titulo->limit(50)->upper();

`encrypted` e `hashed`: segurança sem boilerplate

Precisa guardar um dado sensível criptografado no banco? Tem cast pra isso, e ele criptografa na gravação e descriptografa na leitura sozinho:

protected function casts(): array
{
    return [
        'token_api' => 'encrypted',
        'dados_bancarios' => 'encrypted:array', // criptografa E serializa
    ];
}

E pra senha, o hashed aplica o hash automático quando você atribui — chega de Hash::make() espalhado:

'password' => 'hashed',

$user->password = 'senha123'; // já vai hasheada pro banco

Como usar na prática

Configurações de usuário. Uma coluna preferencias JSON com AsArrayObject deixa você fazer $user->preferencias['tema'] = 'dark' e salvar, sem decode nenhum.

Roles/permissões. AsEnumCollection::of(Permissao::class) guarda a lista tipada e você compara com contains() sem medo de string errada.

Metadados de qualquer coisa. Pedido, produto, post — aquela coluna meta JSON com AsCollection te dá map, filter e amigos direto no model.

Pegadinha: quer o seu? Cria um custom cast

Nenhum dos prontos serve? Você cria o seu implementando CastsAttributes (leitura e gravação) ou CastsInboundAttributes (só na gravação, tipo um hash). Exemplo real de um cast que hasheia antes de salvar:

<?php

namespace App\Casts;

use Illuminate\Contracts\Database\Eloquent\CastsInboundAttributes;
use Illuminate\Database\Eloquent\Model;

class AsHash implements CastsInboundAttributes
{
    public function set(Model $model, string $key, mixed $value, array $attributes): string
    {
        return bcrypt($value);
    }
}

'codigo_secreto' => AsHash::class,

A regra de bolso: se você percebe que fica transformando o mesmo atributo do mesmo jeito toda vez, isso é um cast pedindo pra nascer.

Bônus: e agora?

Abre o model mais gordo do seu projeto e procura por json_decode, explode, Str::of($this-> ou Hash::make dentro dele. Cada um desses é forte candidato a virar cast e sumir do controller.

A doc oficial lista uns quantos que nem citei aqui — AsUri, AsFluent, immutable_datetime, decimal. Vale um passeio de 10 minutos.

Antes de você fechar a aba

Qual desses casts você não conhecia? Aposto que pelo menos um vai entrar no seu próximo commit. 😄

Me conta aí embaixo qual coluna JSON do seu projeto tá implorando por um AsArrayObject. E se o post te economizou uns json_decode, salva ele e manda pro colega que ainda trata dado na unha.

Migrations que não quebram em produção — o guia que ninguém te deu

Denis Augusto — Fri, 03 Jul 2026 15:09:25 +0000

A migration rodou liso. Aí você deu deploy.

Você criou a migration, rodou php artisan migrate no seu PC, tudo verdinho. Testou, funcionou, subiu pra produção numa sexta às 18h porque "é só uma coluninha".

E aí o deploy travou. Ou pior: rodou, mas a tabela de 8 milhões de linhas ficou travada por 40 segundos e o site deu timeout pra todo mundo.

Migration é traiçoeira assim. No banco vazio da sua máquina tudo é rápido e reversível. Em produção, com dados de verdade e usuários online, cada comando tem consequência. Bora ver os cuidados que separam um deploy tranquilo de um plantão não planejado.

Regra 1: o `down` tem que existir e funcionar

Toda migration tem up e down. O up você caprichou. O down? Geralmente tá vazio ou errado — e você só descobre no pior momento, quando precisa de um rollback às pressas.

public function up(): void
{
    Schema::table('pedidos', function (Blueprint $table) {
        $table->string('rastreio')->nullable();
    });
}

public function down(): void
{
    Schema::table('pedidos', function (Blueprint $table) {
        $table->dropColumn('rastreio'); // o inverso EXATO do up
    });
}

Regra de bolso: se você não consegue escrever um down que desfaz o up, sua migration provavelmente tá fazendo coisa demais. Teste o rollback antes do deploy: migrate e depois migrate:rollback na sua máquina. Se voltar limpo, respira aliviado.

Regra 2: nunca edite uma migration que já rodou em produção

Essa dói porque é tentador. Você criou a coluna com o tamanho errado, abre a migration antiga e conserta ali mesmo. No seu PC funciona (você deu migrate:fresh). Em produção, aquela migration já rodou — o Laravel não vai executá-la de novo. A correção nunca chega no servidor.

O certo é sempre uma migration nova:

// Nova migration, não mexe na antiga
Schema::table('users', function (Blueprint $table) {
    $table->string('name', 100)->change();
});

Migration é histórico. Você não reescreve o passado, você adiciona um capítulo.

Regra 3: adicionar coluna? `nullable` ou com `default`

Adicionar uma coluna NOT NULL sem valor padrão numa tabela que já tem dados é pedido de erro na certa — o banco não sabe o que colocar nas linhas existentes.

// 💣 explode se a tabela já tiver linhas
$table->string('cpf');

// ✅ seguro
$table->string('cpf')->nullable();
// ou
$table->boolean('ativo')->default(true);

Precisa mesmo que a coluna seja obrigatória e preenchida? Faz em três passos: cria nullable, preenche os dados, depois torna obrigatória. Nunca tudo de uma vez numa tabela grande.

Regra 4: `dropColumn` apaga dados. Pra sempre.

Rollback de coluna adicionada é tranquilo. Rollback de coluna removida não existe — o down recria a coluna vazia, mas os dados que estavam lá já foram pro além.

public function up(): void
{
    Schema::table('users', function (Blueprint $table) {
        $table->dropColumn('bio'); // os dados somem AGORA
    });
}

Antes de dropar em produção: tem backup? Tem certeza que nada mais usa essa coluna? Uma prática segura é deixar a coluna morrer aos poucos — para de usá-la no código num deploy, e só remove no banco semanas depois, quando tem certeza absoluta.

Regra 5: separe mudança de schema de mudança de dados

A tentação é preencher os dados na mesma migration que altera a estrutura. O problema: um User::all() dentro da migration pode carregar milhões de registros na memória e travar o deploy.

Se precisar transformar dados, use chunk pra não estourar a memória — ou, melhor ainda, jogue isso num comando/job separado que roda depois da migration:

// Se for na migration mesmo, ao menos vá de chunk:
User::where('tipo', null)->chunkById(500, function ($users) {
    foreach ($users as $user) {
        $user->update(['tipo' => 'comum']);
    }
});

Schema é uma coisa, dado é outra. Misturar os dois numa migration só é onde os deploys vão morrer.

Regra 6: no deploy, sempre `--force`

Em produção o Laravel pergunta "tem certeza?" antes de rodar migration — e num pipeline automatizado isso trava esperando um "yes" que nunca vem. A flag --force pula a confirmação:

php artisan migrate --force

Coloca isso no seu script de deploy e nunca mais veja o pipeline pendurado esperando input.

Pegadinha: tabela grande = lock demorado

Num MySQL, alterar uma coluna (change()) ou adicionar índice numa tabela gigante pode travar a tabela inteira durante a operação. No seu PC com 200 linhas é instantâneo. Em produção com milhões, são segundos (ou minutos) de tabela indisponível.

Pra tabelas realmente grandes, vale olhar ferramentas de migração online (como pt-online-schema-change) ou rodar a alteração numa janela de baixo tráfego. Só de saber que o lock existe você já evita a surpresa.

Bônus: seu checklist de pré-deploy

Antes de dar push numa migration, passa por essa lista mental:

O down desfaz o up? Testei o rollback local?
Estou editando uma migration antiga? (Se sim, para. Cria uma nova.)
Coluna nova é nullable ou tem default?
Tem dropColumn? Tem backup e certeza?
Tem manipulação de dados pesada? Dá pra separar num job?

Antes de você fechar a aba

Migration não é código descartável — é a coisa que roda direto no seu banco de produção, sem rede de proteção. Um pouco de paranoia aqui economiza muitos plantões.

Me conta aí embaixo: qual migration já te deu o maior susto em produção? Todo dev tem uma história dessas. 😅 E se esse checklist te salvou de um deploy na sexta, salva o post e manda pro colega que ainda edita migration antiga.

Seu status de pedido não devia ser uma string

Denis Augusto — Thu, 02 Jul 2026 19:58:53 +0000

Quantos jeitos de escrever "pendente" existem no seu banco?

Abre a tabela de pedidos aí do seu projeto e dá uma olhada na coluna status. Aposto que você acha pending, Pending, talvez um pendente perdido de quando o cliente pediu pra traduzir, e vai saber, um pnding que passou batido numa madrugada.

Isso acontece porque status virou uma string solta. Qualquer um pode escrever qualquer coisa ali. Não tem trava, não tem autocomplete, não tem ninguém pra dizer "opa, esse valor não existe".

Já perdeu meia hora caçando um bug que era só um paid escrito payed? Senta aí, porque o PHP 8.1 resolveu isso e o Laravel abraçou a solução com carinho.

O reino da string mágica

O cenário clássico. Status espalhado como texto puro pelo código inteiro:

// No controller
$pedido->status = 'pending';

// No outro controller
if ($pedido->status === 'paid') {
    // ...
}

// Naquela blade
@if($pedido->status == 'canceled')

// E no service, com um pequeno "typo" que ninguém viu
$pedido->update(['status' => 'canceld']);

Cada um desses 'pending', 'paid', 'canceled' é o que a gente chama de string mágica: um valor cru, sem significado formal, que você reza pra ter digitado certo.

E o problema não é só o typo. É que nada te avisa dos valores possíveis. Chegou dev novo no time? Ele vai ter que caçar no grep quais status existem. Mudou paid pra payment_confirmed? Boa sorte achando os 23 lugares.

A meia-solução que muita gente usa

Aí você lembra das constantes e pensa "já resolvi isso":

class Pedido extends Model
{
    const STATUS_PENDING  = 'pending';
    const STATUS_PAID     = 'paid';
    const STATUS_CANCELED = 'canceled';
}

$pedido->status = Pedido::STATUS_PAID;

Melhorou? Um pouco. Ganhou autocomplete e centralizou os valores. Mas ainda tem furo: nada impede alguém de gravar $pedido->status = 'qualquer_coisa' direto. A constante é uma sugestão, não uma regra. E você continua sem um lugar único pra pendurar comportamento (a cor do badge, o label bonito, se aquele status permite cancelamento...).

Dá pra fazer melhor. E de fábrica.

A solução: Enums de verdade

O PHP 8.1 trouxe os backed enums — enums com um valor por trás. É um tipo novo, de verdade, que só aceita os casos que você definiu:

<?php

namespace App\Enums;

enum StatusPedido: string
{
    case Pending  = 'pending';
    case Paid     = 'paid';
    case Canceled = 'canceled';
}

Repara no : string ali no topo: é isso que faz cada caso ter um valor de string por trás, perfeito pra salvar no banco. Agora StatusPedido::Paid é um objeto tipado, não um texto solto. E aqui mora a mágica: no Laravel, você fala pro model tratar a coluna como esse enum, usando o cast:

class Pedido extends Model
{
    protected function casts(): array
    {
        return [
            'status' => StatusPedido::class,
        ];
    }
}

Pronto. A partir daqui o Eloquent faz a ponte sozinho: grava a string no banco, devolve o enum quando você lê:

$pedido->status = StatusPedido::Paid; // grava 'paid' no banco
$pedido->status;                      // volta como StatusPedido::Paid (objeto)

if ($pedido->status === StatusPedido::Paid) {
    // type-safe, com autocomplete, sem chance de typo
}

Tentou atribuir uma string inválida? Estoura na hora. O valor errado nem chega no banco.

Como usar na prática

Comparação sem medo. Acabou o === 'paid'. Agora é === StatusPedido::Paid, e o editor te entrega o autocomplete de todos os casos:

if ($pedido->status === StatusPedido::Canceled) {
    return back()->with('erro', 'Esse pedido já foi cancelado.');
}

Comportamento junto do dado. O melhor dos enums: eles têm métodos. Aquela lógica de "qual a cor do badge" para de viver espalhada na blade e vira parte do próprio status:

enum StatusPedido: string
{
    case Pending  = 'pending';
    case Paid     = 'paid';
    case Canceled = 'canceled';

    public function label(): string
    {
        return match($this) {
            self::Pending  => 'Aguardando pagamento',
            self::Paid     => 'Pago',
            self::Canceled => 'Cancelado',
        };
    }

    public function cor(): string
    {
        return match($this) {
            self::Pending  => 'yellow',
            self::Paid     => 'green',
            self::Canceled => 'red',
        };
    }
}

Na view, fica limpo assim:

<span class="badge badge-{{ $pedido->status->cor() }}">
    {{ $pedido->status->label() }}
</span>

Preencher um select. O método cases() já te dá todos os valores possíveis, prontos pra iterar:

@foreach (StatusPedido::cases() as $status)
    <option value="{{ $status->value }}">{{ $status->label() }}</option>
@endforeach

Pegadinha: `value` vs. `name` vs. o caso em si

Aqui rola uma confusão comum. Um backed enum tem três coisas fáceis de embolar:

StatusPedido::Paid — o caso em si, o objeto tipado. É o que você usa em comparação.
StatusPedido::Paid->value — a string por trás ('paid'). É o que vai pro banco, pro value do <option>, pra API.
StatusPedido::Paid->name — o nome do caso no código ('Paid'). Raramente é o que você quer mostrar pro usuário.

Regra rápida: comparou lógica? Usa o caso. Precisou do valor cru (banco, HTML, JSON)? Usa ->value. E pra transformar uma string de volta em enum — tipo o que chega de um request — tem o from() e o tryFrom():

StatusPedido::from('paid');      // StatusPedido::Paid
StatusPedido::from('inexistente'); // estoura ValueError
StatusPedido::tryFrom('xpto');   // null, sem estourar (ótimo pra input do usuário)

Bônus: validação de request de brinde

Já que estamos falando de dados que entram, o Laravel valida enum direto na regra. Se alguém mandar um status que não existe no request, nem passa:

use Illuminate\Validation\Rule;

'status' => ['required', Rule::enum(StatusPedido::class)],

Junta isso com o Form Request que você já usa e o status inválido morre antes de chegar no controller. String mágica não passa nem na porta.

Antes de você fechar a aba

Faz um teste rápido: dá um grep por 'pending', 'paid' ou qualquer status do seu projeto. Quantos lugares apareceram? Cada um deles é uma string mágica esperando pra te dar dor de cabeça numa refatoração.

Me conta aí embaixo: qual é a string mágica mais cabeluda que ainda vive no seu código? Status de pedido, tipo de usuário, forma de pagamento... todo projeto tem a sua. 😄

E se esse post te deu vontade de matar umas strings soltas hoje, salva ele e manda pro colega que ainda escreve === 'paid' por aí.

Seu controller tá fazendo o trabalho do Form Request (e ele não devia)

Denis Augusto — Fri, 26 Jun 2026 15:42:12 +0000

Abre o seu controller. Vai, eu espero

Tem um método store() aí dentro com umas 40 linhas? Começando com um $request->validate([...]) gigante, seguido de um monte de if, depois a regra de negócio, depois o retorno?

Pois é. Seu controller tá fazendo um trabalho que não é dele.

A função de um controller é simples: receber a requisição, chamar quem resolve o problema, devolver a resposta. Ele é o garçom, não o cozinheiro. E ainda assim a gente vive enfiando validação, autorização e tratamento de dados ali no meio, até virar aquele monstrinho de 80 linhas que ninguém quer abrir na sexta-feira.

Já viu (ou escreveu) isso? Senta aí que tem solução, e ela já vem de fábrica no Laravel.

O controller-faz-tudo

Olha esse clássico:

public function store(Request $request)
{
    $validated = $request->validate([
        'titulo'    => 'required|string|max:255',
        'conteudo'  => 'required|string|min:10',
        'categoria' => 'required|exists:categorias,id',
    ]);

    if (! $request->user()->can('criar-post')) {
        abort(403);
    }

    $validated['slug'] = Str::slug($validated['titulo']);

    $post = Post::create($validated);

    return redirect()->route('posts.show', $post);
}

Funciona? Funciona. Mas repara quantas responsabilidades diferentes tão espremidas aí: validação, autorização, transformação de dado e a regra de negócio de verdade. Tudo no mesmo lugar.

Agora imagina esse mesmo bloco repetido no update(). E na versão da API. Copiado, colado, com pequenas diferenças. De novo a velha história.

O controller tem UMA função

Existe um princípio chamado Single Responsibility: cada classe deveria ter um motivo só pra mudar. O controller muda quando o fluxo da requisição muda — não quando uma regra de validação muda, não quando uma permissão muda.

Validação é um conhecimento. Autorização é outro. Cada um merece morar na sua própria casa, e o Laravel já construiu essa casa pra você: o Form Request.

A solução: tira o peso do controller

Gera com um comando:

php artisan make:request StorePostRequest

Isso cria app/Http/Requests/StorePostRequest.php. Joga tudo que não é função de controller pra dentro dele:

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Support\Str;

class StorePostRequest extends FormRequest
{
    // Autorização: este usuário pode fazer isso?
    public function authorize(): bool
    {
        return $this->user()->can('criar-post');
    }

    // Validação: os dados estão corretos?
    public function rules(): array
    {
        return [
            'titulo'    => ['required', 'string', 'max:255'],
            'conteudo'  => ['required', 'string', 'min:10'],
            'categoria' => ['required', 'exists:categorias,id'],
        ];
    }

    // Preparação: ajusta os dados ANTES de validar
    protected function prepareForValidation(): void
    {
        $this->merge([
            'slug' => Str::slug($this->titulo),
        ]);
    }
}

E agora olha o que sobrou do controller:

public function store(StorePostRequest $request)
{
    $post = Post::create($request->validated());

    return redirect()->route('posts.show', $post);
}

Duas linhas. Duas. O controller voltou a ser garçom.

O pulo do gato é o type-hint: ao trocar Request por StorePostRequest, o Laravel roda a autorização e a validação automaticamente antes do método executar. Falhou? Nem entra no store(). O usuário já recebe o erro certo, redirecionado de volta, com as mensagens preenchidas.

Form Request não é só `rules()`

Esse é o ponto que quase ninguém usa direito. O Form Request tem três super-poderes, não um:

Autorização — o authorize() decide quem pode. Retornou false, vira 403 sozinho:

public function authorize(): bool
{
    return $this->user()->id === $this->route('post')->user_id;
}

Mensagens customizadas — sem espalhar texto pelo projeto:

public function messages(): array
{
    return [
        'titulo.required' => 'O título é obrigatório, capricha nele.',
        'conteudo.min'    => 'Conteúdo muito curto, conta mais história.',
    ];
}

Preparação de dados — o prepareForValidation() ajusta a entrada antes da regra rodar. Ótimo pra normalizar CPF, gerar slug, limpar máscara de telefone.

Tudo isso saiu do controller e foi morar onde faz sentido.

Pausa: e quando NÃO usar?

Porque sim, dá pra exagerar. Form Request vira muleta quando você cria um pra toda e qualquer rota, mesmo as triviais.

Tem um endpoint que valida só um campo? Um filtro de busca com um q opcional? Criar uma classe inteira pra isso é cerimônia demais. Um $request->validate(['q' => 'nullable|string']) ali mesmo resolve e é mais legível.

A régua é simples: se a validação é curta, usada num lugar só e não tem autorização envolvida, deixa inline. Se ela cresce, se repete, ou se mistura validação com permissão — chama o Form Request. Ele existe pra tirar peso, não pra adicionar burocracia.

E mais um aviso: Form Request não é lugar de regra de negócio. Calcular preço, disparar evento, mexer em outras tabelas — isso é trabalho da camada de serviço, não da validação. Não troque um controller inchado por um Form Request inchado.

Bônus: olha quantos controllers seus pedem isso

Pega seu projeto e procura por $request->validate(. Quantos resultados? Cada um daqueles, especialmente os que se repetem entre store e update, é um Form Request esperando pra nascer.

Começa pelo controller mais bagunçado que você tem. Extrai um. Vê como ele encolhe. Vicia.

Antes de você fechar a aba

Pergunta sincera: qual é o controller mais inchado do seu projeto hoje? Aquele que você sente um arrepio só de abrir.

Comenta aí embaixo o tamanho do método store() mais cabeludo que você já viu (ou escreveu, sem vergonha). E se esse post te deu vontade de fazer um refactor agora, salva ele e manda pro colega que ainda valida tudo no controller.

Seu controller magro agradece. 😄

Seu código de validação de CPF tá gritando por socorro (e você nem percebeu)

Denis Augusto — Fri, 26 Jun 2026 15:37:27 +0000

Deixa eu adivinhar.

Você tá com um projeto Laravel rodando, tem uns 5, 10, talvez 15 formulários que recebem CPF. Cadastro de cliente, cadastro de fornecedor, atualização de perfil, checkout, área administrativa… e em cada um desses lugares tem aquela mesma lógica de validação de CPF. Copiada. Colada. Com pequenas variações.

E tá tudo bem. Até o dia em que o cliente pede pra mudar uma regra. Ou um bug aparece em um formulário e funciona normal no outro. Aí você abre o projeto, dá um Ctrl+Shift+F procurando "cpf" e… surpresa: tem oito lugares diferentes com a mesma validação. Com mensagens de erro escritas de oito jeitos. Uma delas até com erro de digitação.

Já passou por isso? Então senta que essa conversa é pra você.

O crime acontecendo em câmera lenta

Olha esse cenário aqui, que eu garanto que você já viu (ou escreveu):

// app/Http/Requests/StoreClienteRequest.php
public function rules()
{
    return [
        'cpf' => ['required', function ($attribute, $value, $fail) {
            $cpf = preg_replace('/[^0-9]/', '', $value);
            if (strlen($cpf) !== 11) {
                $fail('CPF inválido.');
                return;
            }
            // ... mais 20 linhas do algoritmo
        }],
    ];
}

E aí, três dias depois, no outro Form Request:

// app/Http/Requests/StoreFornecedorRequest.php
public function rules()
{
    return [
        'cpf' => ['required', function ($attribute, $value, $fail) {
            $cpf = preg_replace('/[^0-9]/', '', $value);
            if (strlen($cpf) !== 11) {
                $fail('O CPF informado não é válido!');  // mensagem diferente, claro
                return;
            }
            // ... mais 20 linhas quase iguais, mas não exatamente
        }],
    ];
}

Multiplica isso por 8 telas. Agora imagina o seu "eu do futuro" tentando manter isso.

Dá pra sentir a dor daqui.

DRY: a sigla que vai salvar seu projeto (e sua sanidade)

DRY significa Don't Repeat Yourself. Em bom português: não se repita, caramba.

A ideia é simples: cada pedaço de conhecimento (uma regra de negócio, um cálculo, uma validação) deve existir em um único lugar no seu sistema. Se precisar mudar, você muda em um lugar só, e todo o resto continua funcionando.

No nosso caso, a "regra de validar CPF" é um conhecimento. E esse conhecimento merece ter um endereço fixo no seu projeto, não ficar espalhado igual confete depois do Carnaval.

E se eu te dissesse que o Laravel já resolveu isso pra você?

O Laravel tem um recurso chamado Custom Validation Rule. É basicamente uma classe que encapsula uma regra de validação. Você escreve uma vez, usa em qualquer lugar.

Gera com um comando:

php artisan make:rule Cpf

Isso cria o arquivo app/Rules/Cpf.php. Abre ele e coloca o algoritmo de validação ali dentro:

<?php

namespace App\Rules;

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

class Cpf implements ValidationRule
{
    public function validate(string $attribute, mixed $value, Closure $fail): void
    {
        // Tira tudo que não é número
        $cpf = preg_replace('/[^0-9]/', '', (string) $value);

        // CPF tem 11 dígitos. Ponto.
        if (strlen($cpf) !== 11) {
            $fail('O :attribute informado não é um CPF válido.');
            return;
        }

        // Rejeita sequências repetidas (111.111.111-11, 222.222.222-22, etc)
        if (preg_match('/(\d)\1{10}/', $cpf)) {
            $fail('O :attribute informado não é um CPF válido.');
            return;
        }

        // Calcula os dois dígitos verificadores
        for ($t = 9; $t < 11; $t++) {
            $d = 0;
            for ($c = 0; $c < $t; $c++) {
                $d += $cpf[$c] * (($t + 1) - $c);
            }
            $d = ((10 * $d) % 11) % 10;

            if ($cpf[$c] != $d) {
                $fail('O :attribute informado não é um CPF válido.');
                return;
            }
        }
    }
}

Pronto. Acabou. Esse é o único lugar do seu projeto que sabe validar CPF.

Usando na prática

Agora vem a parte boa. Você usa essa Rule em qualquer lugar, com uma linha:

Em um Form Request:

use App\Rules\Cpf;

public function rules()
{
    return [
        'cpf' => ['required', new Cpf()],
    ];
}

Inline no controller:

$request->validate([
    'cpf' => ['required', new Cpf()],
]);

Com Validator facade:

Validator::make($request->all(), [
    'cpf' => ['required', new Cpf()],
])->validate();

Mesmo código. Mesma mensagem de erro. Mesmo comportamento. Em todo lugar.

Mudou a regra? Mexe no app/Rules/Cpf.php. Pronto, mudou em todo lugar.

Pausa rápida: Rule não é Role

Detalhe que confunde muita gente (e tudo bem, eu também já confundi):

Rule = regra de validação. É disso que a gente tá falando.
Role = papel de usuário, ligado a permissões e autorização (tipo "admin", "editor", "cliente").

São coisas completamente diferentes, só têm nome parecido. Se você buscou no Google "Laravel Role validação" e tava perdido, agora sabe o porquê. 😄

Bônus: e agora?

Pegou a ideia? Então olha quantas outras validações no seu projeto provavelmente tão duplicadas:

CNPJ
Telefone (com DDD, formato brasileiro)
CEP
Data de nascimento (maioridade, idade mínima, etc)
Placa de veículo
Cartão de crédito

Cada uma dessas é uma Rule esperando pra nascer. Que tal escolher uma e criar agora? Lição de casa rápida pra quando você terminar de ler isso aqui.

Antes de você fechar a aba

Aqui vai uma pergunta sincera: qual validação você ainda mantém copiada e colada no seu projeto Laravel?

Comenta aí embaixo. Eu juro que não vou julgar (eu mesmo tenho um projeto antigo que precisa urgentemente desse refactor).

E se esse post te poupou de uma dor de cabeça futura, salva ele, compartilha com aquele dev que tá começando agora, ou manda pro seu colega de equipe que tá com 14 controllers validando CPF do jeito errado.

Seu eu do futuro agradece. Seu projeto, também.

Curtiu? Tem mais conteúdo sobre Laravel, boas práticas e como deixar seu código mais limpo por aqui. Me segue pra não perder os próximos.

DEV Community: Denis Augusto

Deixei um bot derrubar minha API antes de descobrir o throttle

Segunda de manhã, servidor no chão, e eu sem entender nada

O problema: sua API confia em todo mundo

A versão de 3 linhas: middleware throttle

A versão profissional: named limiters

Como usar na prática

Pegadinha: os headers que ninguém lê (mas deveria)

Bônus: e agora?

Antes de você fechar a aba

Funciona na minha máquina: o mistério do env() que some em produção

"Mas aqui na minha máquina roda perfeitamente"

O código que parece inofensivo

O que o config:cache faz (e por que ele te trai)

A regra de ouro

Como usar na prática

A pegadinha da pegadinha

Bônus: e agora?

Antes de você fechar a aba

API Resources no Laravel: pare de dar return no seu Model cru

Sua API tá contando segredo pro mundo inteiro

O código que todo mundo já escreveu

O $hidden ajuda, mas não resolve

A solução: uma camada só pra montar a resposta

Como usar no controller

O pulo do gato: campos condicionais

A pegadinha que confunde muita gente

Bônus: e agora?

Antes de você fechar a aba

DB::transaction(): o try/catch que salva seu banco de dados

Salvou o pedido, mas não salvou os itens. E agora?

O código que parece inofensivo (mas não é)

O conceito por trás: atomicidade

A solução: DB::transaction()

Como usar na prática

A versão manual (pra quando você precisa de controle)

A pegadinha que pega todo mundo

Bônus: e agora?

Antes de você fechar a aba

Soft Deletes no Laravel: apague sem apagar de verdade

"Some do banco" nem sempre é o que você quer

O problema: delete() é definitivo

A solução: três passos e pronto

Trazendo de volta e vendo os apagados

Como usar na prática

Pegadinha 1: unique não sabe de soft delete

Pegadinha 2: relacionamento com registro apagado

Bônus: e agora?

Antes de você fechar a aba

Casts do Eloquent que você não sabia que existiam

Você ainda faz json_decode na mão, né?

Relembrando rapidinho: o que é um cast

AsArrayObject: array de verdade, mexível

AsCollection: sua coluna JSON vira Collection

AsEnumCollection: lembra dos Enums? Agora um array deles

AsStringable: string com superpoderes

encrypted e hashed: segurança sem boilerplate

Como usar na prática

Pegadinha: quer o seu? Cria um custom cast

Bônus: e agora?

Antes de você fechar a aba

Migrations que não quebram em produção — o guia que ninguém te deu

A migration rodou liso. Aí você deu deploy.

Regra 1: o down tem que existir e funcionar

Regra 2: nunca edite uma migration que já rodou em produção

Regra 3: adicionar coluna? nullable ou com default

Regra 4: dropColumn apaga dados. Pra sempre.

Regra 5: separe mudança de schema de mudança de dados

Regra 6: no deploy, sempre --force

Pegadinha: tabela grande = lock demorado

Bônus: seu checklist de pré-deploy

Antes de você fechar a aba

Seu status de pedido não devia ser uma string

Quantos jeitos de escrever "pendente" existem no seu banco?

O reino da string mágica

A meia-solução que muita gente usa

A solução: Enums de verdade

Como usar na prática

Pegadinha: value vs. name vs. o caso em si

Bônus: validação de request de brinde

A versão de 3 linhas: middleware `throttle`

O `$hidden` ajuda, mas não resolve

O problema: `delete()` é definitivo

Pegadinha 1: `unique` não sabe de soft delete

Você ainda faz `json_decode` na mão, né?

`AsArrayObject`: array de verdade, mexível

`AsCollection`: sua coluna JSON vira Collection

`AsEnumCollection`: lembra dos Enums? Agora um array deles

`AsStringable`: string com superpoderes

`encrypted` e `hashed`: segurança sem boilerplate

Regra 1: o `down` tem que existir e funcionar

Regra 3: adicionar coluna? `nullable` ou com `default`

Regra 4: `dropColumn` apaga dados. Pra sempre.

Regra 6: no deploy, sempre `--force`

Pegadinha: `value` vs. `name` vs. o caso em si

Form Request não é só `rules()`