This section describes how the module maps images for products to Shopware and what configuration options are available.

Asset Type Definition

Assets must be part of an AssetGroup that has one of the types defined in Elio\CommerceBundle\Definition\Product\ProductAssetGroupTypeDefinition. Available type definitions are:


Image Positions

The order of the Asset documents on the product determines the positions of the images in Shopware.

Cover Images

The first asset that does not have a deletedAt timestamp is set as the cover image of a product.


There are two options available.

Automatic Generation

The first option is to let the module generate the file names automatically. Since there have been problems with duplicate file names in the past, this is the recommended option. File names in Shopware must be globally unique.

If you choose this option the file names are generated from their position and product number: {{productNumber}}_{{position}}. The original file names are stored in a custom field.

Custom / Original

If you wish to keep the original file names as stored in your file system you can activate this behaviour by setting the configuration subsections.product.keepOriginalFilenames to true.

Keep in mind that filenames must be globally unique.

Image Updates

  • The mapping between an asset (synQup) and a media entity (Shopware) is done based on the identifier of the asset.
  • The check if the underlying image of an asset matches the corresponding image in shopware is done by the help of the hash value of the asset.
  • If the hash values do not match the image in Shopware is going to be replaced.
  • The following case is not covered by the module: manual replacement of an image in the backend changes the image, but not the hash value in the CustomField. The module is not able to detect the changed image.

Image Deletion

In addition to the general media deletion rules there are some things to keep in mind when deleting product images.

Images cannot be deleted in Shopware if they are set as cover of an OrderLineItemEntity. Background: OrderLineItems automatically get the current cover image of the ordered product when created. As a work-around the module removes the relationship between the product and the image. This causes the image to be no longer visible on the product itself, but it will still serve as the cover of the OrderLineItem. In addition, the image will be renamed according to the following pattern to avoid duplicate file names: " line_item_cover_{product_id}_{timestamp}"


This is the configuration for the mapping of product media:

    "subsections": {
        "product": {
            "enabled": false,
            "identifierWhitelist": [
            "keepOriginalFilenames": false,
            "deleteShopwareOnlyFiles": false