Conflito no Composer do Magento 2? Encontre o pacote que bloqueia a atualização em 9 checL

Um conflito no Composer do Magento 2 pode impedir a instalação de um módulo, a aplicação de um patch ou a atualização da plataforma. A mensagem costuma citar diversos pacotes e versões, mas o componente que aparece no fim do erro nem sempre é a causa inicial.

Antes de apagar o arquivo composer.lock, remover extensões ou executar uma atualização geral, preserve o estado atual do projeto. As nove checagens abaixo ajudam a descobrir qual requisito bloqueia a operação e a preparar uma correção que possa ser testada fora da produção.

Por que o Composer encontra conflitos no Magento 2?

O Composer precisa encontrar uma combinação de versões que atenda simultaneamente ao arquivo composer.json, ao conteúdo do composer.lock, aos requisitos de cada pacote e à versão do PHP utilizada durante a execução.

Um módulo pode exigir uma biblioteca mais nova enquanto outro restringe essa mesma biblioteca a uma linha antiga. Também é possível que o Magento pretendido exija outra versão de PHP, que um repositório privado não esteja acessível ou que o arquivo de bloqueio mantenha uma dependência em uma versão incompatível.

Por isso, o texto “your requirements could not be resolved to an installable set of packages” deve ser tratado como o início do diagnóstico, não como indicação para atualizar tudo.

Conflito no Composer do Magento 2: faça estas 9 checagens

1. Registre o comando e preserve os arquivos do projeto

Guarde o comando executado, a saída completa do terminal, a versão atual da loja e o objetivo da alteração. Trabalhe em uma branch própria e registre o estado de composer.json e composer.lock no controle de versão.

Não apague o composer.lock como primeira tentativa. Ele registra as versões efetivamente resolvidas para o projeto. Sua remoção permite que o Composer recalcule toda a árvore e pode introduzir mudanças muito maiores do que a atualização pretendida.

2. Confirme qual PHP está executando o Composer

O PHP da linha de comando pode ser diferente daquele utilizado pelo PHP-FPM no site. Verifique a versão e as extensões carregadas:

php -v
php --ini
php -m
composer --version

Se o erro mencionar php, ext-intl, ext-soap, ext-sodium ou outra extensão, confirme a configuração do ambiente antes de alterar dependências. A versão desejada da plataforma também precisa ser compatível com toda a infraestrutura. Para uma mudança de linha, consulte o checklist de requisitos do Adobe Commerce 2.4.9 e valide cada componente aplicável ao seu projeto.

3. Valide a estrutura do composer.json e do lock

Um erro de sintaxe, uma restrição malformada ou uma divergência entre os dois arquivos pode interromper a resolução. Execute:

composer validate

Leia avisos e erros separadamente. Nem todo aviso impede uma instalação, mas inconsistências no arquivo de bloqueio precisam ser compreendidas. Evite editar manualmente o hash ou as versões dentro do composer.lock.

4. Identifique quem exige o pacote incompatível

Quando a mensagem cita uma biblioteca específica, descubra quais pacotes dependem dela:

composer why nome-do-fornecedor/nome-do-pacote

O resultado mostra a relação de dependência instalada. Isso ajuda a distinguir um requisito direto do projeto de uma dependência transitiva, trazida por outro módulo. Se vários componentes exigirem o mesmo pacote, compare as faixas aceitas por cada um.

5. Pergunte ao Composer quem bloqueia a versão desejada

O comando prohibits, também disponível pelo alias why-not, costuma revelar o bloqueador com mais clareza:

composer prohibits fornecedor/pacote 2.0.0
composer why-not fornecedor/pacote 2.0.0

Substitua o nome e a versão pelo componente que pretende instalar. O bloqueio pode vir do pacote principal do Magento, de uma extensão, de uma biblioteca fixada no projeto ou da própria versão do PHP.

Repita a consulta para o pacote raiz que motivou a atualização. Em vez de tentar corrigir cada linha da mensagem, procure a primeira restrição que torna a combinação impossível.

6. Verifique se a dependência está fixada no composer.json

Abra o composer.json e revise as seções require, require-dev, conflict, replace e repositories. Uma versão exata, como 1.2.3, oferece menos margem de resolução que uma faixa compatível, mas não deve ser ampliada sem confirmar o suporte do módulo.

Também procure pacotes antigos que já foram removidos funcionalmente, mas continuam declarados. Não elimine uma dependência apenas porque ela parece obsoleta: primeiro confirme se algum módulo, patch ou processo de build ainda a utiliza.

