DEV Community: Denis Augusto

Você testou a API funcionando. E quando ela cair?

Denis Augusto — Tue, 04 Aug 2026 22:58:21 +0000

O caminho feliz sempre passa. O problema é o outro.

Sua integração com o gateway funciona. Você testou. O teste tá verde. Deploy feito, tá em produção há meses.

Aí, numa terça qualquer, o gateway devolve um erro 500. Instabilidade do lado deles.

E o seu app? Cospe uma tela branca com Undefined array key "transaction_id" na cara do cliente. Porque seu código pegou a resposta de erro e tentou ler o transaction_id que não existe ali.

Você testou a API funcionando. Nunca testou ela falhando. E é exatamente aí que mora o bug.

O teste que só conhece o dia bonito

Olha o teste típico de integração. Aposto que o seu se parece com esse:

public function test_processa_o_pagamento(): void
{
    Http::fake([
        'gateway.com/*' => Http::response([
            'status'         => 'aprovado',
            'transaction_id' => 'tx_123',
        ], 200),
    ]);

    $resultado = $this->service->cobrar($pedido);

    $this->assertTrue($resultado->aprovado);
}

Bonito. Verde. E completamente ingênuo.

Ele responde uma única pergunta: "quando dá tudo certo, meu código funciona?". Ótimo. Mas a produção não é só o dia bonito. A API vai devolver 500, vai dar timeout, vai responder um JSON estranho, vai ficar fora do ar. E você nunca escreveu uma linha testando o que acontece nesses casos.

O caminho feliz é o que menos quebra. O caminho de falha é onde o cliente vê tela branca.

O resgate: `Http::fake()` também simula desastre

Aqui tá a beleza de mockar a API — você não fica refém de esperar ela cair pra ver o que acontece. Você manda ela cair. Na hora que quiser, no teste que quiser.

public function test_gateway_fora_do_ar_nao_quebra_o_app(): void
{
    // simula o gateway devolvendo erro 500
    Http::fake([
        'gateway.com/*' => Http::response('Service Unavailable', 500),
    ]);

    $resultado = $this->service->cobrar($pedido);

    // seu código degrada com elegância, em vez de explodir?
    $this->assertFalse($resultado->aprovado);
    $this->assertEquals('gateway_indisponivel', $resultado->motivo);
    $this->assertEquals('pendente', $pedido->fresh()->status);
}

Esse teste vale ouro. Ele te obriga a responder: "quando o gateway cai, meu pedido fica num estado consistente ou vira lixo?". Se o teste passa, você sabe que o cliente vê uma mensagem decente e o pedido fica pendente pra retentar — não uma tela branca.

Os três desastres que você precisa testar

Não é só o erro 500. O mundo real tem sabores variados de falha:

// 1. Erro do servidor (a API respondeu, mas com pau)
Http::fake(['gateway.com/*' => Http::response('', 500)]);

// 2. Resposta inesperada (mudaram o contrato, ou veio corrompido)
Http::fake(['gateway.com/*' => Http::response(['algo' => 'diferente'], 200)]);

// 3. A API nem respondeu (timeout / fora do ar)
Http::fake(fn () => throw new ConnectionException('timeout'));

Cada um exercita um pedaço diferente do seu tratamento de erro. O 500 testa seu throw(). A resposta estranha testa se você valida o que recebeu antes de usar. A ConnectionException testa o que acontece quando a requisição nem chega — o cenário do post sobre timeout e retry, agora coberto por teste.

A pegadinha: caminho de falha sem tratamento não "passa", ele engana

Cuidado com uma armadilha sutil. Se seu código não trata o erro, esse teste de falha pode passar por engano — porque o Laravel lança a exceção e o teste morre com ela, ou o assert bate em cima de um estado que você nem pensou.

O teste de falha só tem valor se você escreveu o teste esperando um comportamento específico e digno: uma flag aprovado = false, um status pendente, uma exceção sua tratada. Se você não sabe o que seu código deveria fazer quando a API cai... esse é o verdadeiro bug, e o teste acabou de te mostrar.

Antes de você fechar a aba

O caminho feliz é o mínimo. Ele prova que seu código funciona no melhor dos mundos — que é justamente o mundo que menos acontece.

O teste que te salva de plantão às 2 da manhã é o do caminho de falha. Pega a sua integração externa mais crítica e se pergunta: "eu tenho um teste que simula essa API caindo?". Se a resposta é não, você já sabe qual teste escrever amanhã.

Me conta: você testa o caminho de falha das suas integrações, ou só o dia bonito? Sem julgamento — a maioria só testa o feliz. 👀

Seu teste bate na API de verdade? Um dia ela vai te trair

Denis Augusto — Tue, 04 Aug 2026 22:57:40 +0000

O teste quebrou. E não foi você.

Segunda de manhã, você abre o projeto e o CI tá vermelho.

Você não mexeu em nada desde sexta. Abre o log: o teste de integração com a API de pagamento falhou. Timeout.

O gateway deles teve uma instabilidade às 3 da manhã. Seu código tá perfeito. Mesmo assim, o build tá vermelho, o deploy travado, e agora você perde meia hora provando que o problema não é seu.

Já passou por isso? Teste que depende de API externa é assim: lento, instável e quebra por motivos que não são culpa sua. E tem o cenário pior — o teste que roda de verdade contra a API de pagamento, e a cada php artisan test você dispara 30 cobranças reais no sandbox até o gateway achar suspeito e bloquear.

O problema: seu teste não deveria conhecer a internet

Olha esse teste. Parece razoável, né?

public function test_busca_o_cep(): void
{
    // isso bate no ViaCEP de VERDADE, toda vez que o teste roda
    $endereco = $this->service->buscarCep('01001000');

    $this->assertEquals('São Paulo', $endereco['cidade']);
}

O que tem de errado? Tudo que importa num teste:

Lento — cada teste espera a ida e volta pela rede.
Instável — a API cair, ficar lenta ou mudar o retorno quebra seu teste sem seu código ter mudado.
Perigoso — se for uma API que cobra, envia e-mail ou cria pedido, você tá fazendo isso pra valer a cada execução.
Sem controle — como você testa "o que acontece quando a API devolve erro 500"? Não dá pra pedir pra ela cair na hora certa.

O teste devia verificar o seu código. Não a saúde do servidor dos outros.

A solução: `Http::fake()` intercepta tudo

Aqui vem o $pedido->restore() dessa história. Se você usa o HTTP Client do Laravel (Http::get(), Http::post()...), uma linha resolve:

use Illuminate\Support\Facades\Http;

public function test_busca_o_cep(): void
{
    // A partir daqui, NENHUMA requisição sai de verdade.
    // Você diz o que cada URL deve responder.
    Http::fake([
        'viacep.com.br/*' => Http::response([
            'localidade' => 'São Paulo',
            'uf'         => 'SP',
        ], 200),
    ]);

    $endereco = $this->service->buscarCep('01001000');

    $this->assertEquals('São Paulo', $endereco['cidade']);
}

Pronto. O Http::fake() intercepta a requisição e devolve a resposta que você mandou, sem tocar na internet. O teste roda offline, em milissegundos, e dá o mesmo resultado toda vez. Você virou dono do comportamento da API.

Como usar na prática

O fake() é flexível. Alguns cenários que você vai usar toda hora:

// Fingir QUALQUER requisição como 200 vazio (o mais simples)
Http::fake();

// Respostas diferentes por URL
Http::fake([
    'github.com/*'  => Http::response(['plano' => 'pro'], 200),
    'viacep.com.br/*' => Http::response('', 404), // simula CEP não achado
]);

// Simular a API fora do ar (erro 500) — o caminho que ninguém testa
Http::fake([
    'gateway.com/*' => Http::response('Erro interno', 500),
]);

Repara no último: agora você consegue testar o caminho de falha. "Se o gateway devolver 500, meu app mostra uma mensagem amigável ou explode na cara do usuário?" Sem fake(), você nunca teve como responder isso.

Não basta simular: confirme que você mandou certo

Aqui mora a pegadinha que separa o teste que testa do teste que só finge.

Simular a resposta não garante que você montou a requisição direito. Passou o header de autenticação? Mandou o valor no campo certo? O Http::assertSent() confere isso:

Http::fake();

$this->service->cobrar(valor: 150, cartao: 'tok_abc');

Http::assertSent(function (Request $request) {
    return $request->url() === 'https://gateway.com/charges'
        && $request->hasHeader('Authorization')
        && $request['amount'] === 150;
});

Agora o teste garante os dois lados: você mandou o que devia e reagiu certo à resposta.

Bônus: proíba requisições reais escaparem

Tem um detalhe traiçoeiro. Se você esquecer de fakear uma URL, a requisição sai de verdade — e você nem percebe que aquele teste ainda depende da internet.

O preventStrayRequests() fecha essa porta:

Http::preventStrayRequests();

Http::fake([
    'gateway.com/*' => Http::response('ok'),
]);

Http::get('https://gateway.com/charges'); // ok, tá fakeado
Http::get('https://outra-api.com');        // 💥 lança exceção na hora

Qualquer requisição sem fake correspondente estoura na hora, em vez de vazar silenciosamente pra rede. Coloca isso no setUp() da sua suíte de testes e durma tranquilo.

Antes de você fechar a aba

