DataFirefly Image Optimizer: documentatie Shopware 6

DataFirefly Image Optimizer zet elke Shopware-mediabestand automatisch om in WebP- en AVIF-varianten, hercomprimeert de originele JPEG- en PNG-bestanden en herschrijft de URL’s naar uw CDN, zonder wijzigingen aan het thema. Deze documentatie behandelt de installatie, de volledige configuratie, de Twig-API die aan thema’s wordt aangeboden en de probleemoplossing.

Installatie

De plugin wordt als ZIP geleverd. Er zijn twee installatiemethodes, functioneel gelijkwaardig.

Via de Shopware-administration

1. Instellingen → Systeem → Extensies → Extensie uploaden
2. Selecteer DfImageOptimizer-1.0.0.zip
3. Klik op Installeren en daarna op Activeren
4. Leeg de cache: Instellingen → Systeem → Cache en index → Legen

Via de CLI (aanbevolen)

cd /pad/naar/shopware
unzip DfImageOptimizer-1.0.0.zip -d custom/plugins/

sudo -u www-data setsid php bin/console plugin:refresh
sudo -u www-data setsid php bin/console plugin:install --activate DfImageOptimizer
sudo -u www-data setsid php bin/console cache:clear
sudo -u www-data setsid php bin/console theme:compile

Controle na de installatie

Ga naar het adminmenu Catalogi → Image Optimizer. Het dashboard moet verschijnen met een kaart Servercompatibiliteit die in realtime het volgende toont:

• Gedetecteerde PHP-versie (minimaal 8.2)
• Aanwezigheid van Imagick (aanbevolen)
• Aanwezigheid van GD (verplicht)
• Effectieve WebP-ondersteuning, moet ✓ zijn
• Effectieve AVIF-ondersteuning, kan ✗ zijn afhankelijk van de server, niet blokkerend
• Aanbevolen engine: Imagick of GD

Architectuur in het kort

Wanneer er een afbeelding wordt geüpload, luistert de plugin naar het entiteitsevent media.written, laadt de afbeelding in een lokaal tijdelijk bestand en produceert daarna parallel:

• Het hergecomprimeerde origineel (vervangt het oorspronkelijke bestand als Origineel comprimeren is aangevinkt)
• Een WebP-sibling ernaast met gestapelde extensie: foo.jpg → foo.jpg.webp
• Een AVIF-sibling ernaast: foo.jpg → foo.jpg.avif

De Shopware-miniaturen die door de native ThumbnailService worden gegenereerd, worden op dezelfde manier verwerkt. Aan storefrontzijde wikkelt de Twig-override van storefront/component/image/thumbnail.html.twig de <img>-tag in een <picture> met bronnen voor AVIF en WebP en een terugval op het origineel; de browser kiest automatisch het lichtste formaat dat hij ondersteunt.

Configuratie

Toegang: Instellingen → Systeem → Extensies → DfImageOptimizer → Configureren. Zeven kaarten bundelen de opties.

Kaart “Algemeen”

Kaart “WebP”

Kaart “AVIF”

Kaart “Compressie”

Kaart “CDN”

Details van de drie bereiken:

• Alleen media: herschrijft uitsluitend de URL’s die met /media/ beginnen. Dit is het veiligst en dekt 95 % van de gangbare gevallen.
• Media en miniaturen: voegt /thumbnail/ toe. Nuttig als uw storefront veel dynamisch gegenereerde miniaturen serveert.
• Alle statische assets: voegt /theme/, /bundles/ en /assets/ toe. Kies deze optie alleen als uw CDN correct is ingesteld om alle assets te pull-cachen en u dit in een stagingomgeving hebt getest.

Kaart “Weergave in de frontend”

Kaart “Batchverwerking”

Een CDN instellen, concrete voorbeelden

BunnyCDN (aanbevolen)

1. Maak op bunny.net een Pull Zone aan met uw origin-URL, bijvoorbeeld https://shop.voorbeeld.com
2. BunnyCDN geeft u een hostname van het type shop-cdn.b-cdn.net
3. Vul in de configuratie van de plugin in: https://shop-cdn.b-cdn.net
4. Kies om te beginnen het bereik Alleen media
5. Activeer de CDN-herschrijving

De plugin voegt automatisch <link rel="dns-prefetch" href="https://shop-cdn.b-cdn.net"> en <link rel="preconnect" href="https://shop-cdn.b-cdn.net" crossorigin> toe in de head van de storefront, goed voor 50 tot 200 ms winst op de eerste CDN-aanvraag.

Cloudflare

Cloudflare in de standaard DNS-proxymodus vereist geen CDN-herschrijving, want Cloudflare cachet automatisch op uw hoofdhostname. Gebruikt u echter een eigen Custom Hostname van Cloudflare voor de assets (bijvoorbeeld cdn.voorbeeld.com), stel die dan hier in. Activeer aan de kant van Cloudflare ook Cache Reserve of Polish om bovenop uw eigen optimalisatie van die van Cloudflare te profiteren.

KeyCDN

