Checklist de upgrade para o Magento 2.4.8, passo a passo

A maioria dos upgrades de Magento que dão errado não falha por causa do Magento em si. Falha porque a stack do servidor não estava pronta, uma extensão de terceiros nunca foi verificada, ou o time descobriu na noite do lançamento que um plugin customizado do checkout depende de um método que mudou. Um upgrade para a 2.4.8 é um projeto com algumas fases previsíveis, e tratar assim elimina quase todo o risco.

Este é o checklist que eu sigo ao mover uma loja da 2.4.4, 2.4.5, 2.4.6 ou 2.4.7 para a 2.4.8. Vale para Magento Open Source e Adobe Commerce. Onde algo só existe no Adobe Commerce, eu aviso.

1. Defina a versão exata de destino

Não faça upgrade para a 2.4.8 pura. A Adobe lança patch releases de segurança em cima de cada versão minor, chamadas 2.4.8-p1, 2.4.8-p2 e assim por diante. Veja as release notes e mire na última patch release disponível quando você começar o projeto, e depois planeje aplicar as patch releases mais novas conforme saírem. Se o projeto dura várias semanas, uma nova patch release pode aparecer no meio, então mantenha a versão num único lugar nas suas anotações e atualize antes do go live.

Leia as release notes de cada versão minor entre a sua atual e a 2.4.8, não só as da 2.4.8. Se você está na 2.4.6, as mudanças da 2.4.7 importam tanto quanto as da 2.4.8. Um exemplo conhecido é a mudança de Content Security Policy na 2.4.7, em que as páginas de checkout passaram para o modo restrict. Qualquer script inline no checkout que não esteja na whitelist ou não seja carregado do jeito certo vai parar de funcionar.

2. Prepare a stack

A 2.4.8 mira PHP 8.3 e 8.4. Confira a página oficial de requisitos de sistema para as versões exatas suportadas de cada serviço, porque a Adobe a atualiza com as patch releases. Os serviços que você precisa comparar com o seu setup atual são:

• Versão do PHP e extensões (bcmath, intl, soap, sodium, xsl, zip, gd e o resto da página de requisitos)
• Versão do MySQL ou MariaDB
• Versão do OpenSearch. Se você ainda roda Elasticsearch, planeje a migração para OpenSearch antes do upgrade, porque as releases atuais são testadas contra o OpenSearch
• Versões de Redis ou Valkey, RabbitMQ e Varnish
• Versão do Composer 2

Atualize os serviços no seu ambiente local primeiro e mantenha a versão antiga do Magento rodando neles quando possível. Uma loja Magento 2.4.7 com PHP 8.3 é uma combinação válida, então dá para separar o upgrade do PHP do upgrade do Magento e achar os problemas um de cada vez. Escrevi mais sobre essa parte no guia de compatibilidade com PHP 8.

3. Faça o inventário do código

Antes de tocar no Composer, liste o que vai precisar de atenção:

bin/magento --version
bin/magento module:status --disabled
composer show --direct
ls app/code

Separe o resultado em três grupos:

• Extensões de fornecedores via Composer. Para cada uma, ache a versão que declara suporte à 2.4.8 e ao PHP para o qual você está indo. Alguns fornecedores publicam isso só no changelog, então olhe lá também.
• Código customizado em app/code. Esse é seu para consertar. Plugins e preferences em classes do core são o maior risco, porque uma assinatura de método alterada quebra em runtime ou na hora do compile.
• Módulos desabilitados ou sem uso. É um bom momento para removê-los em vez de carregá-los adiante. Veja como remover um módulo com segurança.

Clientes do Adobe Commerce podem rodar a Upgrade Compatibility Tool, que compara o código customizado com a versão de destino e aponta o uso de APIs removidas ou alteradas. No Magento Open Source você tem uma cobertura parecida, com mais trabalho manual, rodando PHPStan e o coding standard do Magento sobre o app/code depois do upgrade.

4. Rode o upgrade do Composer numa branch

Trabalhe numa branch dedicada, com uma cópia nova do banco de produção no seu ambiente local. Coloque o site em maintenance mode localmente e depois atualize o root package. O comando require-commerce vem do composer root update plugin e também atualiza as entradas do composer.json raiz que o metapackage do Magento espera.

composer require magento/composer-root-update-plugin "^2.0" --no-update
composer update magento/composer-root-update-plugin

composer require-commerce magento/product-community-edition 2.4.8-p3 --no-update
composer update

No Adobe Commerce, o pacote é magento/product-enterprise-edition. Troque a string de versão pela patch release que você escolheu no passo 1.

O primeiro composer update raramente passa numa loja real. As causas de sempre são extensões que fixam uma versão antiga do framework, um pacote de fornecedor que exige uma faixa de PHP que exclui o 8.4, ou um patch antigo no composer.json que não se aplica mais. Resolva cada conflito atualizando a extensão ou removendo ela. Não use --ignore-platform-reqs para forçar a instalação, isso só empurra o erro para o runtime.

