Update Assistant bloqueado: reparar uma atualização do PrestaShop 9

Uma atualização falhada deixa a loja num estado instável

O Update Assistant do PrestaShop é uma excelente ferramenta quando tudo corre bem. Quando para a meio, o site fica com os ficheiros na versão 9 e a base de dados na versão 8, o que produz erros 500 ilegíveis. A primeira regra é, por isso, simples: nunca se lança uma atualização sem uma cópia de segurança restaurável e testada.

Eis as falhas que encontramos com mais frequência nas nossas intervenções, com a respetiva causa e a solução alternativa.

«Can't empty cache directory»

É o erro mais frequente nas passagens de 9.0.x para 9.1.x, sobretudo em PHP 8.4.

O módulo tenta esvaziar var/cache/ e esbarra em ficheiros que pertencem a outro utilizador do sistema, normalmente porque foram executados comandos por SSH com uma conta diferente da do servidor web.

Solução alternativa:

rm -rf var/cache/prod var/cache/dev
chown -R www-data:www-data var/

Adapte o utilizador ao seu alojamento. Nunca elimine a própria pasta var/cache: apenas o seu conteúdo.

«has a dependency on a non-existent service mbo.modules.repository»

Este erro, que devolve um HTTP 500 durante a etapa de verificação da versão, vem do contentor de injeção de dependências do Symfony, que ficou incoerente: o módulo MBO (o marketplace integrado) está declarado, mas os seus serviços não chegam a ser construídos.

Três ações, por esta ordem:

1. Atualizar o próprio módulo Update Assistant antes de mais nada. Uma versão antiga do módulo continua a ser a primeira causa de falha.
2. Apagar o conteúdo de var/cache/ e confirmar que a pasta app/cache/ existe e tem permissões de escrita.
3. Desativar temporariamente o ps_mbo em ps_module e voltar a lançar o processo.

O processo para sem qualquer mensagem

Em alojamento partilhado, o Update Assistant esbarra em três limites invisíveis: o max_execution_time, a memória e o próprio timeout do servidor web. A interface fica então com uma roda a girar indefinidamente.

A solução passa pela linha de comandos, que não conhece o timeout HTTP:

php modules/autoupgrade/bin/console update:start --config-file-path=config.json

Confirme antes que a função symlink() não consta da lista disable_functions da sua configuração PHP: sem ela, a troca das pastas falha em silêncio. Coloque o memory_limit a -1 durante a operação.

A armadilha da retoma manual

Quando a atualização falha a meio, a tentação é voltar a executar «à mão» os ficheiros SQL de migração. É uma armadilha.

Esses ficheiros contêm diretivas PHP encapsuladas em comentários SQL, do tipo /* PHP:add_column(...) */. Executados no phpMyAdmin, esses comentários são ignorados: a estrutura da base de dados parece migrada quando, na realidade, faltam colunas e dados. Os sintomas surgem semanas mais tarde, numa funcionalidade pouco usada.

Se a migração falhar, reponha a cópia de segurança e recomece de forma limpa. Nunca repare uma migração aplicada pela metade.

A preparação que evita 80 % das falhas

Antes de lançar seja o que for:

• Guardar ficheiros e base de dados, e testar a reposição num ambiente separado.
• Desativar todos os módulos não nativos. Um módulo que rebente durante a fase de atualização interrompe todo o processo. Volta a ativá-los um a um a seguir.
• Voltar ao tema Classic durante a operação, sobretudo se o seu tema substituir templates do core.
• Verificar a versão do PHP. O PrestaShop 9 exige PHP 8.1 no mínimo e aceita até 8.4. Uma atualização lançada em PHP 7.4 falha inevitavelmente.
• Verificar o espaço em disco. O processo duplica a totalidade do site: são precisas pelo menos duas vezes a dimensão atual.
• Listar os módulos incompatíveis. O PrestaShop 9 retirou o Guzzle, o League Tactician e o Swift Mailer. Qualquer módulo que dependa deles produz um erro fatal depois da mudança.

Depois da atualização: os testes que contam

Uma atualização «bem-sucedida» só fica validada depois de verificados estes pontos:

1. Fazer uma encomenda de ponta a ponta, com pagamento real incluído.
2. Confirmar a receção dos e-mails transacionais, muitas vezes partidos na passagem para a 9 por causa da mudança de biblioteca de envio.
3. Testar as transportadoras e os widgets de ponto de recolha no processo de compra.
4. Regenerar as miniaturas e verificar a apresentação das imagens de produto.
5. Reler var/logs/: os avisos de descontinuação de hoje são as avarias da próxima versão.

Se a passagem para a versão 9 o preocupa, o nosso artigo sobre o fim de suporte do PrestaShop 8 ajuda-o a escolher o momento certo, e a nossa página de migração PrestaShop descreve o nosso método.

Atualização bloqueada neste momento?

Retomamos migrações interrompidas, mesmo quando a loja já está offline. Diagnóstico gratuito, resposta em 1 h, das 9h às 22h, 7 dias por semana.