A regra de ouro: teste não conversa com o mundo lá fora. Ele verifica o seu código, de forma rápida e previsível. A conversa real com a API você deixa pra um teste de integração separado, que roda de vez em quando — não a cada commit.

Um detalhe importante: isso só funciona se você usa o HTTP Client do Laravel (Http::). Se ainda chama Guzzle ou cURL na mão, o fake() não te alcança — e migrar pro Http:: é justamente o próximo passo (spoiler: ele também te dá timeout e retry de graça, mas isso é papo pra outro post).

Me conta: você mocka suas APIs nos testes ou ainda reza pro sandbox ficar de pé? 👀

A API de terceiro caiu e derrubou seu app junto

Denis Augusto — Tue, 04 Aug 2026 22:56:07 +0000

A API deles caiu. Por que o SEU app caiu junto?

O fornecedor de frete teve um problema. A API deles ficou lenta — respondendo em 40 segundos em vez de 200 milissegundos.

Do lado deles, um incidente. Do seu lado? Caos.

Cada requisição que seu app fez pra calcular o frete ficou pendurada esperando. Os workers da fila entupiram. As conexões do PHP-FPM esgotaram. Em poucos minutos, seu app inteiro parou de responder — não só o checkout, tudo.

Um problema que era deles virou seu problema. E o pior: era evitável com três linhas.

O código que confia demais no mundo lá fora

Chamada de API é um ato de fé. Você pede algo pra um servidor que não é seu e espera que ele responda rápido, sempre, sem erro. Spoiler: ele não vai.

// Confiança cega: espera pra sempre, e reza pra dar certo
$response = Http::get('https://api-frete.com/cotacao', [
    'cep' => $cep,
]);

return $response->json();

O que tá faltando aqui?

Sem limite de espera. Se a API travar, sua requisição trava junto. Por padrão o HTTP Client espera até 30 segundos — uma eternidade quando isso acontece em cascata.
Sem tentar de novo. Uma falha de rede momentânea (acontece o tempo todo) já derruba a operação inteira.
Sem tratar erro. Se a API devolver 500, o $response->json() segue como se nada fosse, e você processa lixo achando que é cotação.

A blindagem: `timeout`, `retry` e `throw`

O HTTP Client do Laravel já traz o resgate embutido. Você encadeia e pronto:

$response = Http::timeout(5)   // desiste depois de 5s, não fica pendurado
    ->retry(3, 200)            // tenta 3x, esperando 200ms entre as tentativas
    ->get('https://api-frete.com/cotacao', ['cep' => $cep]);

$response->throw();            // erro 4xx/5xx? lança exceção, não segue com lixo

return $response->json();

Três métodos, três problemas resolvidos:

timeout(5) — se em 5 segundos não respondeu, o Laravel desiste e lança uma ConnectionException. Sua requisição não fica travada arrastando o app junto.
retry(3, 200) — falha de rede? Ele tenta de novo, até 3 vezes, com 200ms de intervalo. A instabilidade passageira some sozinha.
throw() — se depois de tudo a resposta for erro, ele lança exceção. Você trata de propósito, em vez de processar dado inválido silenciosamente.

Como usar na prática

Alguns ajustes que valem a pena conhecer:

// Separar timeout de conexão do timeout de resposta
Http::connectTimeout(3)->timeout(10)->get(/* ... */);

// Só relançar em erro de servidor, não em 404 esperado
$response->throwIf($response->serverError());

// Ou garantir que veio exatamente 200
$response->throwUnlessStatus(200);

connectTimeout é quanto você espera pra conectar (3s costuma bastar). timeout é o total até a resposta chegar. Separar os dois te dá controle fino: "conecta rápido, mas se conectou, dou mais um tempinho pra processar".

A pegadinha: retry cego pode cobrar o cartão duas vezes

Aqui mora o perigo que quase ninguém pensa. O retry é maravilhoso pra operações idempotentes — buscar uma cotação, consultar um CEP. Repetir não faz mal.

Mas e uma cobrança? Se a API processou o pagamento e a resposta se perdeu no caminho, o retry vai tentar de novo — e cobrar o cliente duas vezes. 😬

Pra esses casos, o retry aceita uma condição: só repete se for erro de conexão (a requisição nem chegou), nunca se o servidor já respondeu:

use Illuminate\Http\Client\ConnectionException;
use Illuminate\Http\Client\PendingRequest;

Http::retry(3, 200, function ($exception, PendingRequest $request) {
    // só tenta de novo se NEM CHEGOU no servidor
    return $exception instanceof ConnectionException;
})->post('https://gateway.com/charges', $dados);

A régua: repetir consulta, sempre. Repetir cobrança, só se tiver certeza de que nem chegou.

Bônus: e agora?

Trocar Guzzle na mão pelo Http:: do Laravel não é só sintaxe mais bonita. É timeout, retry, throw e — de brinde — a possibilidade de mockar tudo nos testes com Http::fake(), sem tocar na API real (isso rende um post inteiro à parte).

Se você tem uma integração externa crítica sem timeout, essa é sua lição de casa pra hoje. Uma API lenta lá fora não pode ser capaz de derrubar seu app aqui dentro.

Me conta: seu app já foi derrubado por uma API de terceiro? O que travou primeiro — a fila ou o FPM? 👀

N+1: o bug silencioso que trava seu Laravel em produção

Denis Augusto — Tue, 04 Aug 2026 22:56:06 +0000

Sua tela demora 8 segundos e o servidor não tem culpa

O cliente manda a mensagem: "o painel tá travando".

Você abre em produção. Conta os segundos. Um... dois... oito. A tela de listagem de pedidos, que tem 50 linhas, demora uma eternidade pra carregar.

Primeiro palpite: servidor fraco. Você já tá quase abrindo um chamado pra subir o plano da VPS.

Segura o dedo. Na esmagadora maioria das vezes, não é o servidor. É o N+1 query — o bug mais silencioso e mais comum do Eloquent. Ele não quebra nada, não estoura erro, não aparece no log. Só deixa tudo lento e finge que a culpa é de outro.

O código parece inofensivo (e é aí que mora o problema)

Olha esse trecho. Aposto que tem um igualzinho no seu projeto agora:

$pedidos = Pedido::all(); // 1 query pra buscar os pedidos

foreach ($pedidos as $pedido) {
    // e aqui... +1 query POR pedido, toda vez que você toca no cliente
    echo $pedido->cliente->nome;
}

Bonito, limpo, legível. E secretamente fazendo o banco chorar.

Cada vez que o loop acessa $pedido->cliente, o Eloquent dispara uma nova consulta pra buscar aquele cliente. São 50 pedidos? 1 query dos pedidos + 50 dos clientes = 51 queries numa tela só.

Agora imagina uma listagem com 500 registros e três relações (cliente, produtos, endereço). O número explode. Já vi tela abrir o Debugbar e mostrar mais de 3.000 queries. Cada uma custa alguns milissegundos de ida e volta ao banco. Some tudo: sua tela de 8 segundos.

Por que "N+1"? O nome entrega o problema

É matemática simples e meio cruel.

1 query pra buscar a lista principal (os N pedidos).
N queries extras, uma pra cada item, quando você acessa a relação dentro do loop.

Total: N + 1. Quanto mais dados, pior fica — e o ambiente de dev, com 5 registros de teste, nunca te avisa. O bug só acorda em produção, com dado de verdade. Traiçoeiro.

A solução cabe em uma palavra: `with()`

Aqui vem o $pedido->restore() dessa história. Uma linha e você vira o herói do dia:

// Eager loading: já traz os clientes junto, de uma vez
$pedidos = Pedido::with('cliente')->get();

foreach ($pedidos as $pedido) {
    echo $pedido->cliente->nome; // já tá na memória, ZERO query nova
}

O que mudou? Em vez de buscar cliente por cliente dentro do loop (lazy loading), o with() faz o Eloquent buscar todos os clientes de uma vez só, com um WHERE IN, antes do loop começar. Isso é eager loading — "carregamento adiantado".

De 51 queries pra 2. Sempre 2, tanto faz se são 50 ou 5.000 pedidos. A tela de 8 segundos vira 200 milissegundos.

Não mexeu no servidor. Não instalou nada. Uma palavra.

Como usar na prática

O with() é mais flexível do que parece:

// Várias relações de uma vez
Pedido::with(['cliente', 'itens'])->get();

// Relação aninhada: o item e o produto de cada item
Pedido::with('itens.produto')->get();

// Já filtrou a query? Carrega depois, na collection que você já tem
$pedidos = Pedido::all();
$pedidos->load('cliente'); // mesmo efeito, pra collection pronta

// Só quer a CONTAGEM, não os dados? withCount é seu amigo
Pedido::withCount('itens')->get(); // vira a coluna itens_count

with() você usa na query. load() quando a collection já foi buscada. withCount() quando só precisa do número, sem carregar os registros.

A pegadinha: eager loading não é "coloca em tudo"

Antes de sair jogando with() em toda query, cuidado com o outro extremo.

Se você carrega uma relação que não vai usar naquela tela, tá trazendo dados à toa — gastando memória e banda pra nada. O with('itens.produto.fornecedor.endereco') que ninguém lê é tão ruim quanto o N+1.

A régua é simples: carregue o que você vai acessar no loop. Nada além disso.

