SW Shopware 6 Shopware Mittel

DataFirefly Image Optimizer — Shopware 6 Dokumentation

Installation, WebP/AVIF-Konfiguration, CDN-Integration, Twig-API und Fehlerbehebung des Image Optimizer Plugins für Shopware 6.6 und 6.7.

Aktualisiert Modulversion 1.0.0

DataFirefly Image Optimizer wandelt automatisch jedes Shopware-Medienbild in WebP- und AVIF-Varianten um, komprimiert Original-JPEGs und PNGs neu und schreibt URLs zu Ihrem CDN um — ohne Theme-Änderung. Diese Dokumentation behandelt Installation, vollständige Konfiguration, die Themes verfügbare Twig-API und Fehlerbehebung.

Installation

Das Plugin wird als ZIP ausgeliefert. Zwei funktional äquivalente Installationsmethoden.

Via Shopware-Administration

  1. Einstellungen → System → Erweiterungen → Erweiterung hochladen
  2. Wählen Sie DfImageOptimizer-1.0.0.zip
  3. Klicken Sie auf Installieren und dann Aktivieren
  4. Cache leeren: Einstellungen → System → Cache & Indexe → Leeren

Via CLI (empfohlen)

cd /pfad/zu/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
Tipp. theme:compile ist nach der Installation obligatorisch, damit der Twig-Override der Thumbnail-Komponente im Storefront aktiv wird. Ohne diesen Schritt werden <picture>-Tags nicht generiert, auch wenn WebP und AVIF erzeugt werden.

Post-Installations-Überprüfung

Gehen Sie im Admin-Menü zu Catalogues → Image Optimizer. Das Dashboard sollte mit einer Serverfähigkeiten-Karte angezeigt werden, die in Echtzeit zeigt:

  • Erkannte PHP-Version (mindestens 8.2)
  • Imagick-Präsenz (empfohlen)
  • GD-Präsenz (erforderlich)
  • Effektiver WebP-Support — sollte ✓ sein
  • Effektiver AVIF-Support — kann je nach Server ✗ sein, nicht blockierend
  • Empfohlene Engine: Imagick oder GD

Architektur in zwei Worten

Beim Bild-Upload hört das Plugin auf das Entity-Event media.written, lädt das Bild in eine lokale Temp-Datei und produziert dann parallel:

  • Das neukomprimierte Original (ersetzt die Datei, wenn Original komprimieren aktiviert ist)
  • Ein WebP-Geschwister daneben mit kumulativer Erweiterung: foo.jpg → foo.jpg.webp
  • Ein AVIF-Geschwister daneben: foo.jpg → foo.jpg.avif

Shopware-Thumbnails, die vom nativen ThumbnailService generiert werden, werden auf dieselbe Weise verarbeitet. Im Storefront wrappt der Twig-Override von storefront/component/image/thumbnail.html.twig den <img>-Tag in einem <picture> mit AVIF-, WebP- und Original-Fallback-Quellen — der Browser wählt automatisch das leichteste unterstützte Format.

Konfiguration

Zugriff: Einstellungen → System → Erweiterungen → DfImageOptimizer → Konfigurieren. Sieben Karten gruppieren die Optionen.

Karte „Allgemein“

Option Standard Wirkung
Auto-Optimierung beim Upload Aktiviert Löst die Pipeline sofort bei jedem Upload aus. Deaktivieren, wenn Sie alles im Hintergrund via Cron verarbeiten möchten.
Thumbnails verarbeiten Aktiviert Generiert WebP/AVIF auch für Shopware-Thumbnails (typischerweise 4-6 Größen pro Quellbild).

Karte „WebP“

Option Standard Empfehlung
WebP aktivieren Aktiviert Aktiviert lassen, außer in sehr spezifischen Fällen. WebP wird von 96% der Browser unterstützt.
WebP-Qualität (1-100) 82 75-85 für gutes Gleichgewicht. 90+ für High-End-Fotografie, 70 für umfangreichen Katalog.
Lossless für PNG Deaktiviert Nur aktivieren, wenn Ihre PNGs Text oder scharfe Grafiken enthalten (Logos, Icons). Sonst gibt der Lossy-Modus bessere Gewinne.

Karte „AVIF“

Option Standard Empfehlung
AVIF aktivieren Deaktiviert Aktivieren Sie, wenn das Dashboard anzeigt, dass Ihr Server AVIF unterstützt. Typischer Gewinn 50% gegenüber JPEG.
AVIF-Qualität (1-100) 55 45-65 für ausgezeichnetes Rendering. AVIF toleriert niedrigere Qualitäten als JPEG/WebP.
Maximale Breite für AVIF (px) 2400 CPU-Schutz. Bilder oberhalb werden für AVIF übersprungen, behalten aber ihr WebP.
Über AVIF. AVIF-Encoding benötigt entweder PHP 8.1+ mit dem IMG_AVIF-Flag kompiliert oder Imagick mit libheif. Das Dashboard Serverfähigkeiten zeigt genau an, was verfügbar ist.

