Shopware 6 插件单元测试因自动加载机制混乱引发 Cannot declare class ... because the name is already in use 错误，根源在于 vendor 目录下 Shopware 核心类被多次注册；本文提供基于官方规范的标准化测试环境搭建方案，彻底规避命名空间碰撞。
shopware 6 插件单元测试因自动加载机制混乱引发 `cannot declare class ... because the name is already in use` 错误，根源在于 vendor 目录下 shopware 核心类被多次注册；本文提供基于官方规范的标准化测试环境搭建方案，彻底规避命名空间碰撞。
在 Shopware 6 插件开发中，单元测试阶段出现类似 Compile Error: Cannot declare class ShopwareCoreCheckoutPromotionCartPromotionProcessor, because the name is already in use 的致命错误，并非代码逻辑缺陷，而是测试引导流程中类自动加载路径失控所致。该问题常发生在直接复制 SwagPayPal 等第三方插件的 TestBootstrap.php 后——因其隐式依赖特定项目结构与缓存策略，在独立插件环境中极易引发核心类（如 PromotionProcessor）被从 vendor/shopware/core/ 和当前插件 vendor/（或根项目 vendor/）双重加载，触发 PHP 的类重声明限制。
✅ 正确做法：弃用“复制粘贴”，严格遵循官方测试引导规范
Shopware 官方明确建议：每个插件应构建隔离、可复现的测试上下文，而非复用其他插件的 bootstrap 配置。关键步骤如下：
1. 删除自定义 TestBootstrap.php，改用 Shopware 内置测试内核
移除 phpunit.xml.dist 中 bootstrap="tests/TestBootstrap.php" 引用，改为使用 Shopware 提供的标准测试启动器：
<!-- phpunit.xml.dist --> <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nonamespaceschemalocation="https://schema.phpunit.de/9.5/phpunit.xsd" bootstrap="vendor/shopware/core/Test/bootstrap.php" colors="true"><testsuites><testsuite name="Plugin Tests"><directory>tests</directory></testsuite></testsuites></phpunit>
⚠️ 注意：确保
vendor/shopware/core/Test/bootstrap.php存在（需已执行composer install并正确安装shopware/core）。
2. 测试类继承标准行为，显式激活插件
使用 IntegrationTestBehaviour（集成测试）或 StorefrontPageTestBehaviour（前端页面测试），并在 setUp() 中调用 installPlugin()：
<?php use PHPUnitFrameworkTestCase;
use ShopwareCoreTestIntegrationTestBehaviour;
use ShopwareCoreTestStorefrontPageTestBehaviour;
class CustomerRepositoryTest extends TestCase
{
use IntegrationTestBehaviour; // 提供 getContainer(), installPlugin() 等能力
protected function setUp(): void
{
parent::setUp();
// ✅ 关键：按插件技术名称激活（非目录名！）
$this->installPlugin('MyProductReturns'); // 名称必须与 plugin.xml <name> 或 composer.json "name" 一致
}
public function testCustomerUpsertWorks(): void
{
$customerRepository = $this->getContainer()->get('customer.repository');
$context = ShopwareCoreFrameworkContext::createDefaultContext();
$customerData = [
'id' => 'test-customer-id',
'email' => 'test@example.com',
'firstName' => 'John',
'lastName' => 'Doe',
];
$customerRepository->upsert([$customerData], $context);
// 后续断言...
}
}</name>
3. 确保 composer.json 自动加载配置纯净
避免在插件 composer.json 中错误引入 shopware/core 作为 require（这会导致 vendor 嵌套加载）：
{
"require": {
"php": ">=8.0",
"ext-json": "*",
"goetas-webservices/xsd2php-runtime": "^0.2.16",
"enqueue/stomp": "^0.10.16"
// ❌ 移除 "shopware/core": "6.4.12.0"
},
"autoload": {
"psr-4": {
"Namespace\Plugin\": "src/"
}
},
"autoload-dev": {
"psr-4": {
"Namespace\Plugin\Test\": "tests/"
}
}
}
✅ 正确方式：Shopware 核心由宿主项目（即运行 Shopware 的根应用）统一提供，插件仅通过
require-dev引入测试辅助包（如shopware/platform），并在phpunit.xml中指向其bootstrap.php。
4. 清理与验证命令（推荐 CI/CD 中固化）
# 彻底清理测试缓存（非临时方案，而是验证手段） rm -rf var/cache/test_* # 运行单个测试，观察是否稳定通过 ./vendor/bin/phpunit tests/Unit/CustomerRepositoryTest.php # 检查自动加载映射（确认无重复注册） composer dump-autoload --optimize
? 根本原因总结与预防原则
-
冲突本质：PHP 的
spl_autoload_register在多 vendor 层级下未做命名空间去重，导致ShopwareCore...类被从不同路径（如plugin/vendor/shopware/core/和project/vendor/shopware/core/）两次加载。 - 为何首次成功？ 因 Symfony 缓存未生成，类加载器处于“宽松模式”；二次运行时缓存启用，校验变严格，立即报错。
-
黄金守则：
- 插件不
requireshopware/core，只依赖宿主环境； - 测试入口必须使用
vendor/shopware/core/Test/bootstrap.php； - 插件激活必须通过
$this->installPlugin('TechnicalName')，而非手动注册服务或修改容器； - 禁止跨项目复制
TestBootstrap.php—— 它是项目级配置，非插件通用契约。
- 插件不
遵循上述结构化实践，即可一劳永逸解决命名空间碰撞问题，让插件测试真正具备可移植性与工程可靠性。
