# DataFirefly Image Optimizer — Documentazione Shopware 6

> DataFirefly Image Optimizer trasforma automaticamente ogni immagine media Shopware in varianti WebP e AVIF, ricomprime i JPEG e PNG originali, e riscrive gli URL verso il vostro CDN — senza…

- Pagina: <https://www.datafirefly.com/it/documentation/dfimageoptimizer/>
- Lingua: it
- Aggiornato il: 2026-06-29
- Altre lingue: [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), [de](https://www.datafirefly.com/de/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)
- Indice: <https://www.datafirefly.com/it/documentation/llms.txt>

DataFirefly Image Optimizer trasforma automaticamente ogni immagine media Shopware in varianti WebP e AVIF, ricomprime i JPEG e PNG originali, e riscrive gli URL verso il vostro CDN — senza modifica del tema. Questa documentazione copre installazione, configurazione completa, l'API Twig esposta ai temi, e la risoluzione problemi.

## Installazione

Il plugin è fornito come ZIP. Due metodi di installazione, funzionalmente equivalenti.

### Via amministrazione Shopware

1. Impostazioni → Sistema → Estensioni → Carica estensione
2. Selezionate `DfImageOptimizer-1.0.0.zip`
3. Cliccate su Installa e poi Attiva
4. Svuota cache: Impostazioni → Sistema → Cache e Indici → Svuota

### Via CLI (raccomandato)

```
cd /percorso/a/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
```

**Suggerimento.** `theme:compile` è obbligatorio dopo l'installazione affinché l'override Twig del componente thumbnail sia attivo nello storefront. Senza questa tappa, i tag `` non verranno generati anche se WebP e AVIF sono prodotti.

### Verifica post-installazione

Andate al menu admin **Catalogues → Image Optimizer**. Il dashboard deve apparire con una card _Capacità server_ che indica in tempo reale:

- Versione PHP rilevata (8.2 minimo)
- Presenza Imagick (raccomandato)
- Presenza GD (obbligatorio)
- Supporto effettivo WebP — deve essere ✓
- Supporto effettivo AVIF — può essere ✗ secondo il server, non bloccante
- Motore raccomandato: Imagick o GD

## Architettura in due parole

Quando un'immagine viene caricata, il plugin ascolta l'evento entity `media.written`, carica l'immagine in un file temporaneo locale, poi produce in parallelo:

- L'originale ricompresso (sostituisce il file se _Comprimi originale_ è selezionato)
- Un sibling WebP accanto con estensione cumulativa: `foo.jpg` → `foo.jpg.webp`
- Un sibling AVIF accanto: `foo.jpg` → `foo.jpg.avif`

Le miniature Shopware generate dal `ThumbnailService` nativo vengono elaborate nello stesso modo. Nello storefront, l'override Twig di `storefront/component/image/thumbnail.html.twig` avvolge il tag `` in un `` con sorgenti AVIF, WebP e fallback originale — il browser sceglie automaticamente il formato più leggero supportato.

## Configurazione

Accesso: **Impostazioni → Sistema → Estensioni → DfImageOptimizer → Configura**. Sette card raggruppano le opzioni.

### Card «Generale»

| Opzione | Default | Effetto |
| --- | --- | --- |
| Auto-ottimizza al caricamento | Attivato | Avvia la pipeline subito ad ogni caricamento. Disattivate se preferite elaborare tutto in background via cron. |
| Elabora miniature | Attivato | Genera WebP/AVIF anche per le miniature Shopware (tipicamente 4-6 dimensioni per immagine sorgente). |

### Card «WebP»

| Opzione | Default | Raccomandazione |
| --- | --- | --- |
| Attiva WebP | Attivato | Mantenere attivato salvo caso molto specifico. WebP è supportato dal 96% dei browser. |
| Qualità WebP (1-100) | 82 | 75-85 per buon equilibrio. 90+ per fotografia di fascia alta, 70 per catalogo voluminoso. |
| Lossless per PNG | Disattivato | Attivate solo se i vostri PNG contengono testo o grafica nitida (loghi, icone). Altrimenti modalità lossy dà migliori guadagni. |

### Card «AVIF»

| Opzione | Default | Raccomandazione |
| --- | --- | --- |
| Attiva AVIF | Disattivato | Attivate se il dashboard indica che il vostro server supporta AVIF. Guadagno tipico 50% vs JPEG. |
| Qualità AVIF (1-100) | 55 | 45-65 per rendering eccellente. AVIF tollera qualità più basse di JPEG/WebP. |
| Larghezza massima per AVIF (px) | 2400 | Salvaguardia CPU. Immagini oltre questa larghezza sono saltate per AVIF ma conservano il WebP. |

**Su AVIF.** La codifica AVIF richiede PHP 8.1+ con il flag `IMG_AVIF` compilato, o Imagick con libheif. Il dashboard _Capacità server_ indica esattamente cosa è disponibile.

### Card «Compressione»

| Opzione | Default | Raccomandazione |
| --- | --- | --- |
| Comprimi JPG/PNG originali | Attivato | Sostituisce l'originale con la versione ricompressa. Azione **irreversibile**. |
| Qualità JPEG (1-100) | 85 | 85 è lo standard foto web. Scendere a 80 per guadagno aggiuntivo. |
| Livello compressione PNG (0-9) | 7 | 9 = compressione massima ma 3-4× più lenta. 7 è l'equilibrio standard. |
| Rimuovi metadati EXIF/ICC | Attivato | Guadagno tipico 5 a 30 KB per foto da fotocamera. |

### Card «CDN»

| Opzione | Default | Spiegazione |
| --- | --- | --- |
| Attiva riscrittura CDN | Disattivato | Se disattivato, gli URL puntano alla vostra origin. Attivate dopo configurazione CDN. |
| URL base del CDN | — | Formato: `https://cdn.esempio.com` senza slash finale. |
| Ambito di riscrittura | Solo media | Vedi dettagli sotto. |
| Conserva query string | Attivato | Preserva parametri cache-busting (`?v=1234`). |

**I tre ambiti in dettaglio:**

- **Solo media** — riscrive solo URL che iniziano per `/media/`. Il più sicuro, copre il 95% dei casi d'uso tipici.
- **Media + miniature** — aggiunge `/thumbnail/`.
- **Tutti gli asset statici** — aggiunge anche `/theme/`, `/bundles/` e `/assets/`.

### Card «Rendering frontend»

| Opzione | Default | Effetto |
| --- | --- | --- |
| Uscita come tag `` | Attivato | Avvolge i `` dello storefront in un ``. |
| Aggiungi `loading="lazy"` | Attivato | Lazy-loading nativo browser. |
| Aggiungi `decoding="async"` | Attivato | Permette decodifica in parallelo. |
| Forza `width`/`height` | Attivato | Anti-CLS (Cumulative Layout Shift). |

### Card «Elaborazione batch»

| Opzione | Default | Raccomandazione |
| --- | --- | --- |
| Dimensione batch per task cron | 50 | 50 è buon equilibrio. Aumentare a 100-200 per recupero rapido di grande catalogo. |
| Intervallo cron (minuti) | 15 | Solo informazione — intervallo reale definito in `OptimizeImagesTask::getDefaultInterval()`. |

## Configurare un CDN — esempi concreti

### BunnyCDN (raccomandato)

1. Create una _Pull Zone_ su bunny.net con il vostro URL origin
2. BunnyCDN vi dà un hostname tipo `shop-cdn.b-cdn.net`
3. Nella configurazione plugin, mettete: `https://shop-cdn.b-cdn.net`
4. Scegliete l'ambito _Solo media_ per iniziare
5. Attivate la riscrittura CDN

Il plugin inietta automaticamente `` e `` nell'`` dello storefront — risparmio di 50 a 200 ms.

### Cloudflare

Cloudflare in modalità proxy DNS standard non necessita riscrittura CDN. Ma se usate un _Custom Hostname_ Cloudflare dedicato per asset, configuratelo qui. Attivate anche _Cache Reserve_ o _Polish_.

### KeyCDN

Configurazione identica a BunnyCDN: create una Pull Zone, recuperate l'URL tipo `shop-12345.kxcdn.com`.

### AWS CloudFront

Create una distribuzione CloudFront con il vostro server Shopware come origin. URL distribuzione tipo `https://d1234abc.cloudfront.net`. Configurate il TTL minimo a 1 giorno.

## Pipeline di ottimizzazione dettagliato

Per ogni immagine da elaborare, il plugin esegue questi passi in ordine:

1. Download dell'immagine sorgente dal filesystem pubblico Shopware a file temporaneo locale
2. **Se Comprimi originale attivato**: ricompressione in-place con qualità configurata
3. **Se WebP attivato**: conversione a WebP, scrittura del sibling `foo.jpg.webp`
4. **Se AVIF attivato e larghezza ≤ larghezza massima**: conversione a AVIF
5. Registrazione nella tabella `df_image_optimizer`
6. Pulizia del file temporaneo via blocco `finally`

Imagick viene usato come priorità quando disponibile. GD prende il relevo altrimenti — supporta WebP da molto tempo e AVIF dal PHP 8.1.

**Compressione JPEG originale — irreversibile.** Quando l'opzione _Comprimi originale_ è selezionata, la versione compressa sostituisce l'originale nel filesystem.

## Task pianificato — recupero immagini esistenti

Attivare il plugin su un negozio con già migliaia di immagini non innesca l'ottimizzazione retroattiva. Il task pianificato `df_image_optimizer.optimize_pending` gira ogni 15 minuti di default:

1. Query SQL via LEFT JOIN su `df_image_optimizer` per identificare media non ancora ottimizzati
2. Elabora un batch di 50 immagini (configurabile)
3. Termina e libera il worker

Su un negozio con 10.000 immagini, contate circa 50 ore per recupero totale. Per accelerare:

- Aumentate la dimensione del batch (provate 100 o 200)
- Usate il pulsante **Esegui batch** nel dashboard più volte
- Eseguite il task in loop via 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 ```

## API Twig esposta ai temi

Due helper Twig registrati, utilizzabili in qualsiasi template di tema o plugin.

### Filtro `|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>
```

### Funzione `df_picture()`

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

Genera:

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

## Endpoint API admin

| Metodo | Rotta | Descrizione |
| --- | --- | --- |
| GET | `/api/_action/df-image-optimizer/stats` | Panoramica + attività 30g + capacità server |
| POST | `/api/_action/df-image-optimizer/run-batch` | Esegue un batch. Parametro POST opzionale `batchSize` |
| GET | `/api/_action/df-image-optimizer/capabilities` | Rilevamento server |

## Tabelle create

### `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       Peso originale in byte
bytes_saved       BIGINT       Cumulativo risparmi
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`

Giornale opzionale degli errori. Solo lettura per debug.

## Risoluzione problemi

### «Il dashboard mostra AVIF: Non disponibile»

- **Se GD-only**: verificate `php -m | grep gd` e `php -i | grep AVIF`. Serve PHP 8.1+ e GD compilato con `--with-avif`.
- **Se Imagick disponibile**: verificate `php -r "print_r(Imagick::queryFormats('AVIF'));"`. Vuoto? Il vostro Imagick non è compilato con libheif.
- **Fallback accettabile**: lasciate AVIF disattivato e concentratevi su WebP.

### «Le immagini `.webp` sono generate ma lo storefront mostra JPEG»

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

### «Il caricamento media è diventato lento»

La conversione AVIF è CPU-intensiva. Disattivate l'auto-ottimizzazione al caricamento e lasciate solo il task pianificato elaborare in background.

### «Le miniature `.webp` non sono generate»

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

### «Come svuotare tutti i file WebP/AVIF generati?»

```
cd /percorso/a/shopware
find public/media -name "*.webp" -delete
find public/media -name "*.avif" -delete
```

### «Gli URL CDN non si applicano ovunque»

Verificate l'ambito configurato. URL origin per asset tema con ambito default _Solo media_ sono normali. Passate a _Tutti gli asset statici_.

## Disinstallazione

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

Alla disinstallazione, Shopware chiede se conservare i dati utente:

- **Conservare** (default): le tabelle restano in base.
- **Non conservare**: le due tabelle vengono eliminate (DROP TABLE).

In entrambi i casi, i file `.webp` e `.avif` sul filesystem restano.

## Per andare oltre

- Monitorate il vostro punteggio Core Web Vitals in Google Search Console
- Testate con PageSpeed Insights prima/dopo — guadagno tipico 20-40 punti su mobile
- Attivate anche HTTP/2 o HTTP/3 lato server
- Combinate con cache full-page Shopware