Se você aplica patches com cweagans/composer-patches, muitos vão falhar depois do upgrade porque a correção já está no core. Remova os que foram incluídos na nova versão e reconstrua o resto. Há mais sobre isso no artigo sobre Composer patches.

5. Atualize o banco e compile

bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento indexer:reindex
bin/magento cache:flush

O setup:di:compile é o primeiro teste de verdade do seu código. Ele falha em classes ausentes, argumentos de construtor errados e plugins em métodos que não existem mais. Leia cada erro, não apague só a pasta generated e tente de novo.

Depois rode as suas próprias verificações:

bin/magento setup:db:status
vendor/bin/phpstan analyse app/code
vendor/bin/phpcs --standard=Magento2 app/code

6. Teste o que dá dinheiro

Um teste de regressão completo é o ideal, mas raramente cabe no orçamento. No mínimo, teste esses fluxos com dados reais do banco copiado:

1. Página de categoria com layered navigation e ordenação
2. Página de produto para cada tipo de produto que você vende (simple, configurable, bundle, grouped)
3. Adicionar ao carrinho, minicart, página do carrinho com cupom
4. Checkout como guest e como cliente logado, com todos os métodos de pagamento e de frete ativos
5. E-mail de pedido, invoice, shipment e credit memo no admin
6. Integrações: exportação para ERP, sync com marketplace, feeds, qualquer cron job que fale com um sistema externo
7. Login no admin com autenticação em dois fatores, salvar produto, salvar configuração

Acompanhe o var/log/exception.log e o var/log/system.log durante os testes, e confira o console do navegador no checkout atrás de violações de CSP e erros de JavaScript. Avisos de deprecation do PHP 8.4 muitas vezes aparecem nos logs antes de qualquer coisa quebrar de forma visível.

Confira também o cron e os consumers de queue. Rode bin/magento cron:run algumas vezes e olhe a tabela cron_schedule atrás de jobs em estado de erro. Se você usa RabbitMQ, confirme que os consumers iniciam e processam mensagens.

7. Planeje o release de produção

O upgrade em produção roda setup:upgrade no banco real, então precisa de maintenance mode. Planeje a janela:

• Faça um backup completo do banco e uma cópia do app/etc/env.php logo antes de começar. Veja o guia de backup e restore.
• Faça o build do código (Composer install, compile, static content) antes da janela, numa pasta de release separada, para que o maintenance mode cubra só o upgrade do banco e a troca.
• Atualize o PHP no servidor primeiro, de preferência num release anterior separado com a versão antiga do Magento, para que uma única janela não mude tudo de uma vez.
• Meça o tempo do setup:upgrade numa cópia da produção. Catálogos grandes e tabelas de vendas grandes podem deixar algumas mudanças de schema lentas.
• Escreva o plano de rollback. Se o upgrade do banco já rodou, voltar significa restaurar o backup, então decida de antemão por quanto tempo você vai tentar corrigir para a frente antes de restaurar.

8. Depois do go live

Nos primeiros dias, acompanhe os logs de erro, o cron schedule, os consumers de queue e o volume de pedidos. Compare a taxa de conversão e os erros de checkout com a semana anterior. Limpe e aqueça o full page cache para que os primeiros clientes não paguem por páginas frias. Depois remova a pasta do release antigo e os patches temporários, e atualize sua documentação com as novas versões de PHP e dos serviços.

Por fim, coloque um lembrete para aplicar a próxima patch release. Ir da 2.4.8-p3 para uma 2.4.8-p posterior é uma mudança pequena perto desta, e acompanhar as patch releases é a forma mais barata de evitar que o próximo upgrade grande vire uma emergência.

FAQ

Quanto tempo leva um upgrade para o Magento 2.4.8?

Depende principalmente do número de extensões de terceiros e de quanto código customizado toca classes do core. Uma loja limpa, com poucas extensões, fica pronta em alguns dias. Uma loja com dezenas de extensões e muita customização leva semanas, a maior parte em testes.

Posso atualizar direto da 2.4.4 para a 2.4.8?

Sim. O Composer instala a versão de destino direto e o setup:upgrade roda todas as mudanças de schema e de dados do caminho. Você ainda precisa ler as release notes de cada versão que pular.

Preciso atualizar o PHP ao mesmo tempo?

A 2.4.8 exige PHP 8.3 ou 8.4, então o PHP precisa ser atualizado em algum momento. Fazer isso primeiro, na versão antiga do Magento onde for suportado, divide o risco em dois releases menores.

A Upgrade Compatibility Tool está disponível para o Magento Open Source?

Ela é oferecida a clientes do Adobe Commerce. No Open Source você consegue informação parecida com o setup:di:compile, o PHPStan e o coding standard do Magento.

Atendo como freelancer em Magento e Adobe Commerce, incluindo upgrades de versão. Se você precisa de ajuda com isso, fale comigo.