De configuratie is identiek aan die van BunnyCDN: maak een Pull Zone aan, haal de URL van het type shop-12345.kxcdn.com op en stel die in de plugin in met het voorvoegsel https://.

AWS CloudFront

Maak een CloudFront-distributie aan met uw Shopware-server als origin. De distributie-URL is van het type https://d1234abc.cloudfront.net, of uw eigen domein als u een alias hebt ingesteld. Stel de minimale TTL in op 1 dag om de cache volledig te benutten.

De optimalisatiepijplijn in detail

Voor elke te verwerken afbeelding (origineel of miniatuur) voert de plugin de volgende stappen in deze volgorde uit:

1. Downloaden van de bronafbeelding van het publieke Shopware-filesystem naar een lokaal tijdelijk bestand (/tmp/dfimgopt_xxx.jpg)
2. Als Origineel comprimeren actief is: hercompressie ter plaatse met de ingestelde kwaliteit en verwijdering van de metadata indien geactiveerd. Is de hergecomprimeerde versie kleiner dan het origineel, dan vervangt ze het oorspronkelijke bestand op het filesystem.
3. Als WebP actief is: conversie naar WebP en wegschrijven van de sibling foo.jpg.webp op het publieke filesystem
4. Als AVIF actief is en de breedte ≤ de maximale breedte: conversie naar AVIF en wegschrijven van de sibling foo.jpg.avif
5. Registratie in de tabel df_image_optimizer met tellers en de bespaarde omvang
6. Opruimen van het lokale tijdelijke bestand via een finally-blok (ook bij een fout)

Imagick krijgt voorrang wanneer die beschikbaar is (betere kwaliteit en op veel servers de enige AVIF-engine via libheif). Anders neemt GD het over; die ondersteunt WebP al lang en AVIF sinds PHP 8.1.

Geplande taak, bestaande afbeeldingen inhalen

De plugin activeren op een shop met al duizenden afbeeldingen in de database start geen optimalisatie met terugwerkende kracht. Dat is bewust: 50.000 afbeeldingen in één keer naar AVIF omzetten zou uw server verzadigen. In plaats daarvan draait de geplande taak df_image_optimizer.optimize_pending standaard elke 15 minuten:

1. SQL-query via LEFT JOIN op df_image_optimizer om de nog niet geoptimaliseerde media te vinden
2. Verwerking van een batch van 50 afbeeldingen (batchgrootte instelbaar)
3. Afronden en de worker vrijgeven voor de volgende taak

Op een shop met 10.000 afbeeldingen duurt het ongeveer 50 uur om alles op de achtergrond in te halen. Om te versnellen:

• Verhoog de batchgrootte in de configuratie (probeer 100 of 200)
• Gebruik de knop Batch starten in het dashboard meerdere keren achter elkaar
• Voer de taak handmatig in een lus uit via de CLI:

  for i in {1..100}; do sudo -u www-data setsid php bin/console scheduled-task:run-single df_image_optimizer.optimize_pending; done

Twig-API voor thema’s

Er worden twee Twig-helpers geregistreerd die u in elk thema- of plugintemplate kunt gebruiken.

Filter |df_cdn

Herschrijft een URL naar het CDN indien geactiveerd, en geeft anders de URL ongewijzigd terug. Nuttig voor assets die u handmatig invoegt.

<img src="{{ media.url|df_cdn }}" alt="...">
<link rel="preload" as="image" href="{{ heroImage.url|df_cdn }}">
<style>
    .hero { background-image: url("{{ bgImage.url|df_cdn }}"); }
</style>

Functie df_picture()

Rendert een volledige <picture>-tag met AVIF- en WebP-bronnen en een terugval op het origineel, plus alle ingestelde attributen (lazy, async, width/height).

{{ df_picture(
    media,
    alt='Toegankelijke beschrijving',
    classes='product-image card-img',
    sizes='(max-width: 768px) 100vw, 50vw'
) }}

Genereert:

<picture>
    <source type="image/avif"
            srcset="https://cdn.voorbeeld.com/media/foo.jpg.avif"
            sizes="(max-width: 768px) 100vw, 50vw">
    <source type="image/webp"
            srcset="https://cdn.voorbeeld.com/media/foo.jpg.webp"
            sizes="(max-width: 768px) 100vw, 50vw">
    <img src="https://cdn.voorbeeld.com/media/foo.jpg"
         alt="Toegankelijke beschrijving"
         class="product-image card-img"
         sizes="(max-width: 768px) 100vw, 50vw"
         loading="lazy"
         decoding="async"
         width="1200"
         height="800">
</picture>

Admin API-endpoints

Er zijn drie REST-endpoints beschikbaar, geauthenticeerd via het standaard Bearer-token van de admin.

Voorbeeld met curl:

TOKEN=$(curl -s -X POST https://shop.voorbeeld.com/api/oauth/token 
    -H "Content-Type: application/json" 
    -d '{"grant_type":"password","client_id":"administration","scope":"write","username":"admin","password":"shopware"}' 
    | jq -r .access_token)

curl -X POST https://shop.voorbeeld.com/api/_action/df-image-optimizer/run-batch 
    -H "Authorization: Bearer $TOKEN" 
    -H "Content-Type: application/json" 
    -d '{"batchSize":200}'

