WebP Media Replacer

WebP Media Replacer è un plugin WordPress admin-only che converte immagini JPG/PNG in WebP,
registra l’allegato WebP e, se attivato sul singolo media, sostituisce runtime URL e srcset con le versioni WebP.
Nato e testato in produzione su AffittiBrevi360.it.

Requisiti hosting

• PHP: 8.0+ (consigliato 8.1/8.2)
• Memory limit: consigliato 256MB+ (meglio 512MB su media pesanti)
• Estensioni: GD con supporto WebP oppure Imagick con supporto WebP
• Permessi: scrittura su wp-content/uploads
• Ambiente: hosting WordPress ottimizzato / VPS consigliato per batch e immagini grandi

Installazione

1. Carica il plugin in /wp-content/plugins/webp-media-replacer/
2. Attiva da WordPress → Plugin
3. Verifica che in Media puoi caricare anche WebP (il plugin abilita il mime image/webp)

Impostazioni

Vai in Impostazioni → WebP Media Replacer.

• Limita srcset alla dimensione richiesta:
  quando il tema richiede un’immagine come array [w,h], evita candidati più grandi di w.
  Utile per temi che generano srcset “troppo generosi”.

Workflow consigliato (Quick Start)

1. Apri un allegato JPG/PNG in Media Library
2. Se hai effettuato crop/resize in WP, prima premi Salva nell’editor immagine
3. (Opzionale) Inserisci Nuovo nome file WebP (senza estensione)
4. Clicca Converti in WebP
5. Clicca Sostituisci nel sito con WebP per attivare runtime replacement
6. Verifica nel frontend che img src e srcset puntino a .webp

Cosa viene salvato (Meta & Opzioni)

Opzioni

• wmr_options:
  • limit_srcset (0/1)

Post Meta sugli allegati

• _wmr_webp_map: mappa size_key → percorso relativo webp
• _wmr_webp_replace_on: flag (1/0) che abilita la sostituzione runtime

Esempio mappa:

{  "full": "2025/12/foto-ottimizzata.webp",  "thumbnail": "2025/12/foto-ottimizzata-150x150.webp",  "medium": "2025/12/foto-ottimizzata-300x300.webp"}

Come funziona la conversione

• Rigenera i metadata con wp_generate_attachment_metadata() per allineare le size all’originale corrente
• Genera WebP per full + tutte le size intermedie
• Opzionale: rinomina i WebP mantenendo i suffissi dimensione (-300x300)
• Registra l’allegato WebP in Media Library (se non esiste già)
• Salva la mappa WebP nel meta dell’allegato originale

Runtime replacement (filtri usati)

Quando la sostituzione è attiva sul media, il plugin interviene su:

• wp_get_attachment_image_src → sostituisce URL dell’immagine servita
• wp_get_attachment_image_url → sostituisce URL in base a size richiesta
• wp_calculate_image_srcset → sostituisce candidati srcset + limita candidati troppo grandi
• wp_calculate_image_sizes → (opzionale) rende coerente l’attributo sizes per richieste array

Nota: la sostituzione avviene solo se _wmr_webp_replace_on = 1 sull’allegato.
Quindi è una scelta controllata, non globale.

Troubleshooting

1) “Conversione fallita. Verifica che GD/Imagick supportino WebP.”

• Controlla che GD supporti WebP (non basta “GD installato”)
• Oppure abilita Imagick con WebP sul server
• Aumenta memory limit se l’immagine è grande

2) Srcset contiene misure più grandi dell’originale

• Il plugin rimuove sempre candidati più larghi della width reale del full
• Se il tema richiede [w,h], attiva “Limita srcset alla dimensione richiesta” nelle impostazioni

3) Non vedo i bottoni in Media

• Serve capability upload_files
• I bottoni appaiono solo per JPG/JPEG/PNG

4) Ho rinominato e alcuni contenuti puntano ancora al vecchio file

• Usa il tasto “Sostituisci nel sito con WebP”
• Se il contenuto è in builder/page builder, potrebbe essere salvato in meta dedicati: in quel caso va gestito con patch mirata

Assistenza e migliorie

Per suggerimenti, nuove feature o adattamenti su misura,
puoi contattarmi tramite l’area Assistenza Ticket,
categoria: “Plugin WordPress”.