How to: Shopware image urls

How is a Shopware image url generated, let’s dive into it and start really early so everyone can follow.

MediaEntity::getUrl into the Template

This is part of vendor/shopware/storefront/Resources/views/storefront/utilities/thumbnail.html.twig

<img {% if load %}src="{{ media|sw_encode_media_url }}" {% else %}data-src="{{ media|sw_encode_media_url }}" {% endif %}
    {% if media.thumbnails|length > 0 %}
        {% if load %}srcset="{{ srcsetValue }}" {% else %}data-srcset="{{ srcsetValue }}" {% endif %}
        {% if sizes['default'] %}
        sizes="{{ sizes['default'] }}"
        {% elseif sizes|length > 0 %}
        sizes="{{ sizesValue }}"
        {% endif %}
    {% endif %}
    {% for key, value in attributes %}{% if value != '' %} {{ key }}="{{ value }}"{% endif %}{% endfor %}

I’ll just dig down the methods and will sum everything up in the end.


    public function encodeMediaUrl(?MediaEntity $media): ?string
        if ($media === null || !$media->hasFile()) {
            return null;

        return $this->encodeUrl($media->getUrl());

So far so good. So the big question is, where is \Shopware\Core\Content\Media\MediaEntity::getUrl from?

Database to MediaEntity::setUrl

When we start searching, where the url is set on the MediaEntity we’ll find \Shopware\Core\Content\Media\Subscriber\MediaLoadedSubscriber::addUrls, especially the following line:


The method is from an interface (\Shopware\Core\Content\Media\Pathname\UrlGeneratorInterface::getAbsoluteMediaUrl) and implemented here: \Shopware\Core\Content\Media\Pathname\UrlGenerator::getAbsoluteMediaUrl

public function getAbsoluteMediaUrl(MediaEntity $media): string
        return $this->getBaseUrl() . '/' . $this->getRelativeMediaUrl($media);
    public function getRelativeThumbnailUrl(MediaEntity $media, MediaThumbnailEntity $thumbnail): string

        return $this->toPathString([
            $this->pathnameStrategy->generatePhysicalFilename($media, $thumbnail),

All these methods belong to the interface \Shopware\Core\Content\Media\Pathname\PathnameStrategy\PathnameStrategyInterface and are implemented by default in \Shopware\Core\Content\Media\Pathname\PathnameStrategy\IdPathnameStrategy

Why by default?

In your .env file you set a value for SHOPWARE_CDN_STRATEGY_DEFAULT="id" which defines via Shopware\Core\Content\Media\Pathname\PathnameStrategy\StrategyFactory which implementation of the PathnameStrategyInterface to use. The default is id


The following methods are implementation in \Shopware\Core\Content\Media\Pathname\PathnameStrategy\IdPathnameStrategy (or inherited from ancestor classes.


I don’t know why it is needed to generate a md5 hash from a GUID, but people which are smarter than me know. Maybe because it is shorter than the GUID or they don’t want to give away the GUIDs of the images? Another idea I have is to avoid having similar ids and therefore all images would end up in the same directory, but as far as I know GUIDs are built to distribute maximally like most hash algorithms as well (like md5) 🤷

public function generatePathHash(MediaEntity $media, ?MediaThumbnailEntity $thumbnail = null): ?string
        return $this->generateMd5Path($media->getId());


To make sure, that the current image is online and not an old one, the timestamp of the upload is used – important here is to note, that it is NOT the timestamp on the file, but the entry on the database in media.uploaded_at.

    public function generatePathCacheBuster(MediaEntity $media, ?MediaThumbnailEntity $thumbnail = null): ?string
        $uploadedAt = $media->getUploadedAt();

        if ($uploadedAt === null) {
            return null;

        return (string) $uploadedAt->getTimestamp();


And the filename is pretty straight forward, the filename and the extension. In case of a thumbnail the image size is added as a suffix.

    public function generatePhysicalFilename(MediaEntity $media, ?MediaThumbnailEntity $thumbnail = null): string
        $filenameSuffix = '';
        if ($thumbnail !== null) {
            $filenameSuffix = sprintf('_%dx%d', $thumbnail->getWidth(), $thumbnail->getHeight());

        $extension = $media->getFileExtension() ? '.' . $media->getFileExtension() : '';

        return $media->getFileName() . $filenameSuffix . $extension;


The url consists of the following parts, where $media is a MediaEntity:

  • md5($media->getId()) – the first six digits are used and split every 2 character for directories like ab/e3/ed
  • $media->getUploadedAt()->getTimestamp()
  • $media->getFilename()
  • (in case of a thumbnail) _<width>x<height>
  • .<extension>

Media example


Thumbnail example


2 Kommentare zu „How to: Shopware image urls

Kommentar verfassen