SW Shopware 6 Shopware Intermedio

DataFirefly Image Optimizer — Documentazione Shopware 6

Installazione, configurazione WebP/AVIF, integrazione CDN, API Twig e risoluzione problemi del plugin Image Optimizer per Shopware 6.6 e 6.7.

Aggiornato Versione del modulo 1.0.0

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 <picture> 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 <img> in un <picture> 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 <picture> Attivato Avvolge i <img> dello storefront in un <picture>.
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 <link rel="dns-prefetch" href="..."> e <link rel="preconnect" href="..." crossorigin> nell’<head> 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
Questa pagina ti è stata utile?

Ancora bloccato? Contatta l'assistenza