Aangemaakte tabellen

df_image_optimizer

Eén regel per geoptimaliseerd mediabestand. Unieke sleutel op media_id: een nieuwe optimalisatie van hetzelfde bestand overschrijft de regel.

id                BINARY(16)   UUID
media_id          BINARY(16)   FK media.id ON DELETE CASCADE, UNIQUE
has_webp          TINYINT(1)
has_avif          TINYINT(1)
compressed        TINYINT(1)
original_size     BIGINT       Oorspronkelijke omvang in bytes
bytes_saved       BIGINT       Totale besparing (compressie plus delta WebP/AVIF)
sales_channel_id  BINARY(16)   FK sales_channel.id ON DELETE SET NULL
optimized_at      DATETIME(3)
created_at        DATETIME(3)

df_image_optimizer_log

Optioneel foutenlogboek. Alleen-lezen voor debugging, zonder automatische opschoning.

Probleemoplossing

“Het dashboard toont AVIF: niet beschikbaar”

Uw server beschikt niet over de vereiste AVIF-stack. Opties:

• Als u alleen GD hebt: controleer php -m | grep gd en php -i | grep AVIF. U hebt PHP 8.1+ en GD gecompileerd met --with-avif nodig. Op recente Debian- en Ubuntu-versies is dat standaard.
• Als Imagick beschikbaar is: controleer php -r "print_r(Imagick::queryFormats('AVIF'));". Leeg? Dan is uw Imagick niet met libheif gecompileerd: opnieuw compileren of overschakelen op GD.
• Aanvaardbare terugval: laat AVIF uitgeschakeld en concentreer u op WebP. De winst van WebP alleen is al enorm ten opzichte van de native JPEG van Shopware.

“De .webp-bestanden worden wel gegenereerd maar de storefront toont JPEG”

De themacompiler heeft de Twig-override niet meegenomen. Oplossing:

sudo -u www-data setsid php bin/console theme:compile
sudo -u www-data setsid php bin/console cache:clear

Controleer daarna met de DevTools van de browser (Chrome of Firefox): open het tabblad Netwerk, herlaad een productpagina en bekijk het MIME-type van de geladen afbeeldingen. U zou image/avif of image/webp moeten zien in plaats van image/jpeg.

“Het uploaden van media is traag geworden”

Vooral de AVIF-conversie is CPU-intensief: reken op 1 tot 3 seconden per afbeelding. Is dat hinderlijk, schakel dan de automatische optimalisatie bij upload uit (kaart Algemeen) en laat alleen de geplande taak op de achtergrond werken. De uploads worden dan weer direct en de afbeeldingen zijn binnen maximaal 15 minuten geoptimaliseerd.

“De .webp-miniaturen worden niet gegenereerd”

Controleer of Miniaturen verwerken is aangevinkt op de kaart Algemeen. Genereer daarna de miniaturen handmatig opnieuw zodat ze de pijplijn opnieuw doorlopen:

sudo -u www-data setsid php bin/console media:generate-thumbnails

“Hoe verwijder ik alle gegenereerde WebP- en AVIF-bestanden?”

De plugin verwijdert ze niet automatisch, ook niet bij het verwijderen van de plugin (om uw back-ups te sparen). Om ze handmatig op te ruimen:

cd /pad/naar/shopware
find public/media -name "*.webp" -delete
find public/media -name "*.avif" -delete

“De CDN-URL’s worden niet overal toegepast”

Controleer het ingestelde bereik. Ziet u origin-URL’s voor thema-assets (/theme/.../style.css), dan is dat normaal bij het standaardbereik Alleen media. Ga naar Alle statische assets als uw CDN is ingesteld om alle assets te serveren.

Let er ook op dat de herschreven URL’s de Twig-weergave aan serverzijde betreffen. Roept uw frontend de Store API aan en bouwt hij de URL’s aan JavaScript-zijde opnieuw op, dan moet u de herschrijving aan de clientzijde apart toepassen.

Verwijderen

sudo -u www-data setsid php bin/console plugin:uninstall DfImageOptimizer
sudo -u www-data setsid php bin/console plugin:remove DfImageOptimizer

Bij het verwijderen vraagt Shopware of u de gebruikersgegevens wilt behouden:

• Behouden (standaard): de tabellen df_image_optimizer en df_image_optimizer_log blijven in de database staan. Bij een herinstallatie wordt de geschiedenis hervat.
• Niet behouden: de twee tabellen worden verwijderd (DROP TABLE).

In beide gevallen blijven de bestanden .webp en .avif op het filesystem staan; gebruik de bovenstaande find-commando’s om ze zo nodig op te ruimen.

Verder gaan

• Volg uw Core Web Vitals-score in Google Search Console: de LCP hoort binnen 2 tot 4 weken na de activering te dalen
• Test met PageSpeed Insights vóór en na: typische winst van 20 tot 40 punten op mobiel
• Activeer aan serverzijde ook HTTP/2 of HTTP/3 om het voordeel van het CDN te vergroten
• Combineer dit met een full page cache van Shopware voor statische responstijden