Você rodou composer update, viu só um número de patch subindo, e mandou para produção sem pensar duas vezes. Afinal, era 13.20 para 13.21, nada de major, nada de breaking change no papel. Minutos depois, a tela que redimensionava as imagens do seu app parou de responder com um erro de conflito de nome.
Foi mais ou menos assim que um relato recente da comunidade Laravel descreveu o problema, quase em tempo real: o app estava rodando bem, e de repente falhou com um conflito de nomes. A causa não estava no seu código. Estava numa novidade que o próprio framework passou a trazer de fábrica.
O que mudou no Laravel 13.20
A partir do Laravel 13.20, o framework passou a incluir suporte nativo a processamento de imagens. Isso veio com um Image facade próprio, uma configuração própria e um service provider próprio, tudo registrado por padrão.
Parece uma boa notícia, e em muitos casos é. O problema é que o nome Image já estava ocupado há anos na maioria dos projetos. O pacote intervention/image é praticamente sinônimo de manipulação de imagem em Laravel, e ele também registra um facade chamado Image.
Quando dois facades disputam o mesmo nome, o container resolve um só. Se o que ganha não é o que o seu código espera, você chama o método de sempre e recebe um erro ou um comportamento diferente do esperado.
Por que um patch conseguiu quebrar produção
Aqui está a parte que dói. Isso não chegou como uma versão major com aviso em vermelho no changelog. Chegou como um incremento de patch, aquele que a gente costuma tratar como seguro.
A introdução do processamento de imagem nativo veio no ciclo do 13.20 e seguiu evoluindo nos patches seguintes. O 13.21, por exemplo, adicionou formatos de saída como PNG, GIF, AVIF e BMP ao componente Image, além de colocar o facade Image na lista de aliases padrão da aplicação. Ou seja, o novo Image ficou cada vez mais presente por padrão.
Se o seu projeto dependia do intervention/image e você não fixou versões nem leu o diff, a colisão apareceu sozinha. O sintoma é um conflito de nome em runtime, geralmente logo após o deploy da atualização.
Como diagnosticar
Antes de sair mexendo, confirme que o conflito é esse mesmo. Três checagens rápidas resolvem a dúvida.
Primeiro, veja qual Image está registrado. Um comando do Artisan mostra o alias ativo:
php artisan tinker
>>> class_exists(\Image::class) ? get_class(app('image')) : 'sem binding image'Se o retorno apontar para uma classe do namespace Illuminate em vez de Intervention, o facade nativo do Laravel assumiu o nome.
Segundo, olhe suas dependências. Confirme que o intervention/image está mesmo instalado e em qual versão:
composer show intervention/imageTerceiro, veja o que subiu no update. O diff entre as duas versões do framework mostra exatamente o que mudou:
composer show laravel/framework | grep versions
git diff HEAD~1 composer.lock | grep laravel/frameworkCom essas três respostas você já sabe se está diante da colisão ou de outro problema.
A solução
Existem dois caminhos, e a escolha depende de você querer o Image novo do Laravel ou manter o do Intervention.
Se você quer continuar com o intervention/image
O contorno reportado pela comunidade é desabilitar o service provider de imagem do Laravel, para que ele não registre o facade concorrente. No bootstrap/providers.php ou na configuração de providers da sua aplicação, remova o provider nativo de imagem do carregamento automático.
A ideia é simples: se você não vai usar o processamento nativo, não deixe ele registrar um nome que já é seu. O intervention/image volta a responder por Image sem disputa.
Vale um cuidado. A forma exata de desabilitar depende de como o seu projeto declara os providers e de qual versão do Laravel você está. Antes de aplicar em produção, valide em staging e confirme o nome atual do provider no seu vendor, porque esse detalhe muda entre versões.
Se você quer usar o Image nativo
O caminho inverso também funciona. Segundo os relatos, a própria Intervention publicou um ajuste renomeando o seu facade e a sua configuração para evitar a colisão. Nesse cenário, você atualiza o pacote e passa a chamar o Intervention por um nome próprio, deixando Image livre para o Laravel.
Confirme a versão exata desse ajuste na documentação do pacote antes de assumir que o seu composer.json já cobre a correção. Fixar a versão que resolve o problema é mais seguro do que confiar num intervalo aberto.
Boas práticas para não passar por isso de novo
O conflito do Image é um caso específico, mas a lição é geral. Dependência que você não controla pode mudar embaixo dos seus pés, mesmo num patch.
Algumas defesas que valem para qualquer projeto:
- Fixe versões com intenção. Um intervalo como
^13.0aceita qualquer 13.x. Se um patch pode introduzir um símbolo novo no namespace global, você quer decidir quando adotar, não descobrir em produção. - Leia o diff antes de subir.
composer.lockversionado e um olhar no changelog custam poucos minutos e evitam o incidente inteiro. - Teste
composer updateem staging. Rodar a suíte depois de atualizar dependências não é paranoia, é o que separa um deploy tranquilo de um susto às onze da noite. - Escolha bibliotecas sabendo o que elas registram. Antes de adotar um pacote, entenda quais facades, aliases e providers ele traz. Essa mesma disciplina vale para qualquer decisão de dependência, como escolher entre bibliotecas que resolvem o mesmo problema de formas diferentes.
Se você já apanhou de confiar cego numa resposta externa, sabe que o custo de validar antes é sempre menor que o de corrigir depois. Esse raciocínio de validação defensiva aparece em integração de API e vale igual para dependência de biblioteca.
Limitações
Esse conflito só afeta você se o projeto usa intervention/image e está no Laravel 13.20 ou superior. Quem nunca instalou o Intervention não vai notar nada, porque o nome Image estava livre.
Também é importante ser honesto sobre o status. A issue oficial que rastreia o problema estava aberta e pedindo mais informações no momento desta pesquisa. Os contornos descritos aqui vêm de relatos de campo confiáveis, mas a versão exata da correção da Intervention e o nome atual do provider nativo devem ser confirmados na fonte antes de você aplicar, porque esses detalhes mudam a cada release.
Conclusão
O Image nativo do Laravel é uma adição útil, mas ele chegou ocupando um nome que meio ecossistema já usava, e chegou num patch. O aprendizado não é “desconfie do Laravel”. É “trate atualização de dependência como uma mudança de verdade, mesmo quando o número parece inofensivo”.
Quando adotar: use o Image nativo em projetos novos ou quando você puder migrar do Intervention com calma. Quando evitar: não deixe o provider nativo entrar sem querer num projeto que já depende do intervention/image, principalmente sem testar.
O próximo passo prático é abrir o seu composer.json agora e olhar como as suas dependências principais estão fixadas. Se estiver tudo em intervalo aberto, você está a um composer update de descobrir o próximo conflito em produção.
Perguntas frequentes
O conflito acontece em qual versão do Laravel?
A partir do Laravel 13.20, que introduziu o processamento de imagem nativo e o facade Image. Versões anteriores não têm esse facade e não colidem com o intervention/image.
Preciso remover o intervention/image para resolver?
Não necessariamente. Você pode manter o Intervention e desabilitar o service provider de imagem do Laravel, ou atualizar o Intervention para a versão que renomeou o próprio facade. A escolha depende de qual dos dois você quer usar como Image.
Como eu evito esse tipo de surpresa no futuro?
Fixe versões com intenção, versione o composer.lock, leia o diff antes de subir e rode a suíte de testes depois de cada composer update em staging. Um patch pode introduzir um símbolo novo no namespace, então trate atualização como mudança real.
Isso é bug do Laravel ou do intervention/image?
Não é exatamente um bug de nenhum dos dois. É uma colisão de nomes: dois pacotes registram um facade chamado Image. A issue oficial ainda estava em análise no momento desta pesquisa, e ambos os lados ofereceram formas de contornar.
