Erro do Composer no Magento 2: resolva conflitos sem quebrar a loja

Um erro do Composer no Magento 2 pode bloquear a instalação de módulos, a aplicação de patches ou todo o processo de atualização. Mensagens extensas sobre dependências, versões incompatíveis e pacotes bloqueados costumam incentivar tentativas arriscadas, como apagar o composer.lock ou executar uma atualização geral diretamente em produção.

O caminho seguro é descobrir qual pacote impõe a restrição, entender se o comando utilizado corresponde ao objetivo e testar a nova árvore de dependências antes do deploy. Este roteiro mostra como fazer isso sem transformar um conflito controlável em uma atualização inesperada de dezenas de componentes.

Primeiro: preserve o estado atual da instalação

Antes de executar novos comandos, registre a versão do código, a branch, o último commit implantado e o conteúdo atual dos arquivos composer.json e composer.lock. Se o projeto usa Git, verifique se existem alterações não commitadas:

git status
composer validate
composer diagnose

O composer validate ajuda a encontrar inconsistências no arquivo de configuração. Já o composer diagnose verifica aspectos gerais do ambiente do Composer. Eles não corrigem dependências automaticamente, mas fornecem contexto antes de qualquer mudança.

Também confirme as versões efetivamente usadas no terminal:

php -v
composer --version
php bin/magento --version

Execute os comandos com o usuário responsável pela aplicação. Alternar entre root, usuário de deploy e usuário do servidor web pode criar arquivos com permissões diferentes e gerar uma segunda falha depois que o conflito for resolvido.

Como interpretar um erro do Composer no Magento 2

A parte mais importante da mensagem costuma aparecer depois de expressões como requires, conflicts with, is locked to version ou but it does not match the constraint. Em vez de analisar apenas a última linha, procure três informações:

• Pacote solicitado: o componente que você tentou instalar ou atualizar.
• Restrição encontrada: a faixa de versões exigida por esse componente.
• Pacote bloqueador: a dependência já instalada que impede a resolução.

Para consultar as versões conhecidas e a instalada, use:

composer show nome-do-fornecedor/nome-do-pacote --all

Se você precisa saber por que determinada versão não pode ser instalada, execute:

composer prohibits nome-do-fornecedor/nome-do-pacote 1.2.3

O comando composer why-not é um alias comum para a mesma investigação. Substitua o pacote e a versão pelos valores envolvidos no seu caso. A saída geralmente revela qual módulo, metapacote ou biblioteca mantém a dependência em uma faixa incompatível.

Install e update não fazem a mesma coisa

Uma causa recorrente de incidentes é tratar composer install e composer update como comandos equivalentes.

• composer install instala as versões registradas no composer.lock. É normalmente o comportamento esperado em um deploy reproduzível.
• composer update recalcula dependências com base nas restrições do composer.json e altera o arquivo de lock.

Em produção, um composer update genérico pode modificar muito mais pacotes do que o componente que motivou a manutenção. A resolução deve ocorrer em ambiente de desenvolvimento ou homologação, com revisão do novo composer.lock. O servidor de produção recebe os arquivos aprovados e executa a instalação conforme esse lock.

7 causas frequentes de conflito de dependências

1. Módulo incompatível com a versão do Magento

Uma extensão pode exigir uma edição ou linha diferente da plataforma. Confira as restrições declaradas no pacote e valide a compatibilidade diretamente com o fornecedor, sem presumir que a instalação bem-sucedida em outra loja garante o funcionamento no seu projeto.

2. Versão do PHP fora da faixa aceita

O Composer resolve dependências usando a versão do PHP executada no terminal e as configurações do projeto. O PHP da linha de comando pode ser diferente daquele utilizado pelo PHP-FPM. Compare os dois ambientes antes de alterar restrições.

3. Pacote bloqueado pelo composer.lock

A mensagem pode informar que um componente está travado em determinada versão porque foi realizada uma atualização parcial. Nesse caso, avalie a atualização conjunta das dependências relacionadas, em vez de apagar o lock.

4. Atualização sem dependências associadas

Quando a mudança de um pacote exige versões diferentes de componentes relacionados, uma atualização restrita demais não consegue montar a árvore. Após identificar o conjunto necessário, o parâmetro --with-all-dependencies, abreviado como -W, pode permitir o ajuste das dependências relacionadas:

composer update fornecedor/pacote -W

Use essa opção somente em uma branch de manutenção e revise tudo o que foi alterado no lock.

5. Repositório privado ou credencial ausente