E tem a confusão clássica: with() não é a mesma coisa que has() ou whereHas(). O with() traz a relação junto. O whereHas() filtra pela existência dela. Um carrega, o outro filtra. Já vi muita gente usar um esperando o comportamento do outro.

Bônus: faça o Laravel gritar quando você esquecer

O melhor jeito de nunca mais deixar um N+1 passar é pedir pro próprio Laravel te avisar. No AppServiceProvider:

use Illuminate\Database\Eloquent\Model;

public function boot(): void
{
    // Em dev, estoura exceção sempre que uma relação
    // for carregada de forma lazy (o gatilho do N+1)
    Model::preventLazyLoading(! app()->isProduction());
}

Agora, se você esquecer um with(), o Laravel lança uma exceção na sua cara em desenvolvimento — muito antes de virar tela travada em produção. Deixa ligado só fora de produção pra não derrubar o app do cliente por um esquecimento.

Antes de você fechar a aba

O N+1 é aquele bug que a gente escreve sem perceber e só descobre quando alguém reclama. A boa notícia: achar e matar é fácil quando você sabe o que procurar.

Abre o Laravel Debugbar (ou o Telescope) numa tela lenta do seu projeto e olha a contagem de queries. Achou uma listagem com dezenas ou centenas? É N+1 quase na certa. Um with() e você resolve.

Me conta nos comentários: qual foi a tela mais absurda de queries que você já pegou? Aposto que tem gente com número maior que 3.000. 👀

Seu código dispara um Event e você não faz ideia do que acontece depois

Denis Augusto — Thu, 30 Jul 2026 03:10:57 +0000

"De onde saiu esse e-mail?"

O cliente abre um chamado: está recebendo dois e-mails de confirmação toda vez que faz um pedido.

Você abre o PedidoController. Não tem Mail:: ali. Abre a Action. Nada. Segue o rastro e chega numa linha inocente:

PedidoConfirmado::dispatch($pedido);

E agora? Quem escuta isso? Você dá um Ctrl+Shift+F em PedidoConfirmado e aparecem seis arquivos. Dois deles mandam e-mail.

Meia hora de investigação pra uma linha de código que, na teoria, deixava tudo mais organizado.

Já passou por isso?

O que Event resolve de verdade

Antes de bater no coitado: Event é ótimo. O problema é o uso, não a ferramenta.

Olha esse controller, que é o cenário que motiva todo mundo a usar Event:

public function store(CriarPedidoRequest $request)
{
    $pedido = $this->criarPedido->execute($request->validated());

    Mail::to($pedido->cliente)->send(new PedidoConfirmado($pedido));
    $this->estoque->baixar($pedido->itens);
    $this->slack->avisarVendas($pedido);
    $this->analytics->registrarConversao($pedido);
    ActivityLog::registrar('pedido.criado', $pedido);

    return redirect()->route('pedidos.show', $pedido);
}

Toda vez que o negócio quer mais uma coisinha quando um pedido é criado, você volta aqui e adiciona uma linha. Um ano depois o controller tem quatorze responsabilidades e cinco dependências que não têm nada a ver com "criar pedido".

Com Event, vira isso:

public function store(CriarPedidoRequest $request)
{
    $pedido = $this->criarPedido->execute($request->validated());

    PedidoConfirmado::dispatch($pedido);

    return redirect()->route('pedidos.show', $pedido);
}

O código que cria pedido não precisa saber que existe Slack. Você adiciona um listener novo sem tocar em nada que já funciona. Isso é desacoplamento de verdade.

E o que ele cobra em troca

Só que tem uma conta chegando junto: você trocou legibilidade por flexibilidade.

Na versão de cima, você lê o controller e sabe exatamente tudo que acontece. Na versão de baixo, você lê o controller e sabe... que algo acontece. Em algum lugar. Talvez.

O fluxo virou invisível. E código invisível é código que dá medo de mexer.

Tem um segundo custo: erro em listener vira erro no request. Se o listener não estiver na fila, ele roda no mesmo processo, e uma exceção lá dentro estoura na cara do usuário — depois do pedido já ter sido criado. O desacoplamento é só de código, não de execução.

A regra que eu uso pra decidir

É uma pergunta só:

Isso é parte da operação, ou é uma consequência dela?

Se a operação está errada sem aquele passo, é parte dela. Chamada direta.

Se a operação está completa e correta mesmo que aquele passo falhe, é consequência. Event.

Aplicando no exemplo:

Baixar estoque → parte da operação. Pedido com estoque não baixado é bug de negócio. Vai direto no código, dentro da mesma transaction.
E-mail, Slack, analytics, log de atividade → consequência. O pedido continua válido se o Slack estiver fora. Event.

Repara que "baixar estoque" saiu do Event. Muita gente joga tudo pra lá porque parece mais limpo, e aí descobre em produção que um listener falhou silenciosamente e o estoque ficou errado por três dias.

Regra curta: Event é pra efeito colateral, não pra regra de negócio.

Fazendo direito

O listener fica em app/Listeners, e desde o Laravel 11 você nem precisa registrar nada — o framework descobre sozinho pelo type-hint do handle():

namespace App\Listeners;

use App\Events\PedidoConfirmado;
use Illuminate\Contracts\Queue\ShouldQueue;

class EnviarEmailDeConfirmacao implements ShouldQueue
{
    public function handle(PedidoConfirmado $event): void
    {
        Mail::to($event->pedido->cliente)
            ->send(new ConfirmacaoDePedido($event->pedido));
    }
}

Aquele implements ShouldQueue não é detalhe. Ele resolve o segundo custo que falei: o listener vai pra fila, o request devolve na hora, e se o e-mail falhar isso não derruba o pedido. Efeito colateral quase sempre quer ser um listener enfileirado.

E o nome do evento importa muito. Evento é fato consumado, no passado: PedidoConfirmado, UsuarioRegistrou, PagamentoRecusado. Se você escreveu EnviarEmailDePedido, isso não é um evento — é um comando com fantasia. Comando você chama direto.

A pegadinha do Ctrl+Shift+F

Lembra do problema lá do começo, de não saber quem escuta o quê? Tem comando pra isso:

php artisan event:list

Ele lista todos os eventos e seus listeners. Deixa esse comando no bolso — é a primeira coisa a rodar quando alguém pergunta "de onde saiu esse e-mail?".

Duas outras armadilhas que valem o aviso:

Dispatch dentro de transaction. Se o listener está na fila e você despacha o evento antes do commit, o worker pode buscar um registro que ainda não existe. Usa ShouldHandleEventsAfterCommit no listener e dorme tranquilo.

Model events como atalho. Aquele static::created() no boot() da model dispara em seed, em factory de teste, em import em massa. Você vai mandar e-mail de boas-vindas pros 5 mil usuários de um import. Já vi acontecer. 💀

Bônus: um Event, muitos ouvidos

O momento em que Event realmente brilha é quando o mesmo fato interessa a áreas diferentes do sistema que não deveriam se conhecer.

PagamentoAprovado pode liberar o acesso, disparar a nota fiscal, notificar o suporte e alimentar o dashboard — quatro listeners, quatro contextos, zero acoplamento entre eles. Adicionar o quinto não mexe em nenhum dos outros.

Se o seu evento tem um listener só e nunca vai ter outro, você provavelmente só escreveu uma chamada de função com três arquivos a mais.

Antes de você fechar a aba

Da próxima vez que for criar um Event, faz a pergunta: parte da operação ou consequência dela?

E se a resposta for "sei lá", começa com chamada direta. É bem mais fácil transformar código explícito em Event depois do que caçar um fluxo invisível às onze da noite.

Você é time "dispara Event pra tudo" ou time "só quando precisa mesmo"? Conta aí nos comentários — e se você já perdeu meia hora caçando quem mandou um e-mail, sabe exatamente do que eu tô falando.

Seu code review não precisa discutir espaçamento

Denis Augusto — Wed, 29 Jul 2026 21:38:32 +0000

O pull request com 14 comentários (13 são sobre vírgula)

Você abre o PR do colega. Quarenta arquivos alterados, uma feature importante.

E os comentários são esses:

"faltou linha em branco antes do return"

"acho que aqui cabia trailing comma"

"aspas simples, né? o resto do projeto usa simples"

"esse import não tá sendo usado"

Enquanto isso, no meio do diff, tem um método recebendo ?User e chamando $user->email sem checar null. Ninguém viu. Todo mundo estava ocupado contando espaço.

Esse é o custo real da falta de automação: não é o tempo gasto com detalhe, é a atenção que sobra pra revisar o que importa.

E tem o lado humano. Ninguém gosta de receber cinco comentários sobre estilo. Cria atrito onde não precisa ter.

Três ferramentas resolvem isso. Trinta minutos de setup.

1. Pint — o fim da discussão sobre estilo

O Pint já vem instalado em projetos Laravel novos. Se o seu é antigo:

composer require laravel/pint --dev

E roda:

./vendor/bin/pint

Pronto. Ele formata o projeto inteiro seguindo o padrão Laravel. Aspas, espaçamento, ordem de import, trailing comma — tudo resolvido sem ninguém opinar.

Se quiser ajustar alguma coisa, cria um pint.json na raiz:

{
    "preset": "laravel",
    "rules": {
        "declare_strict_types": true,
        "ordered_imports": { "sort_algorithm": "alpha" }
    }
}