7. Confira repositórios privados e metadados disponíveis

Falhas de autenticação ou repositórios inacessíveis podem fazer uma versão parecer inexistente. Revise a URL configurada, as permissões da credencial e a disponibilidade do pacote esperado. Não publique chaves de acesso em tickets, capturas de tela ou no repositório Git.

Para verificar as versões que o Composer consegue enxergar, use:

composer show fornecedor/pacote --all

Se uma versão documentada pelo fornecedor não aparecer, investigue o repositório e a autenticação antes de modificar restrições.

8. Simule uma atualização restrita fora da produção

Depois de identificar os pacotes envolvidos, simule a operação em desenvolvimento ou homologação:

composer update fornecedor/pacote --with-all-dependencies --dry-run

--with-all-dependencies permite recalcular dependências relacionadas, enquanto --dry-run apresenta a operação planejada sem efetivá-la. Ainda assim, revise cuidadosamente quais pacotes seriam instalados, atualizados ou removidos.

Evite executar composer update sem indicar pacotes em uma tentativa emergencial. Uma atualização ampla pode alterar toda a árvore permitida pelo composer.json, aumentando o escopo de testes e o risco de incompatibilidade.

9. Instale e valide o Magento em homologação

Com a solução aprovada, gere um novo composer.lock de forma controlada, registre a mudança e faça o deploy em um ambiente equivalente ao de produção. A validação deve incluir, no mínimo:

• frontend, painel administrativo e páginas de produto;
• login, carrinho, cálculo de frete e checkout;
• formas de pagamento e criação de pedidos;
• cron, filas, consumidores e integrações externas;
• compilação de dependências e conteúdo estático;
• indexadores, busca, cache e logs da aplicação.

Se indexadores ficarem inválidos após o deploy, investigue o processamento antes de iniciar várias reindexações completas. O roteiro sobre indexadores Magento 2 travados ajuda a separar uma atualização pendente de uma falha no cron, banco ou mecanismo de busca.

O que não fazer para corrigir o Composer

• Não edite arquivos dentro de vendor/: as alterações serão perdidas em uma nova instalação.
• Não ignore requisitos de plataforma sem análise: simular outra versão de PHP pode produzir um conjunto impossível de executar no servidor real.
• Não remova o lock automaticamente: isso amplia a resolução para dependências que não faziam parte da mudança.
• Não teste diretamente na loja ativa: falhas durante a instalação podem deixar autoload, código e conteúdo compilado inconsistentes.
• Não limpe evidências cedo demais: preserve a saída do Composer e o diff dos arquivos para comparar tentativas.

Se uma tentativa deixar a aplicação indisponível, não presuma que o problema esteja somente no cache. Servidor web, PHP-FPM e modo de manutenção também devem ser verificados, como explicado no diagnóstico de erro 503 no Magento 2.

Quando procurar suporte especializado?

Vale envolver uma equipe especializada quando o conflito combina atualização do Magento, PHP e extensões comerciais; quando o pacote bloqueador não pode ser atualizado; ou quando não existe um ambiente de homologação equivalente à produção.

A análise deve resultar em um plano reproduzível: estado inicial, dependência bloqueadora, mudança proposta, novo arquivo de lock, testes e procedimento de reversão. Se sua equipe precisa diagnosticar um conflito no Composer do Magento 2 sem ampliar o risco da atualização, entre em contato com o Suporte Magento para avaliar o projeto.

Perguntas frequentes

Posso apagar o composer.lock para resolver um conflito?

Não como primeira tentativa. A exclusão faz o Composer recalcular toda a árvore de dependências e pode atualizar componentes que não faziam parte da mudança. Identifique o bloqueador e execute uma atualização restrita.

Qual é a diferença entre composer install e composer update?

O composer install instala as versões registradas no composer.lock. O composer update resolve novamente as versões permitidas pelo composer.json e modifica o arquivo de bloqueio.

O que faz o comando composer why-not?

Ele mostra quais requisitos impedem a instalação de uma versão específica. É útil para localizar módulos, bibliotecas ou requisitos de PHP incompatíveis com o pacote desejado.

É seguro usar –ignore-platform-reqs no Magento?

Não como correção definitiva. A opção pode ocultar incompatibilidades de PHP ou extensões e gerar dependências que não funcionam no servidor real. O ambiente deve atender aos requisitos efetivos do projeto.