Erros de autenticação, pacote inexistente ou falha de download nem sempre são conflitos de versão. Confirme a configuração dos repositórios e das credenciais sem imprimir segredos em logs compartilhados. Não versione arquivos que contenham tokens ou chaves privadas.

6. Restrição adicionada manualmente ao composer.json

Uma edição incorreta pode criar faixas incompatíveis ou substituir configurações necessárias. Compare o arquivo com o histórico do Git e prefira comandos composer require apropriados à edição manual sem validação.

7. Metapacote e módulos fora de sincronia

Em uma atualização da plataforma, alterar somente um componente central pode deixar módulos e bibliotecas em versões incompatíveis. Planeje o conjunto completo e revise também requisitos de infraestrutura. Se o objetivo for atualizar a plataforma, consulte o checklist sobre mudanças REST e GraphQL antes do upgrade e os cuidados relacionados à compatibilidade entre Magento e banco de dados.

Por que não apagar o composer.lock como primeira tentativa?

O composer.lock registra as versões exatas aprovadas para o projeto. Ao removê-lo, o Composer volta a resolver toda a árvore dentro das restrições disponíveis. Isso pode trocar bibliotecas, módulos e dependências transitivas que não faziam parte da manutenção.

Apagar o arquivo também dificulta reproduzir o estado anterior e comparar exatamente o que mudou. Se houver suspeita de corrupção ou inconsistência, preserve uma cópia, investigue o histórico e recrie o lock somente como uma decisão controlada, nunca como tentativa automática.

Procedimento seguro para corrigir e testar

1. Crie uma branch específica e garanta que o repositório esteja limpo.
2. Reproduza o erro fora da produção e salve a saída completa do Composer.
3. Use composer show, prohibits e why para identificar a cadeia de dependências.
4. Confirme a compatibilidade do módulo, PHP, Magento e serviços associados.
5. Atualize apenas o conjunto necessário e revise o diff de composer.json e composer.lock.
6. Execute composer install a partir de um ambiente limpo para verificar se o resultado é reproduzível.
7. Rode os procedimentos da aplicação e teste Admin, catálogo, carrinho, checkout, pagamentos, integrações e tarefas agendadas.

Se a mudança estiver ligada a uma correção de segurança, trate o Composer como uma etapa do deploy, não como todo o processo. O planejamento usado para aplicar patches sem interromper o checkout também ajuda a organizar homologação, rollback e validação comercial.

O que fazer se o erro acontecer durante o deploy?

Não prossiga com metade das dependências instaladas. Interrompa o deploy, preserve os logs e verifique se o release anterior continua íntegro. Em estruturas baseadas em releases, o rollback deve apontar para um diretório completo e já validado, em vez de tentar consertar manualmente a pasta parcialmente atualizada.

Depois da instalação bem-sucedida, confirme permissões, compilação, conteúdo estático, caches e estado dos serviços. Uma conclusão sem erros no Composer não garante que módulos, schema do banco e código gerado estejam prontos para receber tráfego.

Conclusão: corrija a dependência, não apenas a mensagem

Um erro do Composer no Magento 2 deve ser tratado como um problema de compatibilidade e reprodutibilidade. Preserve o lock, identifique o pacote bloqueador, limite o alcance da atualização e valide o resultado em um ambiente equivalente ao de produção.

Se o conflito envolver muitos módulos, uma atualização de plataforma ou uma loja já indisponível, evite tentativas sucessivas no servidor principal. A equipe do Suporte Magento pode analisar as dependências, preparar o plano de correção e acompanhar um deploy controlado.

Perguntas frequentes

Posso apagar o composer.lock para resolver um conflito?

Não como primeira tentativa. A remoção recalcula toda a árvore de dependências e pode atualizar pacotes que não faziam parte da manutenção. Preserve o arquivo e identifique primeiro qual restrição causa o bloqueio.

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

O install utiliza as versões exatas registradas no lock. O update recalcula as dependências permitidas pelo composer.json e modifica o lock, por isso deve ser executado e revisado antes do deploy.

O que faz o parâmetro -W do Composer?

O -W, ou --with-all-dependencies, permite atualizar dependências relacionadas ao pacote solicitado. Ele pode resolver bloqueios legítimos, mas também amplia as alterações e exige revisão do composer.lock.

Por que o Composer aponta uma versão errada do PHP?

O PHP usado pelo terminal pode ser diferente do PHP-FPM que atende a loja. Também pode existir uma configuração de plataforma no composer.json. Verifique ambos antes de mudar requisitos.