Karte „Komprimierung“

Option Standard Empfehlung
Original-JPG/PNG komprimieren Aktiviert Ersetzt das Original durch seine neukomprimierte Version. Unumkehrbar.
JPEG-Qualität (1-100) 85 85 ist der Web-Foto-Standard. Auf 80 senken für zusätzlichen Gewinn.
PNG-Kompressionslevel (0-9) 7 9 = maximale Kompression, aber 3-4× langsamer. 7 ist Standardgleichgewicht.
EXIF/ICC-Metadaten entfernen Aktiviert Typischer Gewinn 5 bis 30 KB pro Kamera-Foto.

Karte „CDN“

Option Standard Erklärung
CDN-URL-Umschreibung aktivieren Deaktiviert Wenn deaktiviert, zeigen URLs auf Ihr Origin. Aktivieren Sie nach CDN-Konfiguration.
CDN-Basis-URL — Format: https://cdn.beispiel.de ohne abschließenden Slash.
Umschreibungs-Geltungsbereich Nur Medien Siehe Details unten.
Query-Strings beibehalten Aktiviert Bewahrt Cache-Busting-Parameter (?v=1234).

Die drei Geltungsbereiche im Detail:

  • Nur Medien — schreibt nur URLs um, die mit /media/ beginnen. Sicherster, deckt 95% typischer Anwendungsfälle ab.
  • Medien + Thumbnails — fügt /thumbnail/ hinzu.
  • Alle statischen Assets — fügt auch /theme/, /bundles/ und /assets/ hinzu.

Karte „Frontend-Rendering“

Option Standard Wirkung
Ausgabe als <picture>-Tag Aktiviert Wrappt Storefront-<img>-Tags in einen <picture>.
loading="lazy" hinzufügen Aktiviert Natives Browser-Lazy-Loading.
decoding="async" hinzufügen Aktiviert Erlaubt parallele Dekodierung.
width/height erzwingen Aktiviert Anti-CLS (Cumulative Layout Shift).

Karte „Batch-Verarbeitung“

Option Standard Empfehlung
Batch-Größe für Cron-Task 50 50 ist gutes Gleichgewicht. Erhöhen auf 100-200 für schnelles Aufholen.
Cron-Intervall (Minuten) 15 Nur Information — tatsächliches Intervall definiert in OptimizeImagesTask::getDefaultInterval().

Ein CDN konfigurieren — konkrete Beispiele

BunnyCDN (empfohlen)

  1. Erstellen Sie eine Pull Zone auf bunny.net mit Ihrer Origin-URL
  2. BunnyCDN gibt Ihnen einen Hostname wie shop-cdn.b-cdn.net
  3. In der Plugin-Konfiguration setzen: https://shop-cdn.b-cdn.net
  4. Wählen Sie den Geltungsbereich Nur Medien zum Starten
  5. Aktivieren Sie CDN-Umschreibung

Das Plugin injiziert automatisch <link rel="dns-prefetch" href="..."> und <link rel="preconnect" href="..." crossorigin> im Storefront-<head> — Ersparnis von 50 bis 200 ms.

Cloudflare

Cloudflare im Standard-DNS-Proxy-Modus benötigt keine CDN-Umschreibung. Aber wenn Sie einen dedizierten Cloudflare Custom Hostname für Assets verwenden, konfigurieren Sie ihn hier. Aktivieren Sie auch Cache Reserve oder Polish.

KeyCDN

Konfiguration identisch zu BunnyCDN: erstellen Sie eine Pull Zone, holen Sie die URL vom Typ shop-12345.kxcdn.com.

AWS CloudFront

Erstellen Sie eine CloudFront-Distribution mit Ihrem Shopware-Server als Origin. Distribution-URL ist vom Typ https://d1234abc.cloudfront.net. Konfigurieren Sie das Mindest-TTL auf 1 Tag.

Detaillierte Optimierungs-Pipeline

Für jedes Bild zur Verarbeitung führt das Plugin diese Schritte in der Reihenfolge aus:

  1. Download des Quellbilds vom Shopware-Public-Filesystem in eine lokale Temp-Datei
  2. Wenn Original komprimieren aktiviert: In-Place-Neukompression mit konfigurierter Qualität
  3. Wenn WebP aktiviert: Konvertierung zu WebP, Schreiben des Geschwisters foo.jpg.webp
  4. Wenn AVIF aktiviert und Breite ≤ Max-Breite: Konvertierung zu AVIF
  5. Aufzeichnung in df_image_optimizer-Tabelle
  6. Aufräumen der lokalen Temp-Datei via finally-Block

