Skip to main content
Version: 2026.10

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 classDescription
AbstractProductExtensionDefinitionDefinition with the fields id, pimcore_id, created_at, updated_at and the associations product and translations. Custom fields are added via getAdditionalFields()
Aggregate\ProductExtensionTranslation\AbstractProductExtensionTranslationDefinitionTranslation definition for twocream_product_extension_translation. Custom fields are added via getAdditionalTranslatedFields()
AbstractProductExtensionEntityEntity with pimcoreId, product and translations
Aggregate\ProductExtensionTranslation\AbstractProductExtensionTranslationEntityOptional translation entity
AbstractProductExtensionAdds the association productExtension to the product entity
caution

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​

NameDescription
getEntityClass(): stringClass of the concrete entity
getProductExtensionTranslationDefinitionClass(): stringClass of the concrete translation definition
getAdditionalFields(): arrayProject-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
}
Note

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​

NameDescription
getParentDefinitionClass(): stringClass of the concrete definition of the product extension
getAdditionalTranslatedFields(): arrayTranslatable 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;
Note

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.

TableRequired columnsCustom columns
twocream_product_extensionid, pimcore_id, created_at, updated_atFields of getAdditionalFields()
twocream_product_extension_translationtwocream_product_extension_id, language_id, created_at, updated_atFields of getAdditionalTranslatedFields()
Note

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.