O Shopware 6.7 saiu no fim de 2024 com o que a documentação oficial classifica de «major release with multiple breaking changes». Para as lojas em 6.6, a migração é obrigatória a prazo: o Shopware só mantém em paralelo a última versão estável e a anterior, pelo que ficar em 6.5 ou 6.6 demasiado tempo corta o acesso às correções de segurança. Para os plugins desenvolvidos em 6.6, várias API críticas mudaram de assinatura ou foram removidas entre a 6.6 e a 6.7.
Este artigo é um relato de experiência direto sobre a migração 6.6 para 6.7 que fizemos em várias lojas em 2025 e 2026, com as verdadeiras armadilhas técnicas que encontrámos e os patches que tivemos de produzir para adaptar os nossos plugins e os de terceiros. O objetivo: poupar a outras equipas o mês de depuração que passámos com certas regressões silenciosas.
O que muda mesmo no Shopware 6.7
Para além do marketing da versão, eis as mudanças da 6.7 com impacto concreto nos plugins existentes.
Refundição da API Payment Handler. A interface AsynchronousPaymentHandlerInterface é removida na 6.7. Qualquer plugin de pagamento que a implementasse em 6.6 tem de migrar para AbstractPaymentHandler. Os métodos pay() e finalize() têm uma assinatura diferente: a struct AsyncPaymentTransactionStruct é substituída por PaymentTransactionStruct, mais minimalista e orientada a DDD.
Tags de serviço alteradas. A tag shopware.payment.method.async, que distinguia os pagamentos síncronos dos assíncronos, é removida a favor de uma tag unificada shopware.payment.method. Se os seus services.xml usavam a tag antiga, o payment handler deixa de se declarar corretamente e o meio de pagamento desaparece do checkout sem erro visível.
Migração da administração de Vue 2 para Vue 3. A administração do Shopware 6.7 está portada para Vue 3 (a 6.6 estava em Vue 2 com camada de compatibilidade). Os componentes sw-* (legado) estão a ser substituídos pelos componentes mt-* (design system Meteor). Muitos componentes sw-* estão marcados como descontinuados e serão removidos numa versão 6.x posterior. Os plugins de administração que os usavam têm de migrar.
Sistema de tradução da administração alterado. Os métodos $tc() (translation choice, gestão do plural) foram substituídos por $t() com gestão nativa do plural. Os templates de administração que faziam {{ $tc('meu.plugin.label') }} têm de passar a {{ $t('meu.plugin.label') }}.
Build da administração com Vite. A administração compila agora com Vite, com um manifest.json estruturado de forma diferente da 6.6. Os plugins que injetavam o seu JS de administração pelo mecanismo histórico têm de adaptar o pipeline de build para gerar o manifesto certo, senão a administração carrega um JS vazio em vez do seu código.
Montra: Bootstrap 5.3 generalizado. A passagem ao Bootstrap 5.3 na montra ativa o suporte nativo de data-bs-theme, o que simplifica as implementações de modo escuro, tema do nosso plugin DataFirefly Dark Mode, que explora essa convenção. Os temas à medida baseados em Bootstrap 5.2 ou anterior podem ter variáveis SCSS que deixam de mapear.
Compatibilidade PHP e MySQL. A 6.7 exige PHP 8.2+ (o PHP 8.1 sai, o PHP 8.3 é recomendado) e MySQL 8.0+ ou MariaDB 11.4 LTS. Os alojamentos ainda em MySQL 5.7 ou MariaDB 10.x têm de migrar a base de dados antes da atualização aplicacional.
Os breaking changes, plugin a plugin, que encontrámos
Nas lojas que migrámos, estes foram os bugs concretos descobertos na atualização 6.6 para 6.7.
MoptWorldline (pagamento Worldline / SaferPay). O plugin de pagamento Worldline na versão 6.6 implementava AsynchronousPaymentHandlerInterface. Na passagem à 6.7, o plugin deixa de carregar corretamente e os meios de pagamento Worldline desaparecem do checkout. O patch exige migrar para AbstractPaymentHandler e reescrever os métodos pay() e finalize() com a nova assinatura PaymentTransactionStruct. Trabalho estimado: 2 a 4 dias para um programador Shopware experiente.
Plugins de administração à medida com componentes sw-*. Nos nossos plugins MySmartBook e outros, vários componentes de administração usavam sw-card, sw-button, sw-text-field e afins. Na 6.7, esses componentes ainda existem, mas estão marcados como descontinuados. Os componentes mt-card, mt-button e mt-text-field substituem-nos. A migração é mecânica, mas exige uma revisão exaustiva de todos os ficheiros de administração.
Snippets e traduções. Os ficheiros de snippets em 6.6 usavam por vezes a estrutura pluralizada consumida por $tc(). Na 6.7, com $t(), algumas estruturas de snippets já não funcionam de forma idêntica. A testar sistematicamente, sobretudo nos snippets com contadores («1 produto» / «N produtos»).
Custom field de cliente e sincronização. O nosso plugin Dark Mode para Shopware guarda a preferência do utilizador num custom field df_dark_mode_preference na entidade customer. A migração 6.7 manteve a compatibilidade dos custom fields, mas a API de sincronização tem uma assinatura ligeiramente diferente. A testar sistematicamente depois da atualização.
OpenSearch 2.19+ obrigatório. Se a loja usa a pesquisa de texto completo com OpenSearch (ex-Elasticsearch nas versões anteriores do Shopware), a 6.7 exige OpenSearch 2.19 no mínimo. As versões OpenSearch 1.x deixaram de ser suportadas. Migração do cluster OpenSearch a prever antes da atualização aplicacional.
A checklist de migração em 8 etapas
Para uma migração 6.6 para 6.7 controlada, esta é a ordem que seguimos internamente.
Etapa 1: auditoria dos plugins instalados. Liste todos os plugins ativos na loja. Para cada um, verifique na store ou no GitHub se existe uma versão compatível com a 6.7. Os plugins não atualizados são riscos graves: a desativar temporariamente, a corrigir internamente ou a substituir.
Etapa 2: auditoria do tema à medida. Se usa um tema à medida (e não o tema Storefront nativo), verifique a compatibilidade com o Bootstrap 5.3, as mudanças de estrutura do layout de base e o sistema Vite da administração se o tema injetar JS de administração próprio.
Etapa 3: atualização do ambiente de infraestrutura. PHP 8.2+, MySQL 8 ou MariaDB 11.4 LTS, OpenSearch 2.19+ se usado, Node.js recente (18+ ou 20 LTS). A fazer antes da atualização aplicacional do Shopware.
Etapa 4: cópia de segurança completa. Base de dados mais a pasta files mais os ficheiros de config/. É a etapa que se tende a negligenciar até ao momento em que a atualização parte irremediavelmente alguma coisa. A fazer sistematicamente antes de qualquer alteração.
Etapa 5: migração num ambiente de staging. Clonar a produção num staging idêntico, fazer a atualização 6.7 no staging e validar exaustivamente antes de tocar na produção. Não é opcional: nas lojas que migrámos, 30 % tiveram bugs críticos descobertos apenas em staging.
Etapa 6: atualização aplicacional do Shopware. Através do SUM (Shopware Update Manager) em linha de comandos: bin/console system:update:prepare e depois bin/console system:update:finish. Ler bem a documentação oficial para as opções (skip-asset-build e outras). Conte 30 minutos a 2 horas consoante o tamanho da base.
Etapa 7: recompilação do tema e da administração. Depois da atualização do core, recompilar o tema (bin/console theme:compile) e reconstruir a administração (bin/build-administration.sh). No Shopware 6.7, a administração compila com Vite; o comando histórico theme:compile já não chega para a administração.
Etapa 8: teste exaustivo pós-atualização. Percurso completo: navegação no catálogo, página de produto, adição ao carrinho, checkout, pagamento (cada meio de pagamento testado individualmente), área de cliente, administração (cada módulo instalado). Nas lojas B2B, testar também orçamentos, contas hierárquicas e preços por cliente.
As armadilhas silenciosas que encontrámos na prática
Para além dos breaking changes documentados, estes são os bugs subtis que não se veem de imediato depois da atualização.
O payment handler que deixa de se declarar. Como referido acima, um plugin de pagamento com a tag antiga shopware.payment.method.async deixa de se registar na 6.7. O meio de pagamento desaparece do checkout, mas não é lançado qualquer erro: o payment_method_id correspondente continua a existir na base, simplesmente o handler já não é instanciado. Sintoma do lado do cliente: o método aparece na administração (configuração / sales channels / payment methods) mas não no checkout.
O componente de administração à medida que renderiza vazio. Um componente que usava $tc() sem tradução associada (caso dos labels escritos diretamente no código) deixa de renderizar na 6.7. Sem erro na consola, apenas um espaço vazio. A detetar por revisão manual dos ecrãs de administração à medida depois da atualização.
O manifesto Vite que não é gerado. Se o plugin de administração à medida era compilado com um script personalizado em 6.6 (webpack ou rollup direto), esse build pode não gerar o manifest.json esperado pelo Shopware 6.7. Sintoma: a administração carrega, mas o JS do plugin não executa. Solução: adaptar o build para exportar um manifesto compatível com Vite.
Os snippets pluralizados que deixam de se traduzir. Se tinha snippets com estrutura {count} | uma coisa | {count} coisas consumidos por $tc(), a passagem a $t() exige uma sintaxe diferente. Os snippets não migrados mostram a cadeia do template em bruto em vez da tradução.
O custom field que já não existe na API. Algumas alterações da API DAL (Data Abstraction Layer) na 6.7 mudaram a serialização de certos custom fields complexos (seleção múltipla, JSON). Os valores na base continuam a existir, mas são lidos de forma diferente. A testar nos custom fields críticos.
Conclusão: uma migração necessária, mas a antecipar
A migração do Shopware 6.6 para 6.7 não é uma simples atualização menor. Introduz breaking changes significativos que exigem trabalho real nos plugins (pagamento em particular), na administração à medida e na infraestrutura. As lojas que fazem esta migração num dia «porque só clicámos em Update» descobrem os bugs em produção semanas depois, por vezes com impacto direto nas vendas (pagamento partido, administração inutilizável).
O investimento realista em tempo para uma loja com 5 a 10 plugins de terceiros e um tema à medida é de 5 a 15 dias de um programador Shopware experiente, mais alguns dias de testes de aceitação. Antecipar o tema, fazer a atualização em staging e testar exaustivamente antes da produção é o que distingue uma migração controlada de uma migração em crise.
Para os temas técnicos relacionados, percorra as categorias Notícias e-commerce e Desempenho e Core Web Vitals. E se procura plugins Shopware 6.7 rápidos por construção e bem mantidos, o nosso plugin Dark Mode é compatível com o Shopware 6.7 desde o lançamento e ilustra os padrões técnicos alinhados com a nova arquitetura (anti-FOUC, custom field de cliente, eventos JS para sincronização com terceiros).
Leia também: PrestaShop 9 vs PrestaShop 8.