Imagick wird priorisiert verwendet, wenn verfügbar. GD übernimmt sonst — es unterstützt WebP seit Langem und AVIF seit PHP 8.1.

Original-JPEG-Kompression — unumkehrbar. Wenn die Option Original komprimieren aktiviert ist, ersetzt die komprimierte Version das Original im Filesystem.

Scheduled Task — bestehende Bilder aufholen

Die Aktivierung des Plugins in einem Shop mit bereits Tausenden von Bildern löst die retroaktive Optimierung nicht aus. Stattdessen läuft der Scheduled Task df_image_optimizer.optimize_pending standardmäßig alle 15 Minuten:

  1. SQL-Abfrage via LEFT JOIN auf df_image_optimizer zur Identifizierung noch nicht optimierter Medien
  2. Verarbeitet einen Batch von 50 Bildern (konfigurierbar)
  3. Beendet und gibt den Worker frei

Bei einem Shop mit 10.000 Bildern rechnen Sie mit etwa 50 Stunden zum vollständigen Aufholen. Zur Beschleunigung:

  • Erhöhen Sie die Batch-Größe (versuchen Sie 100 oder 200)
  • Verwenden Sie den Batch ausführen-Button im Dashboard mehrfach
  • Führen Sie den Task in einer Schleife via CLI aus: 
    for i in {1..100}; do sudo -u www-data setsid php bin/console scheduled-task:run-single df_image_optimizer.optimize_pending; done

Themes ausgesetzte Twig-API

Zwei Twig-Helfer registriert, verwendbar in jedem Theme- oder Plugin-Template.

Filter |df_cdn

<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>

Funktion df_picture()

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

Generiert:

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

Admin-API-Endpunkte

Methode Route Beschreibung
GET /api/_action/df-image-optimizer/stats Übersicht + 30-Tage-Aktivität + Serverfähigkeiten
POST /api/_action/df-image-optimizer/run-batch Führt einen Batch aus. Optionaler Parameter batchSize
GET /api/_action/df-image-optimizer/capabilities Server-Erkennung

Erstellte Tabellen

df_image_optimizer

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       Originalgewicht in Bytes
bytes_saved       BIGINT       Kumulative Einsparungen
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

Optionales Fehlerprotokoll. Nur-Lesen zum Debugging.

Fehlerbehebung

„Dashboard zeigt AVIF: Nicht verfügbar“

  • GD-only: prüfen Sie php -m | grep gd und php -i | grep AVIF. PHP 8.1+ und GD mit --with-avif kompiliert nötig.
  • Imagick verfügbar: prüfen Sie php -r "print_r(Imagick::queryFormats('AVIF'));". Leer? Ihr Imagick ist nicht mit libheif kompiliert.
  • Akzeptabler Fallback: AVIF deaktiviert lassen und auf WebP konzentrieren.

„.webp-Dateien werden generiert, aber Storefront zeigt JPEG“

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

„Medien-Upload ist langsam geworden“

AVIF-Konvertierung ist CPU-intensiv. Deaktivieren Sie Auto-Optimierung beim Upload und lassen Sie nur den Scheduled Task im Hintergrund verarbeiten.

„Thumbnail-.webp-Dateien werden nicht generiert“

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

„Wie lösche ich alle generierten WebP/AVIF-Dateien?“

cd /pfad/zu/shopware
find public/media -name "*.webp" -delete
find public/media -name "*.avif" -delete

„CDN-URLs werden nicht überall angewendet“

Prüfen Sie den konfigurierten Geltungsbereich. Origin-URLs für Theme-Assets mit Standard-Nur Medien sind normal. Wechseln Sie zu Alle statischen Assets.

Deinstallation

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

Bei der Deinstallation fragt Shopware, ob Benutzerdaten erhalten bleiben:

  • Erhalten (Standard): Tabellen bleiben in der Datenbank.
  • Nicht erhalten: Beide Tabellen werden gelöscht (DROP TABLE).

In beiden Fällen bleiben .webp– und .avif-Dateien im Filesystem erhalten.

Weitergehende Schritte

  • Beobachten Sie Ihre Core Web Vitals in Google Search Console
  • Testen Sie mit PageSpeed Insights vorher/nachher — typischer Gewinn 20-40 Punkte mobil
  • Aktivieren Sie auch HTTP/2 oder HTTP/3 serverseitig
  • Kombinieren mit Shopware Full-Page-Cache
War diese Seite hilfreich?

Immer noch nicht weiter? Support kontaktieren