Documentation Content

This pages provides an overview of how media files are handled in synQup and Shopware. This is not intended to be a documentation for the media system in Shopware or synQup. It covers only the basics necessary to understand how the module uploads media files to Shopware.

#Media Handling in synQup

There are two things to consider when dealing with files in synQup and the media-module: Filesystems and Assets.

#Filesystems

Please refer to the core-documentation about filesystems for further information.

This is an example for a local filesystem:

{
    "adapter": "local",
    "adapterConfig": {
        "path": "/path/to/all/images"
    }
}

This is an example for a remote filesystem:

{
    "adapter": "sftp",
    "adapterConfig": {
        "host": "assets.some-customer.example.io",
        "port": 22,
        "root": "/home/assets/public_html/assets",
        "password": "...",
        "username": "..."
    },
    "publicUrlPrefix": "http://assets.some-customer.io/assets/",
    "publicUrlUseFullPath": false
}

These configurations must be inserted to the filesystem table.

#Assets

The transfer model provides the trait Elio\CommonBundle\Traits\AssetGroupAware. By using this trait a document contains an AssetGroupCollection.

The AssetGroupCollection contains elements of type AssetGroup which allows to group assets by different types - e.g. PRODUCT_IMAGE or CATEGORY_IMAGE.

The AssetGroup contains a collection of Asset documents that are the representation of the files to be uploaded to Shopware. The asset contains a FileSystemUri which links the asset to a file of the previously mentioned Filesystem.

There are multiple ways to assign Asset documents to your data. You can either do this manually or use the image bundle. You can find examples how to use the image bundle in the (media guide).

#Media Handling in Shopware

This gives you a simple overview on how the module deals with media files in Shopware. All operations are performed via API. This page presents the API operations that the module performs.

#Media Entities

In general, media files in Shopware are managed by entities of type MediaEntity (table media). Each time you upload a file to Shopware a MediaEntity is persisted. A media entity must be part of a media folder.

There are several entities to which you can assign a single image (e.g. categories) to be displayed. Internally this is a reference to the previously mentioned media-entity.

Obviously, you can assign multiple media files to products. This is done by the help of the ProductMediaEntity ( table product_media) that is a junction table between product-entities and media-entities.

#Media API

#File Upload

In general, the steps to upload a media file to Shopware are the following:

1. Create a MediaEntity that is assigned to a specific media folder
2. Upload a file into that media-entity

We can execute a simple sync api request to create a new media entity:

POST {{_sw_api_url}}/_action/sync

[
    {
        "action": "upsert",
        "entity": "media",
        "payload": [
            {
                "id": "00000000000000000000000000000000",
                "mediaFolderId": "{media_folder_id}",
                "customFields": {
                    "synqup_identifier": "..."
                }
            }
        ]
    }
]

To upload a file into that media-entity the module uses the action API of Shopware. The file must be embedded into the request body. The url has the following structure: {{_sw_api_url}}/_action/media/{{media_entity_id}}/upload?extension={{extension}}&fileName={{filename}}.

To upload a file into our previously created media-entity we use the following request: {{_sw_api_url}}/_action/media/00000000000000000000000000000000/upload?extension=jpg&fileName=test_image

#Media Assignment

To assign this image to an entity (in this case a category) we only have to set a reference to the media-entity that contains our image:

POST {{_sw_api_url}}/_action/sync

[
    {
        "action": "upsert",
        "entity": "category",
        "payload": [
            {
                "id": "bce8d6ced0794755adf982a5f41db521",
                "mediaId": "00000000000000000000000000000000"
            }
        ]
    }
]

#Media Deletion

If we want to remove our file from Shopware we can use a simple delete request: DELETE {{_sw_api_url}}/api/media/f159f9291f554961a7ec6b7d4062f30b

#Product Media Assignment

For products there are some more steps to take care of. The first thing to consider is that you need to create a ProductMediaEntity in order to assign a media-entity to a product. You can combine this with the creation of a media entity:

[
    {
        "action": "upsert",
        "entity": "media",
        "payload": [
            {
                "id": "00000000000000000000000000000001",
                "mediaFolderId": "a5c0949af763453fba7b3bf1ff5e3065",
                "productMedia": [
                    {
                        "id": "00000000000000000000000000000002",
                        "productId": "05d38510eb7faba296755b3dc41b586f"
                    }
                ]
            }
        ]
    }
]

You then have to upload an image to the media-entity as before. Since we have assigned the product-media-entity to the media-entity the image is now visible on our product.

#Product Cover

If you want to set a cover you can update the product:

[
    {
        "action": "upsert",
        "entity": "product",
        "payload": [
            {
                "id": "05d38510eb7faba296755b3dc41b586f",
                "coverId": "00000000000000000000000000000002"
            }
        ]
    }
]

#File Renaming

Send a request to the following API:

{{_sw_api_url}}/_action/media/f159f9291f554961a7ec6b7d4062f30b/rename

{
    "fileName": "new_filename"
}