Shopware 6.8 升级指南：核心变更与技术适配要点-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01007/article/details/148755378

Shopware 6.8 升级指南：核心变更与技术适配要点

shopware Shopware 6 is an open commerce platform based on Symfony Framework and Vue and supported by a worldwide community and more than 1.500 community extensions 项目地址: https://gitcode.com/gh_mirrors/sh/shopware

前言

Shopware 6.8版本带来了一系列重要的架构改进和功能优化，本文将深入解析这些变更的技术细节，帮助开发者顺利完成升级适配工作。

一、设置菜单结构重构

1.1 新旧结构对比

Shopware 6.8对后台设置菜单进行了重大重构，从原有的标签页(Tab)布局改为网格(Grid)布局。这种改变带来了更直观的分类和更好的用户体验。

旧结构：基于标签页的线性布局 新结构：分为9个逻辑分组的网格布局：

通用设置(General)
客户管理(Customer)
自动化(Automation)
本地化(Localization)
内容管理(Content)
电商功能(Commerce)
系统设置(System)
账户管理(Account)
扩展功能(Extensions)

1.2 模板变更说明

在sw-settings-index.html.twig模板中，开发者需要注意以下变更：

移除的区块：

sw_settings_content_tab_shop
sw_settings_content_tab_system
sw_settings_content_tab_plugins
sw_settings_content_card
sw_settings_content_header
sw_settings_content_card_content

新增的区块：

sw_settings_content_card_content_grid
sw_settings_content_card_view
sw_settings_content_card_view_header

适配建议：检查所有自定义设置页面，确保它们能够适应新的网格布局结构。

二、API客户端安全增强

2.1 ApiClient构造函数变更

ApiClient类的构造函数参数顺序进行了调整，提高了代码安全性：

// 6.8版本要求
new ApiClient(
    $identifier, 
    $secret, 
    bool $confidential, // 必须显式传递布尔值
    string $name        // 名称参数现在作为第四个参数
);

关键变更点：

confidential参数现在必须显式传递布尔值
参数顺序调整，confidential变为第三参数，name变为第四参数

三、前端架构优化

3.1 DomAccess Helper废弃

Shopware 6.8移除了DomAccess Helper，推荐使用原生浏览器API：

方法替换对照表：

| 原方法 | 替换方案 | 示例 | |--------|----------|------| | hasAttribute() | element.hasAttribute() | el.hasAttribute('data-test') | | getAttribute() | element.getAttribute() | el.getAttribute('href') | | getDataAttribute() | element.getAttribute() | el.getAttribute('data-attr') | | querySelector() | element.querySelector() | container.querySelector('.class') | | querySelectorAll() | element.querySelectorAll() | form.querySelectorAll('input') |

焦点相关方法已迁移至FocusHandler：

// 获取可聚焦元素
window.focusHandler.getFocusableElements()

// 获取第一个可聚焦元素
window.focusHandler.getFirstFocusableElement()

// 获取最后一个可聚焦元素
window.focusHandler.getLastFocusableElement()

3.2 路由与模板清理

废弃路由：移除widgets.account.order.detail，需要检查所有引用该路由的地方
模板替换：用alert.html.twig替代cart-alerts.html.twig

四、核心架构改进

4.1 缓存事件清理

随着6.7版本Store-API缓存层的移除，相关缓存事件已被废弃。开发者需要移除对以下事件的依赖：

StoreApiRouteCacheKeyEvent
StoreApiRouteCacheTagsEvent
// 以及所有子类事件（约30个具体事件）

4.2 支付与配送方法过滤

PaymentMethodCollection和ShippingMethodCollection中的filterByActiveRules方法已被移除，替代方案：

use Shopware\Core\Framework\Rule\RuleIdMatcher;

$matcher = new RuleIdMatcher();
$activeMethods = $matcher->filter($collection, $context);

4.3 主订单交付与交易

新增两个重要属性简化订单处理：

primaryOrderDelivery：替代deliveries.first()
primaryOrderTransaction：替代transactions.last()

注意：OrderTransactionStatusRule现在始终使用primaryOrderTransaction

五、主题系统改进

5.1 主题配置国际化

移除了theme.json中的label和helpText属性，改用片段系统：

片段键命名规则：

sw-theme.<technicalName>.<tab>.<block>.<section>.<field>.<property>

示例：

// 主题颜色设置标签
sw-theme.my-theme.colorTab.primaryColors.label

// 字段帮助文本
sw-theme.my-theme.colorTab.primaryColors.mainColor.helpText

5.2 主题服务重构

废弃方法：

ThemeService::getThemeConfiguration
ThemeService::getThemeConfigurationStructuredFields

替代方案：

$configuration = $themeConfigService->getPlainThemeConfiguration();
$structure = $themeConfigService->getThemeConfigurationFieldStructure();

5.3 Twig函数变更

分类URL函数：

- {{ category_url(item) }}
+ {{ item.seoUrl }}

新标签页函数：

- {% if category_linknewtab(item) %}
+ {% if item.shouldOpenInNewTab %}

面包屑函数参数变更：

- sw_breadcrumb_full(category, context.context)
+ sw_breadcrumb_full(category, context)

六、应用系统调整

6.1 Twig宏函数规范

在应用脚本中，返回值必须使用sw_macro_function：

{% sw_macro_function getMedia(mediaId) %}
    {% set criteria = { ids: [mediaId] } %}
    {% return services.repository.search('media', criteria).first %}
{% end_sw_macro_function %}

6.2 国家状态API限制

CountryStateController的/country/country-state-data路由现在仅支持GET方法，提升缓存兼容性。

七、配置清理

随着Store-API缓存层的移除，以下配置项已被删除：

# 已移除的缓存配置示例
shopware.cache.invalidation.product_listing_route
shopware.cache.invalidation.navigation_route
shopware.cache.invalidation.category_route
// ...共约17个相关配置