Dois flags que valem ouro no dia a dia:

./vendor/bin/pint --dirty   # só o que você mexeu (rápido)
./vendor/bin/pint --test    # não muda nada, só falha se estiver fora do padrão

O --test é o que vai pro CI.

Aviso importante: rode o Pint no projeto inteiro em um commit isolado, sozinho, antes de tudo. Se você misturar formatação com mudança de lógica, o diff fica ilegível e o git blame vira sopa.

2. Larastan — o bug que aparece antes do deploy

Aqui o jogo muda de nível. O Larastan (PHPStan com esteroides de Laravel) lê seu código sem executar e aponta erro de tipo, método que não existe, variável possivelmente nula.

composer require --dev "larastan/larastan:^3.0"

Cria o phpstan.neon na raiz:

includes:
    - vendor/larastan/larastan/extension.neon

parameters:
    paths:
        - app/
        - routes/

    level: 5

E roda:

./vendor/bin/phpstan analyse

Na primeira execução ele vai encontrar coisa. Muita coisa. Não entra em pânico e nem tenta corrigir tudo hoje.

Comece no nível 0 ou 1. Sério. Zera os erros nesse nível, sobe pro próximo, zera de novo. Um nível por sprint é um ritmo saudável. Level 5 já pega a maioria dos problemas de verdade; do 6 pra cima começa a exigir docblock em tudo.

E se o projeto for grande demais pra começar do zero, tem a saída elegante:

./vendor/bin/phpstan analyse --generate-baseline

Ele guarda todos os erros atuais num arquivo e passa a ignorá-los. A partir de agora, código novo não pode introduzir erro novo. A dívida antiga fica lá, congelada, e você paga aos poucos.

O que ele pega e o code review não pega:

// Larastan: "Cannot call method email() on User|null"
$user = User::find($id);
Mail::to($user->email)->send(...);   // 💥 em produção quando não achar

// Larastan: "Call to an undefined method App\Models\Pedido::pagos()"
Pedido::pagos()->get();   // você renomeou o scope e esqueceu daqui

Esse segundo é ouro puro em refatoração.

3. Rector — refatoração automática

O Rector reescreve código pra você. É o que você usa quando sobe de versão do PHP ou do Laravel e não quer varrer 800 arquivos na mão.

composer require rector/rector --dev

rector.php na raiz:

<?php

use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withPaths([
        __DIR__ . '/app',
        __DIR__ . '/tests',
    ])
    ->withPhpSets()                        // moderniza pra sua versão do PHP
    ->withPreparedSets(deadCode: true)     // remove código morto
    ->withComposerBased(laravel: true);    // regras específicas de Laravel

Sempre rode em dry-run primeiro:

./vendor/bin/rector --dry-run   # mostra o que faria
./vendor/bin/rector             # aplica

O que ele faz sozinho: converte construtor antigo pra property promotion, troca array() por [], transforma if/else em operador ternário quando cabe, adiciona tipo de retorno, remove use não usado, atualiza chamadas descontinuadas do Laravel.

Uma tarde de Rector num projeto legado economiza semanas. Só faz duas coisas: tenha testes e commit separado — igual ao Pint.

Colocando pra rodar sozinho

De nada adianta se depender de alguém lembrar. Dois lugares:

No CI, um job que não deixa passar:

  qualidade:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.4'
      - run: composer install --prefer-dist --no-interaction
      - run: ./vendor/bin/pint --test
      - run: ./vendor/bin/phpstan analyse --error-format=github

Repara que o Rector não está aí. Ele é ferramenta de refatoração pontual, não de validação contínua — deixa ele fora do CI, você roda quando precisa.

No pre-commit, pra você nem ver o erro chegar:

# .git/hooks/pre-commit
#!/bin/sh
./vendor/bin/pint --dirty
git add $(git diff --name-only --cached | grep '\.php$')

Formata só o que mudou e já adiciona ao commit. Você nunca mais commita código fora do padrão — e nem percebe que isso aconteceu.

A pegadinha: ferramenta não substitui revisão

Vale deixar claro, porque tem gente que liga tudo isso e acha que resolveu code review.

Não resolveu. Pint, Larastan e Rector não sabem se o nome da sua classe faz sentido, se a regra de negócio está certa, se aquela query vai derrubar o banco com 100 mil registros ou se você acabou de criar uma falha de autorização.

Eles só limpam o ruído pra que a revisão humana sobre pro que só humano faz. Que é justamente o que você quer.

Bônus: um comando pra tudo

Coloca no composer.json e a vida fica mais fácil:

"scripts": {
    "qa": [
        "./vendor/bin/pint",
        "./vendor/bin/phpstan analyse",
        "php artisan test"
    ]
}

Agora é composer qa antes de abrir qualquer PR. ✅

Antes de você fechar a aba

O objetivo não é ter código perfeito. É parar de gastar energia humana com coisa que máquina resolve.

Se você tiver tempo pra só uma hoje, instala o Pint. São dois comandos e o retorno é imediato — na próxima revisão, ninguém mais vai comentar sobre vírgula.

Seu projeto já usa alguma dessas? E qual foi o erro mais bizarro que o PHPStan achou pra você? Conta nos comentários — os melhores são sempre naquele arquivo que "funcionava bem há três anos".

Seu usuário não deveria esperar o e-mail ser enviado

Denis Augusto — Mon, 27 Jul 2026 18:05:53 +0000

Quatro segundos olhando um spinner

O usuário preenche o cadastro, clica em "Criar conta" e... espera. Um. Dois. Três. Quatro segundos com o botão em loading.

Do lado de cá, o INSERT no banco levou 12 milissegundos. O resto foi o servidor de e-mail respondendo com a pressa de quem não tem pressa. Depois teve a chamada pro CRM. E o PDF de boas-vindas sendo gerado.

O usuário não sabe de nada disso. Ele só sabe que o site é lento. E se a conexão cair no meio, ele clica de novo — e agora você tem dois cadastros.

A pergunta que resolve isso é bem simples: o usuário realmente precisa esperar por isso?

Na esmagadora maioria das vezes, não.

O problema na prática

Esse controller aqui provavelmente existe no seu projeto com outro nome:

public function store(CriarContaRequest $request)
{
    $user = User::create($request->validated());

    // 2s (se o SMTP estiver de bom humor)
    Mail::to($user)->send(new BoasVindas($user));

    // 1,5s e depende de uma API que não é sua
    $this->crm->sincronizar($user);

    // mais 1s, e ninguém vai abrir esse PDF hoje
    $this->gerarPdfDeBoasVindas($user);

    return redirect()->route('dashboard');
}

Quatro operações. Só a primeira é urgente.

E tem um detalhe pior que a lentidão: se o CRM estiver fora do ar, o cadastro inteiro explode. O usuário toma um erro 500 numa conta que já foi criada no banco. Você acabou de acoplar o sucesso do seu cadastro à disponibilidade de um sistema de terceiro.

O conceito: agora ou depois?

Fila é uma lista de tarefas que ficam guardadas em algum lugar (banco, Redis, SQS) esperando um processo separado — o worker — pegar e executar.

A regra pra decidir o que vai pra fila é quase sempre essa: se o usuário não precisa ver o resultado na tela seguinte, pode ir pra fila.

E-mail, notificação, sincronização com sistema externo, geração de relatório, redimensionamento de imagem, webhook — tudo isso é "depois". Criar o registro que a próxima tela vai mostrar é "agora".

A solução: um job por tarefa

php artisan make:job EnviarEmailDeBoasVindas

namespace App\Jobs;

use App\Models\User;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;

class EnviarEmailDeBoasVindas implements ShouldQueue
{
    use Queueable;

    // tenta 3 vezes antes de desistir
    public int $tries = 3;

    // espera 10s, depois 30s, depois 60s entre as tentativas
    public array $backoff = [10, 30, 60];

    public function __construct(public User $user) {}

    public function handle(): void
    {
        Mail::to($this->user)->send(new BoasVindas($this->user));
    }
}

O implements ShouldQueue é a chave. Sem ele, o job roda na hora, igual antes.

E o controller volta a ser rápido:

public function store(CriarContaRequest $request)
{
    $user = User::create($request->validated());

    EnviarEmailDeBoasVindas::dispatch($user);
    SincronizarComCrm::dispatch($user);
    GerarPdfDeBoasVindas::dispatch($user);

    return redirect()->route('dashboard');
}

Três dispatch custam alguns milissegundos — é só um INSERT na tabela de jobs. O usuário cai no dashboard quase instantaneamente, e o trabalho pesado acontece por trás.

Melhor ainda: se o CRM estiver fora, só aquele job falha. O cadastro seguiu firme.

Colocando pra rodar

Pra começar, o driver database resolve bem (você troca por Redis quando o volume pedir). No .env:

QUEUE_CONNECTION=database

A tabela de jobs já vem na migration padrão do Laravel. Se seu projeto for antigo e não tiver:

php artisan make:queue-table
php artisan migrate

E aí você sobe o worker:

php artisan queue:work

Em produção esse comando precisa de alguém tomando conta dele — Supervisor, systemd, ou o Horizon se você usa Redis. Worker que morre e ninguém reinicia é fila que enche em silêncio.

As pegadinhas (todas custam caro pelo menos uma vez)

