Módulo PrestaShop que deixou de funcionar depois de uma atualização

Quatro famílias de causas, não uma

Um módulo PrestaShop deixa de funcionar depois de uma atualização e o sintoma varia: um bloco desapareceu do front-office, uma página de administração devolve um erro, ou o site inteiro vai abaixo. Por trás destes sintomas está quase sempre uma destas quatro causas: um hook perdido, um override em conflito, uma dependência retirada do core ou uma cache que ficou incoerente.

Identificar primeiro a família certa poupa horas.

Causa 1: o hook já não está registado

Sintoma: o módulo está ativo, a configuração está intacta, mas o conteúdo já não aparece.

Os nomes dos hooks foram evoluindo ao longo das versões. Os nomes antigos, como hookHeader, passaram a hookDisplayHeader, e alguns pontos de ligação desapareceram. Um módulo antigo continua a instalar-se, mas deixa de aparecer.

Verifique o estado real na base de dados:

SELECT h.name AS hook, m.name AS module, hm.position
FROM ps_hook_module hm
JOIN ps_hook h ON h.id_hook = hm.id_hook
JOIN ps_module m ON m.id_module = hm.id_module
WHERE m.name = 'nom_du_module';

Se o hook esperado não estiver lá, volte a registá-lo no separador Posições do back-office, ou reinstale o módulo — depois de confirmar que a desinstalação não apaga os dados dele.

Veja também a ps_hook_module_exceptions: uma exceção acrescentada para esconder um bloco numa página específica acaba por vezes por escondê-lo em todo o lado.

Existe o caso inverso: um módulo que se volta a registar sozinho num hook a seguir a cada atualização, porque o seu método de instalação é executado outra vez. Nesse caso é o módulo que tem de ser corrigido, não a base de dados.

Causa 2: um override em conflito

Sintoma: erro fatal a apontar uma classe já declarada, ou comportamento incoerente de uma funcionalidade do core.

O PrestaShop só permite um override por classe. Dois módulos que personalizem a Cart ou a Product entram em colisão, e o segundo ganha em silêncio.

O ficheiro a conhecer é o var/cache/prod/class_index.php. Contém a tabela de correspondência entre cada classe e o ficheiro que a implementa. Enquanto não for regenerado, um override acrescentado ou retirado não é tido em conta, o que produz erros fatais incompreensíveis.

O reflexo depois de qualquer alteração em override/:

rm -f var/cache/prod/class_index.php
rm -rf var/cache/prod/*

Para testar se a culpa é de um override, mude temporariamente o nome da pasta override/ para override_off/ e recarregue. Se o site voltar, isolou a família de causas.

Causa 3: uma dependência retirada do core

É a causa dominante desde o PrestaShop 9 e a mais brutal: erro fatal imediato numa classe que não é encontrada.

O PrestaShop 9 retirou várias bibliotecas históricas:

• o Swift Mailer, substituído pelo Symfony Mailer;
• o Guzzle, substituído pelo Symfony HTTP Client;
• o League Tactician, substituído pelo Symfony Messenger;
• o sensio/framework-extra-bundle, eliminado, pelo que as anotações de rota e de template deixam de funcionar.

Qualquer módulo que declare use GuzzleHttp\Client; ou use League\Tactician\...; produz um erro fatal logo ao ser carregado.

Identifique os módulos afetados ainda antes de migrar:

grep -rl "GuzzleHttp\|League\\\\Tactician\|Swift_Mailer" modules/

Além disso, o FrameworkBundleAdminController foi descontinuado a favor do PrestaShopAdminController, e os controladores de administração passam a ter de ser declarados como serviços, com injeção de dependências. Um módulo cujo controlador de back-office devolve um erro 500 depois da passagem para a 9 cai quase sempre neste ponto.

Por fim, a autenticação do back-office ficou totalmente assente no Symfony: os módulos de início de sessão único ou de autenticação de dois fatores que dependiam do cookie histórico deixam de funcionar.

Causa 4: uma cache que ficou incoerente

Sintoma: comportamento errático, que muda de página para página ou desaparece em navegação privada.

Depois de qualquer atualização, limpe por esta ordem:

rm -rf var/cache/prod/* var/cache/dev/*

Depois, em Parâmetros avançados > Desempenho, desative temporariamente as opções de combinação e de compressão dos ficheiros, limpe a cache do Smarty e recarregue. Estas opções agrupam os ficheiros JavaScript e partem com regularidade os módulos que carregam os seus scripts de forma assíncrona.

Confirme também as permissões em var/: uma cache que não pode ser reescrita produz sintomas aleatórios muito difíceis de interpretar.

O método de reposição em serviço

1. Ativar o modo debug, criando o ficheiro config/defines_custom.inc.php com define('_PS_MODE_DEV_', true); em vez de alterar o ficheiro do core. Assim, a sua definição sobrevive à próxima atualização.
2. Ler os registos em var/logs/ e no registo de erros do PHP do alojamento. O nome da classe em falta ou do serviço que não é encontrado identifica o módulo culpado.
3. Desativar o módulo suspeito na base de dados, sem passar pelo back-office, que pode estar inacessível:

UPDATE ps_module SET active = 0 WHERE name = 'nom_du_module';

4. Limpar a cache, confirmar que o site volta e depois tratar do assunto como deve ser: atualização do módulo junto do editor, ou correção do código.
5. Desativar o modo debug antes de reabrir ao público.

Evitar o próximo episódio

A regra que mais tempo poupa: nunca atualizar diretamente em produção. Um ambiente de pré-produção, um plano de testes escrito que cubra o processo de compra, os pagamentos, os e-mails e as transportadoras, e um inventário de módulos atualizado chegam para transformar uma avaria num não-acontecimento.

Para os módulos desenvolvidos à medida, as nossas regras de desenvolvimento de um módulo personalizado explicam o que torna um módulo resistente às atualizações.

Há um módulo a bloquear a sua loja?

Repomos em serviço os módulos partidos e corrigimos o código quando o editor já não acompanha. Veja o desenvolvimento de módulos PrestaShop.