# DataFirefly Image Optimizer — Shopware 6 Dokumentation

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

- Seite: <https://www.datafirefly.com/de/documentation/dfimageoptimizer/>
- Sprache: de
- Aktualisiert am: 2026-06-29
- Weitere Sprachen: [fr](https://www.datafirefly.com/documentation/dfimageoptimizer/index.md), [en](https://www.datafirefly.com/en/documentation/dfimageoptimizer/index.md), [es](https://www.datafirefly.com/es/documentation/dfimageoptimizer/index.md), [it](https://www.datafirefly.com/it/documentation/dfimageoptimizer/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfimageoptimizer/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfimageoptimizer/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfimageoptimizer/index.md)
- Index: <https://www.datafirefly.com/de/documentation/llms.txt>

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 ``-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 ``-Tag in einem `` 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 ``-Tag | Aktiviert | Wrappt Storefront-``-Tags in einen ``. |
| `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 `` und `` im Storefront-`` — 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