1. Job não guarda o objeto, guarda o ID. O trait Queueable serializa só a chave primária do model e busca no banco de novo na hora de executar. Isso é ótimo — o dado nunca fica velho — mas tem um efeito colateral: se o registro for deletado entre o dispatch e a execução, o job estoura ModelNotFoundException. Por isso o padrão é passar o model, não um array com os dados: você ganha o dado fresco de graça.

2. Deploy sem queue:restart não muda nada. O worker carrega seu código na memória quando sobe e fica lá rodando. Corrigiu um bug no job, subiu pra produção, e continua com o comportamento antigo? É isso. Coloca no final do seu script de deploy:

php artisan queue:restart

Todo mundo passa por essa. Uma vez.

3. Job falhou e ninguém viu. Depois de esgotar as tentativas, o job vai pra tabela failed_jobs e some da sua vida. Se você nunca olha essa tabela, e-mail nenhum foi enviado e você não sabe. Trate a falha:

public function failed(\Throwable $e): void
{
    Log::error("Falha ao enviar boas-vindas pro user {$this->user->id}", [
        'erro' => $e->getMessage(),
    ]);
}

Se a tabela não existir no seu projeto: php artisan make:queue-failed-table. Pra reprocessar tudo depois de corrigir: php artisan queue:retry all.

4. Dispatch dentro de transaction. Se você despacha o job antes do commit, o worker pode ser rápido demais e ir buscar um registro que ainda não existe. O afterCommit() resolve:

EnviarEmailDeBoasVindas::dispatch($user)->afterCommit();

Ou você liga 'after_commit' => true na conexão dentro de config/queue.php e esquece o assunto.

Bônus: e se eu não quiser manter um worker?

Nem todo projeto tem infra pra Supervisor rodando. Pra esses casos, o Laravel 12 trouxe duas conexões que ajudam bastante:

RegistrarAcesso::dispatch($user)->onConnection('deferred');

A deferred executa o job no mesmo processo, mas depois que a resposta HTTP já foi enviada pro navegador. A background dispara um processo PHP separado. Nos dois casos o usuário não espera — e você não precisa de worker nenhum.

Não substitui uma fila de verdade (não tem retry robusto, não tem monitoramento, não aguenta volume), mas pra um projeto pequeno que só quer tirar o e-mail do caminho do request, é uma mão na roda.

Antes de você fechar a aba

Abre o controller mais lento do seu projeto e lê linha por linha se perguntando: "o usuário precisa ver isso na próxima tela?".

Cada "não" é um dispatch esperando pra acontecer. E provavelmente uns 2 segundos a menos no botão. ⚡

E você, já tomou a do deploy sem queue:restart ou ainda tem esse prazer pela frente? Conta nos comentários — e se seu projeto tem failed_jobs acumulando poeira, essa é a hora de dar uma olhada lá.

O if de permissão que você copiou pra 12 controllers

Denis Augusto — Mon, 27 Jul 2026 17:39:58 +0000

Ctrl+C, Ctrl+V, e mais uma vez

Toda aplicação Laravel tem essa linha. Geralmente várias cópias dela:

if ($post->user_id !== auth()->id()) {
    abort(403);
}

Ela nasce inocente, no update() do controller. Aí você precisa da mesma checagem no destroy(). Copia. Depois no edit(). Copia. Aí o Blade precisa esconder o botão "Editar" de quem não pode. Copia de novo, agora em outro formato.

Quando você percebe, a regra "quem pode mexer nesse post" está espalhada em oito, dez, doze lugares. Nenhum deles sabe da existência dos outros.

E aí chega a segunda-feira em que o cliente pede: "admin também precisa poder editar qualquer post". Você já sentiu o frio na barriga? Porque agora você precisa achar todas as cópias. E vai esquecer uma. Sempre esquece uma.

O problema não é o if, é o endereço dele

Olha o controller depois de umas três rodadas de "só mais uma regrinha":

public function update(Request $request, Post $post)
{
    if ($post->user_id !== auth()->id() && ! auth()->user()->isAdmin()) {
        abort(403);
    }

    if ($post->publicado_em && $post->publicado_em->diffInHours(now()) > 24) {
        abort(403, 'Posts publicados há mais de 24h não podem ser editados.');
    }

    $post->update($request->validated());

    return back();
}

Metade do método é autorização. E essa mesma metade precisa existir, idêntica, no destroy(), no edit() e na view.

Repara no que aconteceu: uma regra de negócio de verdade — "quem, e em que condições, pode alterar um post" — virou detalhe de implementação de um método HTTP. Ela não tem casa própria. Mora de favor em todo canto.

O conceito: autorização merece um endereço

Policy é uma classe que concentra as regras de autorização de um model. Um arquivo, um assunto: "o que cada usuário pode fazer com um Post".

O controller volta a fazer o que deveria: receber requisição, chamar o serviço, devolver resposta. E quando o cliente mudar de ideia sobre quem pode editar o quê, você abre um arquivo.

A solução: cria a policy e esquece o if

php artisan make:policy PostPolicy --model=Post

O --model já gera o esqueleto com os métodos padrão (viewAny, view, create, update, delete...). Preenche o que interessa:

namespace App\Policies;

use App\Models\Post;
use App\Models\User;

class PostPolicy
{
    public function update(User $user, Post $post): bool
    {
        if ($user->isAdmin()) {
            return true;
        }

        if ($post->user_id !== $user->id) {
            return false;
        }

        // autor só edita nas primeiras 24h após publicar
        return ! $post->publicado_em
            || $post->publicado_em->diffInHours(now()) <= 24;
    }

    public function delete(User $user, Post $post): bool
    {
        return $user->isAdmin() || $post->user_id === $user->id;
    }
}

Não precisa registrar nada: o Laravel descobre a policy sozinho pela convenção de nomes (Post → PostPolicy). Se sua estrutura de pastas fugir do padrão, aí sim você registra manualmente com Gate::policy(Post::class, PostPolicy::class) no AppServiceProvider.

E o controller emagrece:

public function update(Request $request, Post $post)
{
    Gate::authorize('update', $post);

    $post->update($request->validated());

    return back();
}

Uma linha. Se não puder, o Laravel lança AuthorizationException e devolve 403 sem você escrever nada.

Como usar na prática

No Blade, pra esconder o botão de quem não pode clicar:

@can('update', $post)
    <a href="{{ route('posts.edit', $post) }}">Editar</a>
@endcan

Mesma regra, mesmo arquivo. Zero chance de a view discordar do controller.

Na rota, com o middleware can, quando o controller inteiro depende da permissão:

Route::put('/posts/{post}', [PostController::class, 'update'])
    ->middleware('can:update,post');

Em qualquer lugar do código, com o próprio usuário:

if ($user->can('delete', $post)) {
    // ...
}

Funciona em Job, em Livewire, em comando de console. A regra é uma só, e todo mundo pergunta pra ela.

As pegadinhas (essas pegam todo mundo)

1. O $this->authorize() não existe mais por padrão. Do Laravel 11 pra frente, o controller base do skeleton não traz mais o trait AuthorizesRequests. Se você seguiu um tutorial antigo e tomou "Call to undefined method", é isso. Ou usa Gate::authorize('update', $post), ou adiciona o trait no seu controller base:

use Illuminate\Foundation\Auth\Access\AuthorizesRequests;

abstract class Controller
{
    use AuthorizesRequests;
}

2. Métodos sem model precisam do nome da classe. create e viewAny não recebem instância — afinal, o post ainda não existe. Então você passa a classe:

Gate::authorize('create', Post::class);

Esquecer disso e passar $post num create é campeão de confusão.

3. O before() é poderoso demais. Dá pra liberar geral pro admin de uma vez:

public function before(User $user, string $ability): ?bool
{
    return $user->isAdmin() ? true : null;
}

Só que atenção no retorno: true autoriza, false nega tudo e nem chama o resto da policy, e null deixa o fluxo continuar. Retornar false sem querer no before() derruba a policy inteira — e é um bug bem chato de achar, porque tudo simplesmente vira 403.

4. Visitante deslogado nem chega na policy. Por padrão o Laravel nega antes de executar o método. Se um post público pode ser visto por qualquer um, tipe o parâmetro como opcional:

public function view(?User $user, Post $post): bool
{
    return $post->publicado_em !== null || $user?->id === $post->user_id;
}

Bônus: mensagem de erro que ajuda

Retornar false dá um 403 genérico. Às vezes você quer explicar o motivo:

use Illuminate\Auth\Access\Response;

public function update(User $user, Post $post): Response
{
    return $post->user_id === $user->id
        ? Response::allow()
        : Response::deny('Você só pode editar seus próprios posts.');
}

A mensagem chega no front, e o usuário para de abrir chamado perguntando por que o botão não funciona.

Antes de você fechar a aba

Dá um grep por abort(403) no seu projeto agora. Cada resultado é uma regra de negócio morando no lugar errado, esperando o dia em que vai divergir das outras cópias.

A boa notícia: migrar é rápido. Cria a policy, move o if pra lá, e vai trocando os controllers um por um. Dá pra fazer em partes, sem parar o projeto.

E aí, seu projeto tem policy ou tá no esquema if copiado? Conta nos comentários — e se você já caiu na do before() retornando false, quero muito saber quanto tempo levou pra descobrir. 😄

Seu array associativo vai te trair (e vai ser em produção)

