Shopware 6：自定义多对多关联通过ProductExtension加载失败排查

问题场景 #

需要在Shopware 6中创建产品与关联产品的自定义多对多关系（不使用内置交叉销售实体），例如让「锤子」关联「盒装200枚钉子」，要求在产品列表页和详情页加载主产品时，同时加载并展示关联产品的标题和图片。

已完成的实现步骤 #

1. 实体扩展与关联定义 #

• ProductExtension：扩展产品实体，添加多对多关联字段

class ProductExtension extends EntityExtension
{
    public function extendFields(FieldCollection $collection): void
    {
        $collection->add(
            (new ManyToManyAssociationField(
                'relatedproducts',
                ProductDefinition::class,
                RelatedProductDefinition::class,
                'product_id',
                'related_product_id'
            ))->addFlags(new Inherited())
        );
    }

    public function getDefinitionClass(): string
    {
        return ProductDefinition::class;
    }
}

• RelatedProductDefinition：定义关联映射实体

class RelatedProductDefinition extends MappingEntityDefinition
{
    public const ENTITY_NAME = 'custom_related_product';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection(
            [
                (new FkField(
                    'product_id',
                    'productId',
                    ProductDefinition::class
                ))->addFlags(new PrimaryKey(), new Required()),

                (new FkField(
                    'related_product_id',
                    'relatedProductId',
                    ProductDefinition::class
                ))->addFlags(new PrimaryKey(), new Required()),

                (new ReferenceVersionField(
                    ProductDefinition::class,
                    'product_version_id'
                ))->addFlags(new PrimaryKey(), new Required()),

                new ManyToOneAssociationField(
                    'product',
                    'product_id',
                    ProductDefinition::class
                ),

                new ManyToOneAssociationField(
                    'relatedProduct',
                    'related_product_id',
                    ProductDefinition::class
                ),

                new CreatedAtField()
            ]
        );
    }
}

2. 数据库迁移脚本 #

创建关联表并更新产品实体继承关系：

// 创建关联表
$sql = <<<SQL
CREATE TABLE IF NOT EXISTS `custom_related_product` (
    `product_id`     BINARY(16)  NOT NULL,
    `related_product_id`    BINARY(16)  NOT NULL,
    `product_version_id`    BINARY(16)  NOT NULL,
    `created_at`            DATETIME(3) NOT NULL,
    `updated_at`            DATETIME(3) NULL,
    PRIMARY KEY (`product_id`, `related_product_id`, `product_version_id`),
  CONSTRAINT `fk.custom_related_product.product_id` FOREIGN KEY (`product_id`)
    REFERENCES `product` (`id`) ON DELETE CASCADE ON UPDATE CASCADE,
  CONSTRAINT `fk.custom_related_product.related_product_id` FOREIGN KEY (`related_product_id`)
    REFERENCES `product` (`id`) ON DELETE CASCADE ON UPDATE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
SQL;
$connection->executeStatement($sql);

$this->updateInheritance($connection, 'product', 'relatedproducts');

关联表数据结构（简化）：

3. 列表页关联加载配置 #

订阅ProductListingCriteriaEvent，尝试添加关联加载：

public function onProductListingCriteriaEvent(ProductListingCriteriaEvent $event): void
{
    $event->getCriteria()->addAssociation('relatedproducts');
}

遇到的问题 #

关联数据未被加载，分析生成的SQL发现WHERE条件存在错误（预期为product.relatedproducts.mapping.product_id = product.id），手动修改条件后，仍无法在ProductEntity中获取relatedproducts数据。

问题排查与解决方案 #

1. 修正多对多关联字段参数 #

ManyToManyAssociationField需要明确指定映射实体中指向两端实体的关联属性名，否则Shopware无法正确解析关联关系。修改ProductExtension中的关联定义：

(new ManyToManyAssociationField(
    'relatedproducts',
    ProductDefinition::class,
    RelatedProductDefinition::class,
    'product_id',
    'related_product_id',
    // 新增：指定映射实体中对应主实体、关联实体的关联名称
    'product',
    'relatedProduct'
))->addFlags(new Inherited())

2. 补充版本字段的关联 #

产品是版本化实体，映射实体中的product_version_id需要添加对应关联，确保查询时匹配当前产品版本。在RelatedProductDefinition中补充：

(new ReferenceVersionField(
    ProductDefinition::class,
    'product_version_id'
))->addFlags(new PrimaryKey(), new Required()),
// 新增：关联到产品版本
new ManyToOneAssociationField(
    'productVersion',
    'product_version_id',
    ProductDefinition::class,
    'version_id'
),

3. 配置嵌套关联加载 #

仅添加relatedproducts关联只会加载映射实体，不会自动加载关联的产品数据。需要在事件订阅中配置嵌套关联，同时按需指定要加载的字段：

public function onProductListingCriteriaEvent(ProductListingCriteriaEvent $event): void
{
    $criteria = $event->getCriteria();
    // 加载关联的产品实体
    $criteria->addAssociation('relatedproducts.relatedProduct');
    // 可选：过滤活跃产品并仅加载需要的字段，优化性能
    $criteria->getAssociation('relatedproducts.relatedProduct')
        ->addFilter(new EqualsFilter('active', true))
        ->addFields('name', 'cover');
}

4. 验证继承关系更新 #

确认迁移中的updateInheritance方法正确执行，可检查product表的config字段，确认relatedproducts已被添加到实体继承配置中。

5. 清理缓存 #

修改实体定义后必须清理Shopware缓存：

bin/console cache:clear
bin/console cache:warmup

完成以上步骤后，即可通过$product->get('relatedproducts')获取映射实体集合，再通过$mapping->getRelatedProduct()获取关联的产品实体。

内容的提问来源于stack exchange，提问作者quibuz