Módulos Magento em conflito: como identificar a causa raiz e resolver sem derrubar a loja em produção

Sintomas de conflito entre módulos

Conflitos entre módulos no Magento 2 se manifestam de formas variadas. Os cenários mais comuns que encontro em diagnósticos são:

• White Screen of Death (WSOD) — página em branco, sem mensagem de erro visível, geralmente causada por um erro fatal PHP que foi suprimido pelo modo de produção
• Exceções no system.log — erros de classe não encontrada, interface não implementada, plugin conflitando com observer
• Layout quebrado após deploy — CSS ou JS de um módulo sobrescrevendo estilos de outro, ou template sendo sobrescrito de forma incorreta
• Funcionalidade específica parando de funcionar — checkout travado, preços incorretos, filtros de layered navigation retornando zero resultados

Passo 1: Ativar o modo de desenvolvedor

O modo de produção suprime mensagens de erro para não expor informações técnicas ao visitante. O primeiro passo do diagnóstico é mudar para o modo de desenvolvedor — em um ambiente de staging ou clone, nunca em produção ativa.

php bin/magento deploy:mode:set developer

Com o modo de desenvolvedor ativo, erros PHP são exibidos diretamente na página, e o Magento gera arquivos de cache e assets a cada request (sem necessidade de limpar cache a cada mudança). Isso torna o ciclo de diagnóstico muito mais rápido.

Passo 2: Analisar os logs do sistema

Os logs são a fonte primária de informação sobre conflitos de módulo. Os arquivos principais estão em var/log/:

• system.log — erros gerais, exceções de módulos, erros de configuração
• exception.log — stack traces completos de todas as exceções não tratadas
• debug.log — informações detalhadas quando ativado explicitamente

tail -f var/log/system.log | grep -i "error\|exception\|warning"

Procure por referências a namespaces de módulos específicos no stack trace. O nome do módulo costuma aparecer no caminho da classe — ex: Vendor\ModuleName\Model\Something.

Passo 3: Executar di:compile para identificar conflitos de injeção

O principal mecanismo de conflito entre módulos no Magento 2 é a injeção de dependência (DI). Quando dois módulos tentam modificar a mesma classe de formas incompatíveis (preference vs. plugin vs. observer), o di:compile vai falhar com uma mensagem clara.

php bin/magento setup:di:compile 2>&1 | tee /tmp/di_compile.log

Erros de di:compile geralmente são do tipo:

• Class X does not exist — um módulo referencia uma classe que não existe (módulo dependente não instalado ou versão incompatível)
• Interface Y is not implemented — um plugin ou preference não implementa corretamente a interface
• Plugin class Z must not be abstract — conflito de herança entre plugins

Passo 4: Isolar o módulo problemático

Identificado um módulo suspeito pelo log ou pelo di:compile, o passo seguinte é desabilitá-lo temporariamente para confirmar o diagnóstico:

php bin/magento module:disable Vendor_ModuleName
php bin/magento setup:upgrade
php bin/magento cache:flush

Se o problema desaparece após desabilitar o módulo, você confirmou a causa raiz. Agora você tem três opções: remover o módulo, encontrar uma versão compatível, ou desenvolver uma correção para o conflito.

Conflitos de preference e plugins — o caso mais complexo

O caso mais difícil de resolver é quando dois módulos definem preference para a mesma classe core do Magento. Como o DI do Magento suporta apenas uma preference ativa por classe, a última registrada no arquivo di.xml vence — e a outra é silenciosamente ignorada.

A solução mais elegante é criar um terceiro módulo de compatibilidade que estende a preference do módulo A e aplica as modificações do módulo B, garantindo que ambas as funcionalidades convivam sem conflito. Essa abordagem requer entendimento profundo de ambos os módulos.