Denis Augusto — Mon, 27 Jul 2026 17:35:00 +0000

O array que ninguém sabe o que tem dentro

Você abre um Service depois de três meses sem mexer. A assinatura do método é essa aqui:

public function handle(array $data): User

E aí? O que vai dentro desse $data? Tem nome ou name? O enviar_boas_vindas é booleano ou a string "1" que veio do formulário? Tem telefone ou aquilo era opcional?

A resposta honesta é: ninguém sabe. Pra descobrir, você lê o corpo do método inteiro, abre o Form Request, e ainda dá um dd($data) só pra ter certeza. Toda vez.

E o pior nem é isso. O pior é que no dia em que alguém escrever $data['name'] em vez de $data['nome'], o PHP não vai gritar em lugar nenhum útil. Vai gritar em produção, num log que você só vê depois que o cliente reclama.

O problema na prática

Olha esse fluxo bem comum — Form Request valida, controller repassa, service usa:

// Controller
public function store(CriarUsuarioRequest $request)
{
    $user = $this->service->handle($request->validated());

    return redirect()->route('usuarios.show', $user);
}

// Service — boa sorte adivinhando o que tem aqui dentro
public function handle(array $data): User
{
    $user = User::create([
        'name'  => $data['nome'],
        'email' => $data['email'],
    ]);

    // esse aqui vem como string "0" do form... ou não vem nunca. Depende.
    if ($data['enviar_boas_vindas']) {
        Mail::to($user)->send(new BoasVindas($user));
    }

    return $user;
}

Repara nos problemas empilhados:

O $data['enviar_boas_vindas'] estoura um Undefined array key se o campo não veio marcado no formulário — porque checkbox desmarcado simplesmente não é enviado. E se vier a string "0", o if considera falso, mas "false" seria verdadeiro. Divirta-se.

Sua IDE não te ajuda em nada. Zero autocomplete, zero aviso. O array é uma caixa preta que aceita qualquer coisa e só reclama quando o código já rodou.

O conceito: dar um nome e uma forma pros dados

DTO é Data Transfer Object. Nome pomposo pra uma ideia bem simples: em vez de carregar dados soltos num array, você cria uma classe que descreve exatamente quais campos existem e de que tipo cada um é.

Só isso. Não tem lógica de negócio, não fala com banco, não é model. É um envelope tipado que atravessa as camadas do seu sistema.

A vantagem é que o contrato para de morar na sua cabeça e passa a morar no código. E o PHP vira seu revisor de código de graça.

A solução: uma classe boba que resolve tudo

Com PHP 8 e readonly, um DTO cabe em poucas linhas:

final class CriarUsuarioData
{
    public function __construct(
        public readonly string $nome,
        public readonly string $email,
        public readonly bool $enviarBoasVindas = true,
        public readonly ?string $telefone = null,
    ) {}

    public static function fromRequest(CriarUsuarioRequest $request): self
    {
        return new self(
            nome: $request->validated('nome'),
            email: $request->validated('email'),
            // boolean() resolve "1", "on", "true", ausente... tudo
            enviarBoasVindas: $request->boolean('enviar_boas_vindas'),
            telefone: $request->validated('telefone'),
        );
    }
}

Agora o service fica assim:

public function handle(CriarUsuarioData $data): User
{
    $user = User::create([
        'name'  => $data->nome,
        'email' => $data->email,
    ]);

    if ($data->enviarBoasVindas) {
        Mail::to($user)->send(new BoasVindas($user));
    }

    return $user;
}

E o controller vira uma linha honesta:

$user = $this->service->handle(CriarUsuarioData::fromRequest($request));

O que mudou de verdade: se você digitar $data->nomee, a IDE marca em vermelho antes de você salvar. Se esquecer de passar o e-mail, o PHP reclama na hora de construir o objeto, não três camadas depois. E o readonly garante que ninguém vai alterar o dado no meio do caminho e te deixar sem entender de onde veio aquele valor.

Como usar na prática

Na fronteira do sistema. O DTO nasce onde o dado externo entra — Form Request, comando de console, payload de webhook — e daí pra dentro tudo trafega tipado. Um fromRequest(), um fromArray(), um fromWebhook(), cada um sabendo traduzir seu formato de origem.

Em Jobs, que agradecem muito. Job recebe array e você descobre o problema quando o worker já engoliu a fila? Com DTO, o construtor tipado é uma barreira antes do dispatch:

ProcessarPedido::dispatch(new PedidoData(
    pedidoId: $pedido->id,
    valorTotal: $pedido->total,
));

Na saída também. Integração com API externa devolvendo um JSON gigante e imprevisível? Converte pra DTO logo na resposta. Se o fornecedor mudar um campo, você quebra num lugar só — no fromResponse() — em vez de em oito arquivos espalhados.

A pegadinha: DTO não é model, e nem sempre vale

Aqui vem o cuidado, porque tem quem descubra DTO e saia criando um pra cada método do projeto.

DTO não substitui o Eloquent Model. Model representa uma linha do banco com comportamento; DTO representa dados em trânsito. Se você criou um UserData que é uma cópia exata da tabela users, provavelmente você só reescreveu o model com mais trabalho.

DTO não guarda regra de negócio. Sem método salvar(), sem calcularDesconto() dentro dele. No momento em que ele começa a decidir coisas, virou service disfarçado.

E DTO não faz validação. Quem valida é o Form Request. O DTO assume que o dado já chegou limpo e só garante o formato daí pra frente.

A régua que uso: se o dado atravessa mais de uma camada, ou se você já se pegou perguntando "o que vem nesse array?", vale o DTO. Pra um $request->only('email') que morre no controller, não vale.

Bônus: e quando o DTO tem 15 campos?

Escrever fromRequest() na mão fica chato rápido quando o formulário é grande. É exatamente aí que entra o spatie/laravel-data, que faz o mapeamento automático, integra com validação, serializa pra JSON e ainda funciona com collections tipadas.

Mas comece na mão. Escreve dois ou três DTOs com readonly puro, sente o que muda no seu dia a dia, e só depois traga o pacote. Assim você usa a ferramenta entendendo o problema que ela resolve — em vez de instalar mais uma dependência por hype.

Antes de você fechar a aba

Faz um teste rápido: abre seu projeto e procura por array $data nas assinaturas de método. Quantos você achou? Agora escolhe o mais bagunçado e tenta lembrar, sem abrir o Form Request, o que exatamente vai dentro dele.

Se você travou, achou seu primeiro DTO. 🎯

E aí, você já usa DTO ou ainda tá no time do array associativo com fé? Conta nos comentários — e se conhece alguém que vive dando dd($data) pra descobrir o que chegou, marca a pessoa lá.

Validação condicional no Laravel sem virar espaguete de if

Denis Augusto — Wed, 22 Jul 2026 14:48:34 +0000

"Esse campo aqui só é obrigatório às vezes"

Toda regra de validação começa simples. required, email, min:8, beleza. Aí o PO chega e solta a frase mágica:

"Ah, mas o CNPJ só é obrigatório se a pessoa for pessoa jurídica."

E lá se foi a simplicidade. De repente sua validação depende de outro campo, e você faz o que todo mundo faz na primeira vez: joga um if no controller, valida um pedaço, depois valida outro pedaço, e o método store() vira um monstro de ramificação.

Já passou por isso? A boa notícia é que o Laravel tem ferramenta pra praticamente todo tipo de "depende". Você só precisa parar de resolver tudo na mão.

O problema: validação picada no controller

O jeito ingênuo é validar em pedaços, dependendo do que veio:

public function store(Request $request)
{
    $regras = [
        'tipo' => 'required|in:pf,pj',
        'nome' => 'required|string',
    ];

    // e aqui começa a bagunça
    if ($request->tipo === 'pj') {
        $regras['cnpj'] = 'required|string|size:14';
    } else {
        $regras['cpf'] = 'required|string|size:11';
    }

    if ($request->quer_newsletter) {
        $regras['email'] = 'required|email';
    }

    $request->validate($regras);

    // ...
}

Funciona? Funciona. Mas repara no que aconteceu: sua regra de negócio agora tá espalhada em construção manual de array, o controller sabe demais sobre validação, e testar isso é um inferno. Cada if novo é mais uma ramificação pra dar errado.

A solução 1: `required_if` e amigos

Pra dependências simples entre campos, o Laravel já tem regras prontas. Você quase nunca precisa de if pra isso:

public function rules(): array
{
    return [
        'tipo' => 'required|in:pf,pj',
        'cnpj' => 'required_if:tipo,pj|nullable|size:14',
        'cpf'  => 'required_if:tipo,pf|nullable|size:11',
        'email' => 'required_if:quer_newsletter,true|email',
    ];
}

Tem uma família inteira dessas: required_unless, required_with, required_without, required_with_all, exclude_if, prohibited_if... Antes de escrever um if, vale conferir se já não existe uma regra que faz exatamente o que você quer. Na maioria dos casos, existe.

A solução 2: `Rule::when` pra condição no meio da regra

Quando a condição não é "um campo depende de outro", mas sim algo do contexto (o usuário logado, um plano, uma feature flag), o Rule::when deixa a coisa declarativa dentro do próprio array:

use Illuminate\Validation\Rule;

