Product extension
Overview
For product data that cannot be mapped to the Shopware product entity, the plugin provides abstract classes for the entity twocream_product_extension including a translation table as of version 3.0.0. The product extension is linked to the product via the one-to-one association productExtension and can be written directly via the product import (see "Product import"). In the product module, the fields are mapped to the keys of product-extension via getProductExtensionFieldMap() and getProductExtensionTranslationKeyMap(), in Pimcore the product adapter delivers them under product-extension (see "Build a product export").
All classes are located in the namespace Twocream\JsonImporter\Core\Content\Product\ProductExtension.
| Abstract class | Description |
|---|---|
AbstractProductExtensionDefinition | Definition with the fields id, pimcore_id, created_at, updated_at and the associations product and translations. Custom fields are added via getAdditionalFields() |
Aggregate\ProductExtensionTranslation\AbstractProductExtensionTranslationDefinition | Translation definition for twocream_product_extension_translation. Custom fields are added via getAdditionalTranslatedFields() |
AbstractProductExtensionEntity | Entity with pimcoreId, product and translations |
Aggregate\ProductExtensionTranslation\AbstractProductExtensionTranslationEntity | Optional translation entity |
AbstractProductExtension | Adds the association productExtension to the product entity |
The plugin does not register any of these classes and does not create any tables. The concrete classes, the service registration and the migration have to be implemented in the project.
Concrete classes
For each abstract class, a concrete class has to be created in the project. The concrete entity must inherit from AbstractProductExtensionEntity.
Definition
| Name | Description |
|---|---|
getEntityClass(): string | Class of the concrete entity |
getProductExtensionTranslationDefinitionClass(): string | Class of the concrete translation definition |
getAdditionalFields(): array | Project-specific fields, including TranslatedFields for translatable fields and further associations |
<?php
namespace MyCustomExtension\Core\Content\Product\ProductExtension;
use MyCustomExtension\Core\Content\Product\ProductExtension\Aggregate\ProductExtensionTranslation\ProductExtensionTranslationDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Field\StringField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\TranslatedField;
use Twocream\JsonImporter\Core\Content\Product\ProductExtension\AbstractProductExtensionDefinition;
class ProductExtensionDefinition extends AbstractProductExtensionDefinition
{
public function getEntityClass(): string
{
return ProductExtensionEntity::class;
}
protected function getProductExtensionTranslationDefinitionClass(): string
{
return ProductExtensionTranslationDefinition::class;
}
protected function getAdditionalFields(): array
{
return [
new StringField('business_area', 'businessArea'),
new TranslatedField('subtitle'),
];
}
}
Entity
<?php
namespace MyCustomExtension\Core\Content\Product\ProductExtension;
use Twocream\JsonImporter\Core\Content\Product\ProductExtension\AbstractProductExtensionEntity;
class ProductExtensionEntity extends AbstractProductExtensionEntity
{
protected ?string $businessArea = null;
protected ?string $subtitle = null;
// Getter and setter
}
pimcoreId is defined as int in the entity. When writing the product extension, pimcoreId must therefore always be passed – the product import does this automatically.
For the fields shown above, the maps in the product module are:
protected function getProductExtensionFieldMap(): array
{
return ['business-area' => 'businessArea'];
}
protected function getProductExtensionTranslationKeyMap(): array
{
return ['subtitle' => 'subtitle'];
}
Translation definition
| Name | Description |
|---|---|
getParentDefinitionClass(): string | Class of the concrete definition of the product extension |
getAdditionalTranslatedFields(): array | Translatable fields, as counterpart to the TranslatedFields of the definition |
<?php
namespace MyCustomExtension\Core\Content\Product\ProductExtension\Aggregate\ProductExtensionTranslation;
use MyCustomExtension\Core\Content\Product\ProductExtension\ProductExtensionDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Field\LongTextField;
use Twocream\JsonImporter\Core\Content\Product\ProductExtension\Aggregate\ProductExtensionTranslation\AbstractProductExtensionTranslationDefinition;
class ProductExtensionTranslationDefinition extends AbstractProductExtensionTranslationDefinition
{
protected function getParentDefinitionClass(): string
{
return ProductExtensionDefinition::class;
}
protected function getAdditionalTranslatedFields(): array
{
return [
new LongTextField('subtitle', 'subtitle'),
];
}
}
Extension
<?php
namespace MyCustomExtension\Core\Content\Product;
use MyCustomExtension\Core\Content\Product\ProductExtension\ProductExtensionDefinition;
use Twocream\JsonImporter\Core\Content\Product\ProductExtension\AbstractProductExtension;
class ProductExtension extends AbstractProductExtension
{
protected function getProductExtensionDefinitionClass(): string
{
return ProductExtensionDefinition::class;
}
}
Registering the classes
The definitions and the extension have to be registered in the service configuration of the project:
<service id="MyCustomExtension\Core\Content\Product\ProductExtension\ProductExtensionDefinition">
<tag name="shopware.entity.definition" entity="twocream_product_extension"/>
</service>
<service id="MyCustomExtension\Core\Content\Product\ProductExtension\Aggregate\ProductExtensionTranslation\ProductExtensionTranslationDefinition">
<tag name="shopware.entity.definition" entity="twocream_product_extension_translation"/>
</service>
<service id="MyCustomExtension\Core\Content\Product\ProductExtension">
<tag name="shopware.entity.extension"/>
</service>
Once the definition and the extension are registered, the product import automatically loads the association productExtension of existing products. For deactivated variants without their own deletion record, the report additionally shows the Pimcore ID of the product extension.
Migration
The tables have to be created via a migration in the project. Example for the fields shown above:
CREATE TABLE IF NOT EXISTS `twocream_product_extension` (
`id` BINARY(16) NOT NULL,
`pimcore_id` INT NULL,
`business_area` VARCHAR(255) NULL,
`created_at` DATETIME(3) NOT NULL,
`updated_at` DATETIME(3) NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
CREATE TABLE IF NOT EXISTS `twocream_product_extension_translation` (
`twocream_product_extension_id` BINARY(16) NOT NULL,
`language_id` BINARY(16) NOT NULL,
`subtitle` LONGTEXT NULL,
`created_at` DATETIME(3) NOT NULL,
`updated_at` DATETIME(3) NULL,
PRIMARY KEY (`twocream_product_extension_id`, `language_id`),
CONSTRAINT `fk.twocream_product_extension_translation.twocream_product_extension_id`
FOREIGN KEY (`twocream_product_extension_id`)
REFERENCES `twocream_product_extension` (`id`) ON DELETE CASCADE ON UPDATE CASCADE,
CONSTRAINT `fk.twocream_product_extension_translation.language_id` FOREIGN KEY (`language_id`)
REFERENCES `language` (`id`) ON DELETE CASCADE ON UPDATE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
The table twocream_product_extension intentionally has no foreign key to product. The product table has the primary key (id, version_id), and a foreign key on a part of it does not fit the versioning. The ID of the product extension equals the ID of the product.
Therefore, the entries of a deleted product are not removed automatically – cleaning them up is the job of the project. The product import itself never deletes products, it deactivates them.
The translation table references twocream_product_extension (id) and language (id) with ON DELETE CASCADE.
| Table | Required columns | Custom columns |
|---|---|---|
twocream_product_extension | id, pimcore_id, created_at, updated_at | Fields of getAdditionalFields() |
twocream_product_extension_translation | twocream_product_extension_id, language_id, created_at, updated_at | Fields of getAdditionalTranslatedFields() |
Existing projects with their own product extension for twocream_product_extension can switch their classes to the abstract classes. Table and column names remain unchanged, no schema change is needed.