public function rules(): array
{
    return [
        'titulo' => 'required|string',
        // só valida como obrigatório+único se for admin
        'slug' => Rule::when(
            $this->user()->isAdmin(),
            ['required', 'unique:posts,slug'],
            ['nullable'] // senão, opcional
        ),
    ];
}

Leu de cima pra baixo e entendeu a regra inteira, sem sair caçando um if três métodos acima.

A solução 3: `sometimes()` pra lógica que não cabe no array

E quando a condição é complexa de verdade, tipo "valida o desconto só se ele veio E o pedido passa de 500 reais"? Aí entra o método sometimes() do Validator, ideal no withValidator() de um Form Request:

use Illuminate\Validation\Validator;

public function withValidator(Validator $validator): void
{
    $validator->sometimes('desconto', 'numeric|max:50', function ($input) {
        return $input->cupom && $input->total > 500;
    });
}

A regra do desconto só é aplicada se aquele closure retornar true. Toda a lógica maluca fica isolada num lugar só, com nome, testável, e longe do caminho principal.

Como usar na prática

Validação de array/coleção — aquele formulário com N itens repetidos (um carrinho, uma lista de convidados). Usa o .*:

public function rules(): array
{
    return [
        'itens' => 'required|array|min:1',
        'itens.*.produto_id' => 'required|exists:produtos,id',
        'itens.*.quantidade' => 'required|integer|min:1',
    ];
}

Uma regra só valida os N itens do array. Nada de foreach validando na mão.

Mensagem customizada por condição — combina com messages() no Form Request pra falar a língua do usuário: "Informe o CNPJ para pessoa jurídica" em vez do genérico.

A pegadinha: `nullable` vs a ausência da regra

Aqui cai muita gente. Quando você usa required_if, quase sempre precisa combinar com nullable no mesmo campo. Sem isso, se o campo vier vazio (mas presente no request), outras regras como size:14 ou email ainda vão tentar validar a string vazia e reclamar.

// ❌ se vier cnpj='' num PF, o size:14 reclama
'cnpj' => 'required_if:tipo,pj|size:14',

// ✅ vazio é permitido quando não obrigatório
'cnpj' => 'required_if:tipo,pj|nullable|size:14',

nullable diz "pode ser nulo/vazio, e nesse caso ignora as outras regras". É o par natural do required_if. Guarda isso que economiza uma hora de debug.

Bônus: e agora?

Abre o Form Request (ou controller) mais cheio de if do seu projeto e faz o exercício: cada if que existe só pra montar array de regra provavelmente tem um required_if, Rule::when ou sometimes equivalente esperando pra substituir ele.

E se você ainda valida direto no controller com $request->validate(), esse é o empurrãozinho pra migrar tudo pra um Form Request. Todo esse arsenal fica muito mais organizado lá dentro.

Antes de você fechar a aba

A regra de ouro: se você tá construindo array de validação com if, o Laravel provavelmente já tem uma forma declarativa de fazer isso. Vale abrir a doc de validação e passar o olho na lista de regras — tem umas 20 que quase ninguém usa e resolvem casos que a gente insiste em fazer na mão.

Qual regra de validação condicional você mais usa? Ou tem algum caso cabeludo que não soube resolver? Joga nos comentários que a gente destrincha junto. 👇

Early return: o jeito de matar aquele if aninhado que ninguém lê

Denis Augusto — Wed, 22 Jul 2026 14:40:07 +0000

Seu código tem forma de seta e ninguém quer admitir

Você já abriu um método, olhou pro lado direito da tela e viu aquilo? A indentação vai crescendo, crescendo, o código forma uma seta apontando pro canto, e lá no fundo, uns cinco níveis pra dentro, mora a linha que realmente importa.

A gente até tem nome carinhoso pra isso: arrow code (código seta). Ou, pros mais dramáticos, "a pirâmide da perdição".

O pior é que quase sempre esse método começou pequeno. Um if inocente. Aí veio uma validação, mais um caso, uma exceção pra tratar... e quando você percebe, precisa rolar o olho por seis linhas de fechamento de chave } só pra descobrir a qual if cada uma pertence.

O problema na prática

Olha esse método de processar um pedido. Parece inofensivo, mas repara na indentação:

public function processar(Order $order)
{
    if ($order->isPago()) {
        if ($order->itens->isNotEmpty()) {
            if ($order->cliente->estaAtivo()) {
                if (! $order->foiEnviado()) {
                    // finalmente, o código de verdade
                    $this->enviar($order);
                    return true;
                } else {
                    return false;
                }
            } else {
                return false;
            }
        } else {
            return false;
        }
    }

    return false;
}

Pra chegar na única linha que interessa ($this->enviar($order)), seu olho precisou atravessar quatro if e ainda torcer pra não confundir qual else fecha qual bloco. E se amanhã aparecer mais uma regra? Mais um nível pra dentro. A seta cresce.

Esse código não é difícil porque o problema é difícil. Ele é difícil porque tá escrito de trás pra frente.

O conceito: verifica o que dá errado primeiro

Early return (ou "cláusula de guarda", guard clause) é a ideia de tratar os casos de saída logo no começo do método e sair fora na hora. Em vez de aninhar o "caminho feliz" lá no fundo de um monte de if, você inverte a lógica:

"Não tá pago? Cai fora. Sem itens? Cai fora. Cliente inativo? Cai fora. Passou por tudo? Então executa."

O caminho feliz fica no nível principal do método, sem indentação nenhuma. As exceções ficam no topo, cada uma resolvida e esquecida. Você lê de cima pra baixo, uma condição de cada vez, sem precisar segurar nada na cabeça.

A solução: mesmo método, agora legível

public function processar(Order $order): bool
{
    if (! $order->isPago()) {
        return false;
    }

    if ($order->itens->isEmpty()) {
        return false;
    }

    if (! $order->cliente->estaAtivo()) {
        return false;
    }

    if ($order->foiEnviado()) {
        return false;
    }

    // o caminho feliz, no nível principal, sem seta nenhuma
    $this->enviar($order);

    return true;
}

Zero else. Zero aninhamento. Cada if é uma pergunta simples: "tem algum motivo pra parar aqui?". Se tiver, para. Se chegou no fim, é porque passou por todos os filtros e agora pode fazer o trabalho de verdade com a consciência tranquila.

E o de bônus: adicionar uma regra nova amanhã é colar mais um bloco de guarda no meio. Não mexe na estrutura, não empurra nada pra dentro.

Como usar na prática

Lançando exceção em vez de retornar — funciona igualzinho, e é ótimo em Services e Actions:

public function reembolsar(Order $order): void
{
    if (! $order->isPago()) {
        throw new OrderException('Não dá pra reembolsar um pedido não pago.');
    }

    if ($order->foiReembolsado()) {
        throw new OrderException('Esse pedido já foi reembolsado.');
    }

    $this->gateway->refund($order);
}

Saindo cedo dentro de um loop com continue — mesma filosofia, evita o if gigante envolvendo o corpo inteiro:

foreach ($usuarios as $usuario) {
    if ($usuario->optOut) {
        continue; // pula esse e segue
    }

    $this->notificar($usuario);
}

No Blade também, com @continue e @break, pra não aninhar a view inteira num @if.

A pegadinha: não é "return em todo canto"

Aqui vem o aviso, porque tem sempre alguém que lê isso e sai espalhando return no meio de qualquer função só pra parecer moderno.

Early return brilha quando as saídas são cláusulas de guarda de verdade: validações, pré-condições, casos de borda que impedem o fluxo principal. Aí ele reduz complexidade.

O que ele não é: desculpa pra ter dez return espalhados no meio da lógica principal, cada um saindo de um lugar diferente, sem ninguém entender por onde o método realmente termina. Isso não é early return, é fuga.

A régua é simples: os return de guarda ficam agrupados no topo, tratando o que dá errado. O return do caminho feliz fica sozinho no fim. Se seus returns estão espalhados feito confete no meio do código, você trocou um problema por outro.

Bônus: e agora?

Abre o arquivo com o método mais bagunçado do seu projeto — você já sabe qual é. Conta quantos níveis de indentação ele tem. Passou de dois ou três? Provavelmente dá pra inverter os if do topo em cláusulas de guarda e achatar aquilo em cinco minutos.

Uma dica: comece pelos else. Todo else que existe só pra retornar algo é um forte candidato a virar um early return e sumir.

Antes de você fechar a aba

Legibilidade não é frescura de quem gosta de código bonito. É você economizando o tempo do seu eu do futuro (ou do coitado que vai dar manutenção depois) na hora de entender o que aquele método faz.

E você, é time "trata o erro primeiro e cai fora" ou ainda tem carinho pela pirâmide de if? Conta nos comentários — e se conhece alguém que ama um else aninhado, marca lá. 😅

"fix: ajustes": o commit que não ajuda ninguém (nem você)

Denis Augusto — Tue, 21 Jul 2026 10:24:20 +0000

Roda `git log --oneline` no seu projeto agora.

Vai. Roda mesmo.

Se apareceu uma sequência tipo ajustes, correção, wip, agora vai, ajustes 2, revert dos ajustes — bem-vindo ao clube. Todo mundo já escreveu essa novela.

O problema aparece três meses depois, quando você precisa entender por que aquela linha do OrderService está daquele jeito. Você roda um git blame, chega no commit e lê: "ajustes". Obrigado, eu do passado. Muito esclarecedor.

Histórico do Git não é burocracia. É a única documentação que envelhece junto com o código, porque está grudada nele. E ela custa 10 segundos a mais por commit pra ficar boa.

O problema: seu histórico não responde nenhuma pergunta

Olha esse log e tenta responder três coisas: o que entrou de novo? o que quebrou? dá pra fazer deploy?

a3f9c21 ajustes
7b2e881 correção do bug
0c41d7a wip
e91f3b2 mudanças solicitadas
5d8a04c agora vai

Não dá. E isso tem custo real:

Code review — o revisor não sabe se ajustes é refactor inofensivo ou mudança de regra de negócio
Release — alguém tem que reler o diff inteiro pra escrever o "o que mudou nessa versão"
Investigação de bug — git log --grep não serve pra nada quando tudo se chama a mesma coisa
Você mesmo, na segunda-feira — depois de um fim de semana, aquele wip não significa nada

O conceito: um prefixo, e só

Conventional Commits é uma convenção de mensagem tão simples que dá pra aprender no tempo de ler este parágrafo:

<tipo>(<escopo opcional>): <descrição>

Os tipos que você vai usar em 95% dos casos:

feat — funcionalidade nova
fix — correção de bug
refactor — mudou o código sem mudar comportamento
test — mexeu em teste
docs — mexeu em documentação
chore — tarefa de manutenção (dependência, config, build)
perf — melhoria de performance

Na prática, o mesmo histórico de antes vira isto:

a3f9c21 feat(checkout): aplica cupom de desconto no total
7b2e881 fix(auth): corrige redirect após login expirado
0c41d7a refactor(orders): extrai cálculo de frete para Action
e91f3b2 test(checkout): cobre cupom expirado e cupom inválido
5d8a04c chore(deps): atualiza laravel/framework para 11.9

Agora as três perguntas do começo se respondem só de bater o olho. E git log --oneline --grep "^feat" te dá a lista de tudo que entrou de novo desde a última tag. Sem esforço.

O escopo, o corpo e o `!`

O escopo entre parênteses é opcional, mas vale muito num projeto Laravel: checkout, auth, api, admin. É o "onde" da mudança, e permite filtrar por área.

Quando a mensagem de uma linha não conta a história toda, o corpo entra. Regra de ouro: o título diz o que, o corpo diz por quê.

fix(pedidos): usa transaction ao confirmar pedido

Sem a transaction, uma falha no gateway deixava o pedido como
confirmado e o estoque já debitado. Agora ou tudo entra ou nada entra.

Refs #412

Esse commit vale ouro no git blame daqui a um ano. O diff mostra o que mudou; ele explica por quê.

E tem o caso da mudança que quebra compatibilidade — sinalizada com ! antes dos dois-pontos:

feat(api)!: remove campo legacy_id do UserResource

Isso é um aviso gritante pra quem consome a sua API, e é o que separa uma release menor de uma release maior.

O CHANGELOG de graça

Aqui é onde o padrão deixa de ser organização e vira ferramenta.

Como a mensagem passa a ser legível por máquina, dá pra derivar a versão automaticamente, seguindo Semantic Versioning:

Só fix, chore, refactor → sobe o patch (1.2.3 → 1.2.4)
Tem feat no meio → sobe o minor (1.2.3 → 1.3.0)
Tem ! ou BREAKING CHANGE → sobe o major (1.2.3 → 2.0.0)

Ferramentas como o release-please ou o git-cliff leem o histórico, calculam a nova versão, geram o CHANGELOG.md agrupado por tipo e criam a tag. Num workflow do GitHub Actions, isso roda sozinho a cada merge na main.

Você não escreve release notes nunca mais. Elas são um subproduto de você ter escrito commits decentes.

Se quiser garantir o padrão no time, o commitlint rejeita mensagem fora do formato no hook commit-msg. Só uma dica: comece pela convenção combinada com o time e só depois automatize a validação. Ferramenta antes de acordo vira briga no PR.

Pegadinha: o prefixo não é mágico

Esse é o mal-entendido mais comum, e eu já vi acontecer:

fix: ajustes
feat: mudanças
chore: coisas

Parabéns, agora seu histórico é inútil e padronizado. 😅

O prefixo é a menor parte do valor. O que faz diferença é a descrição ser específica: fix(auth): corrige redirect após login expirado conta uma história. fix: ajustes não.

Duas outras convenções que ajudam:

Imperativo, sem "eu" — adiciona, corrige, remove. Completa a frase "esse commit ___ o quê?"
Commit atômico — uma mudança lógica por commit. Se você precisa de um "e" no meio da mensagem, provavelmente eram dois commits

E fica tranquilo: bagunçou na hora de escrever? git commit --amend conserta o último, e git rebase -i conserta o resto antes de virar PR.

Bônus: e agora?

Adota no próximo commit. Não precisa reescrever o passado nem convencer o time inteiro numa reunião — o histórico melhora a partir de hoje, e a diferença aparece sozinha no primeiro git log que alguém rodar.

Depois de um mês, roda isso e vê o que o seu projeto anda fazendo de verdade:

git log --oneline --since="1 month ago" | cut -d' ' -f2 | sort | uniq -c | sort -rn

Se chore e fix dominam e mal aparece feat, você acabou de descobrir algo importante sobre onde o seu tempo está indo.

Antes de você fechar a aba

Vai lá, roda o git log --oneline de novo e me conta nos comentários: qual é a pior mensagem de commit que você encontrou (bônus se for sua)? 😄

DEV Community: Denis Augusto

Você testou a API funcionando. E quando ela cair?

O caminho feliz sempre passa. O problema é o outro.

O teste que só conhece o dia bonito

O resgate: Http::fake() também simula desastre

Os três desastres que você precisa testar

A pegadinha: caminho de falha sem tratamento não "passa", ele engana

Antes de você fechar a aba

Seu teste bate na API de verdade? Um dia ela vai te trair

O teste quebrou. E não foi você.

O problema: seu teste não deveria conhecer a internet

A solução: Http::fake() intercepta tudo

Como usar na prática

Não basta simular: confirme que você mandou certo

Bônus: proíba requisições reais escaparem

Antes de você fechar a aba

A API de terceiro caiu e derrubou seu app junto

A API deles caiu. Por que o SEU app caiu junto?

O código que confia demais no mundo lá fora

A blindagem: timeout, retry e throw

Como usar na prática

A pegadinha: retry cego pode cobrar o cartão duas vezes

Bônus: e agora?

N+1: o bug silencioso que trava seu Laravel em produção

Sua tela demora 8 segundos e o servidor não tem culpa

O código parece inofensivo (e é aí que mora o problema)

Por que "N+1"? O nome entrega o problema

A solução cabe em uma palavra: with()

Como usar na prática

A pegadinha: eager loading não é "coloca em tudo"

Bônus: faça o Laravel gritar quando você esquecer

Antes de você fechar a aba

Seu código dispara um Event e você não faz ideia do que acontece depois

"De onde saiu esse e-mail?"

O que Event resolve de verdade

E o que ele cobra em troca

A regra que eu uso pra decidir

Fazendo direito

A pegadinha do Ctrl+Shift+F

Bônus: um Event, muitos ouvidos

Antes de você fechar a aba

Seu code review não precisa discutir espaçamento

O pull request com 14 comentários (13 são sobre vírgula)

1. Pint — o fim da discussão sobre estilo

2. Larastan — o bug que aparece antes do deploy

3. Rector — refatoração automática

Colocando pra rodar sozinho

A pegadinha: ferramenta não substitui revisão

Bônus: um comando pra tudo

Antes de você fechar a aba

Seu usuário não deveria esperar o e-mail ser enviado

Quatro segundos olhando um spinner

O problema na prática

O conceito: agora ou depois?

A solução: um job por tarefa

Colocando pra rodar

As pegadinhas (todas custam caro pelo menos uma vez)

Bônus: e se eu não quiser manter um worker?

Antes de você fechar a aba

O if de permissão que você copiou pra 12 controllers

Ctrl+C, Ctrl+V, e mais uma vez

O problema não é o if, é o endereço dele

O conceito: autorização merece um endereço

A solução: cria a policy e esquece o if

Como usar na prática

As pegadinhas (essas pegam todo mundo)

Bônus: mensagem de erro que ajuda

Antes de você fechar a aba

Seu array associativo vai te trair (e vai ser em produção)

O array que ninguém sabe o que tem dentro

O problema na prática

O conceito: dar um nome e uma forma pros dados

A solução: uma classe boba que resolve tudo

Como usar na prática

A pegadinha: DTO não é model, e nem sempre vale

Bônus: e quando o DTO tem 15 campos?

Antes de você fechar a aba

Validação condicional no Laravel sem virar espaguete de if

"Esse campo aqui só é obrigatório às vezes"

O problema: validação picada no controller

O resgate: `Http::fake()` também simula desastre

A solução: `Http::fake()` intercepta tudo

A blindagem: `timeout`, `retry` e `throw`

A solução cabe em uma palavra: `with()`

A solução 1: `required_if` e amigos

A solução 2: `Rule::when` pra condição no meio da regra

A solução 3: `sometimes()` pra lógica que não cabe no array

A pegadinha: `nullable` vs a ausência da regra

Roda `git log --oneline` no seu projeto agora.

O escopo, o corpo e o `!`