Rigenerazione delle immagini in PrestaShop: Quando e come ricostruire le miniature

Come PrestaShop gestisce le immagini dei prodotti

Ogni immagine caricata su PrestaShop passa attraverso una pipeline di elaborazione. Quando aggiungi un'immagine prodotto, il sistema memorizza il file originale e poi genera diverse versioni ridimensionate chiamate miniature (thumbnail). Ogni miniatura corrisponde a un tipo di immagine definito nel back office sotto Design > Impostazioni immagini. Questi tipi di immagine specificano dimensioni esatte in pixel e sono legati a contesti specifici: elenchi prodotti, pagine prodotto, anteprime carrello, intestazioni categorie, loghi produttori e altro.

PrestaShop memorizza le immagini nella directory /img/. In PrestaShop 1.7 e 8.x, le immagini dei prodotti sono organizzate usando una struttura di directory basata sull'ID dell'immagine. Ad esempio, un'immagine con ID 1234 è memorizzata in /img/p/1/2/3/4/. All'interno di quella directory, troverai l'immagine originale (denominata per ID, come 1234.jpg) e tutte le miniature generate (come 1234-home_default.jpg, 1234-large_default.jpg, 1234-small_default.jpg).

La convenzione di denominazione segue il pattern: {image_id}-{image_type_name}.{extension}. Questo significa che ogni tipo di immagine che definisci crea un file aggiuntivo per ogni immagine prodotto nel tuo catalogo. Un negozio con 5.000 immagini prodotto e 8 tipi di immagine avrà circa 45.000 file di immagini (5.000 originali più 5.000 per 8 miniature). Questa scala è importante quando devi rigenerarle.

Comprendere i tipi di immagine

I tipi di immagine sono definiti nella tabella del database ps_image_type e gestiti tramite il back office. Ogni tipo di immagine ha un nome, larghezza, altezza e flag che indicano a quali tipi di entità si applica (prodotti, categorie, produttori, fornitori, negozi). L'installazione predefinita di PrestaShop include diversi tipi di immagine:

cart_default è tipicamente 125x125 pixel, usato nel carrello e nel mini carrello. small_default è circa 98x98 pixel, usato negli elenchi prodotti su alcuni temi. medium_default è circa 452x452 pixel, usato per le miniature dei prodotti nella pagina prodotto. home_default è circa 250x250 pixel, usato nella homepage e negli elenchi categorie. large_default è circa 800x800 pixel, usato come immagine principale del prodotto nella pagina prodotto.

I temi possono definire i propri requisiti per i tipi di immagine. Quando installi un nuovo tema, tipicamente registra i suoi tipi di immagine preferiti durante l'installazione. Il punto critico è che i file immagine effettivi su disco devono corrispondere a ciò che il tema si aspetta. Se il tema richiede home_default a 340x340 ma i tuoi file immagine sono stati generati a 250x250 perché usavi un tema diverso in precedenza, ogni elenco prodotti mostrerà immagini con dimensioni errate.

Quando la rigenerazione delle immagini è necessaria

Diverse situazioni richiedono una rigenerazione completa o parziale delle miniature. Comprendere quando è veramente necessaria ti risparmia l'esecuzione di un processo che può richiedere ore su cataloghi di grandi dimensioni.

Cambio tema

Questa è la ragione più comune. Temi diversi richiedono dimensioni immagine diverse. Quando passi da un tema a un altro, i template del nuovo tema fanno riferimento a tipi di immagine con dimensioni specifiche. Se quelle dimensioni non corrispondono ai file miniatura esistenti, le immagini appaiono stirate, ritagliate in modo errato o sfocate. Dopo aver installato un nuovo tema, controlla sempre i suoi requisiti per i tipi di immagine e rigenera le miniature per farle corrispondere.

Modifiche alle dimensioni del tipo di immagine

Se modifichi la larghezza o l'altezza di un tipo di immagine esistente tramite Design > Impostazioni immagini, la modifica influisce solo sulla definizione nel database. Tutti i file miniatura esistenti su disco mantengono le loro vecchie dimensioni. Devi rigenerare le miniature per il tipo di immagine modificato per applicare le nuove dimensioni alle immagini esistenti.

Aggiunta di un nuovo tipo di immagine

Quando crei un nuovo tipo di immagine, non esistono ancora file miniatura per esso. Se un template fa riferimento a questo nuovo tipo di immagine, mostrerà link immagine rotti fino a quando non rigeneri. Il processo di rigenerazione crea i file miniatura mancanti per ogni immagine esistente.

Problemi di qualità delle immagini

Se cambi l'impostazione della qualità di compressione JPEG in PrestaShop (che si trova in Prestazioni > Impostazioni immagini o nella sezione configurazione immagini a seconda della versione), le miniature esistenti sono state generate con la vecchia impostazione di qualità. La rigenerazione applica il nuovo livello di qualità a tutte le miniature.

Dopo una migrazione o spostamento del server

A volte durante la migrazione, i file miniatura vengono persi o corrotti mentre le immagini originali sopravvivono. Se le immagini dei prodotti appaiono rotte ma gli originali esistono nelle directory previste, la rigenerazione ricrea tutte le miniature dagli originali.

Abilitazione del formato WebP

PrestaShop 8.x ha introdotto il supporto WebP per le immagini dei prodotti. Quando abiliti la generazione WebP, le immagini esistenti non ottengono automaticamente le varianti WebP. Devi rigenerare le miniature per creare le versioni .webp accanto ai file JPEG o PNG esistenti.

Rigenerazione tramite il pannello di amministrazione

PrestaShop fornisce uno strumento di rigenerazione integrato nel back office sotto Design > Impostazioni immagini (o Preferenze > Immagini nelle versioni precedenti). In fondo alla pagina troverai la sezione di rigenerazione.

Opzioni disponibili

Puoi scegliere di cancellare le immagini precedenti prima della rigenerazione. Quando abilitato, PrestaShop elimina tutte le miniature esistenti prima di crearne di nuove. Questo è utile quando vuoi rimuovere miniature per tipi di immagine che non esistono più, ma significa che tutte le immagini saranno non disponibili durante il processo di rigenerazione. Quando disabilitato, PrestaShop sovrascrive le miniature esistenti e crea quelle mancanti senza eliminare nulla prima.

Puoi selezionare quali tipi di entità rigenerare: prodotti, categorie, produttori, fornitori o negozi. Se hai cambiato solo le dimensioni delle immagini dei prodotti, non c'è bisogno di rigenerare le immagini delle categorie o dei produttori.

Limitazioni dell'approccio tramite pannello di amministrazione

La rigenerazione tramite pannello di amministrazione viene eseguita come una richiesta web. Questo crea diversi problemi per cataloghi di grandi dimensioni. I server web hanno limiti di tempo di esecuzione, tipicamente da 30 a 300 secondi a seconda della configurazione. Un negozio con 10.000 immagini di prodotti e 8 tipi di immagine deve generare 80.000 file miniatura. Anche a un ritmo generoso di 10 immagini al secondo, ci vogliono più di due ore. La maggior parte dei server web terminerà il processo molto prima che finisca.

Si applicano anche i limiti di memoria. Ogni immagine deve essere caricata in memoria, ridimensionata usando GD o ImageMagick e salvata. Le immagini originali ad alta risoluzione possono consumare da 20 a 50 MB di memoria ciascuna durante l'elaborazione. Il limite di memoria predefinito di PHP di 128 MB o 256 MB può essere esaurito rapidamente, specialmente quando si elaborano immagini in sequenza senza una corretta pulizia della memoria.

Se il processo viene interrotto da un timeout o errore di memoria, ti ritrovi con un catalogo parzialmente rigenerato. Alcuni prodotti hanno le nuove miniature, altri hanno quelle vecchie e alcuni potrebbero non averne affatto. Questo stato incoerente è peggiore del problema originale.

Rigenerazione CLI per cataloghi di grandi dimensioni

Per negozi con più di qualche centinaio di prodotti, la rigenerazione da riga di comando è fortemente raccomandata. Bypassa i limiti di timeout del server web e può essere configurata con limiti di memoria più alti.

Utilizzo della console PrestaShop

PrestaShop 1.7.5 e versioni successive includono una console Symfony. Puoi rigenerare le miniature usando:

php bin/console prestashop:image:regenerate

Questo comando accetta diverse opzioni. Per rigenerare solo tipi di immagine specifici, usa il flag --image-type seguito dal nome del tipo di immagine. Per elaborare solo prodotti, categorie o altri tipi di entità specifici, usa il flag --entity. Il flag --format ti permette di specificare quali formati di output generare (jpg, png, webp).

Esegui il comando dalla directory root di PrestaShop. Se stai usando Docker, eseguilo all'interno del container:

docker exec -u www-data your-container php bin/console prestashop:image:regenerate

Il flag -u www-data assicura che i file generati siano di proprietà dell'utente del server web. Eseguire come root crea file che il server web non può servire o modificare successivamente.

Configurazione di memoria e tempo

Per l'esecuzione CLI, puoi aumentare i limiti PHP direttamente nel comando:

php -d memory_limit=512M -d max_execution_time=0 bin/console prestashop:image:regenerate

Impostare max_execution_time=0 rimuove completamente il limite di tempo, e 512 MB di memoria sono sufficienti per la maggior parte dei cataloghi. Per negozi con originali a risoluzione estremamente alta (4000x4000 pixel o più), potresti aver bisogno di 1 GB o più.

Approccio di rigenerazione personalizzato

Per cataloghi molto grandi (50.000 o più immagini), anche il comando della console può essere lento o problematico. Un approccio PHP personalizzato ti permette di elaborare le immagini in lotti con tracciamento del progresso, gestione degli errori e la possibilità di riprendere dopo un'interruzione.

L'approccio consiste nell'interrogare il database per tutti i record immagine, iterare attraverso di essi in lotti di 100 o 200, generare miniature per ogni immagine e registrare il progresso. Se il processo viene interrotto, puoi riprenderlo da dove si era fermato controllando quali miniature esistono già.

Un approccio a lotti permette anche di distribuire la rigenerazione su più esecuzioni durante le ore di minor traffico, evitando l'impatto sulle prestazioni del negozio attivo.

Generazione WebP durante la rigenerazione

WebP è un formato immagine moderno che fornisce dimensioni di file significativamente più piccole rispetto al JPEG a qualità comparabile. PrestaShop 8.x può generare versioni WebP delle miniature durante il processo di rigenerazione.

Abilitare il supporto WebP

Prima della rigenerazione, abilita WebP nella configurazione di PrestaShop. In PrestaShop 8.x, questa opzione si trova nelle impostazioni immagini. Quando abilitata, il processo di rigenerazione crea sia la miniatura tradizionale JPEG/PNG che una versione .webp per ogni tipo di immagine.

Requisiti del server

La generazione WebP richiede l'estensione GD compilata con supporto WebP (--with-webp) o l'estensione ImageMagick con delegati WebP. Puoi verificare il supporto GD con phpinfo() o gd_info(). Cerca WebP Support nell'output. Se il supporto WebP è mancante, il processo di rigenerazione salta silenziosamente la creazione WebP senza produrre errori.

Considerazioni sullo spazio su disco

I file WebP sono tipicamente dal 25 al 35 percento più piccoli dei file JPEG equivalenti, ma stai memorizzando entrambi i formati. Un negozio con 40.000 miniature JPEG che occupano 2 GB di spazio su disco avrà bisogno di circa 3,4 GB in totale dopo la generazione WebP (i 2 GB originali più circa 1,4 GB di file WebP). Pianifica di conseguenza il tuo spazio su disco prima di avviare una rigenerazione completa.

Servire WebP ai browser

Generare file WebP è solo metà della soluzione. Il tuo tema e server devono essere configurati per servire WebP ai browser che lo supportano, con fallback su JPEG/PNG per i browser che non lo fanno. Questo è tipicamente gestito tramite elementi <picture> nei template del tema o tramite la negoziazione del contenuto lato server usando l'header Accept.

In Apache, puoi aggiungere regole di rewrite che verificano il supporto WebP e servono la versione WebP quando disponibile. In Nginx, la direttiva try_files può verificare se esiste una versione .webp dell'immagine richiesta e servirla se l'header Accept del browser include image/webp.

Impatto sulle prestazioni e mitigazione

La rigenerazione delle immagini è intensiva per la CPU e pesante per l'I/O. Su un negozio attivo, può degradare significativamente le prestazioni se non gestita con attenzione.

Impatto sulla CPU

Ogni operazione di ridimensionamento immagine richiede il caricamento dell'originale in memoria, l'esecuzione dell'algoritmo di ridimensionamento, l'applicazione delle impostazioni di qualità/compressione e la scrittura del risultato su disco. L'operazione di ridimensionamento stessa è computazionalmente costosa, specialmente per immagini grandi ridotte a miniature piccole. Su un ambiente di hosting condiviso, questo può saturare la CPU e rallentare l'intero negozio.

Impatto sull'I/O

La rigenerazione legge ogni immagine originale e scrive diversi file miniatura. Su dischi rigidi tradizionali, questo crea un carico I/O significativo. Su storage SSD, l'impatto è molto minore ma comunque percepibile su larga scala. Il pattern I/O è particolarmente sfavorevole per i dischi rotanti perché comporta letture casuali (originali sparsi tra le directory) combinate con scritture sequenziali (miniature nelle stesse directory).

Eseguire la rigenerazione nelle ore di minor traffico

Programma la rigenerazione nel periodo di traffico più basso. Per i negozi europei, questo è tipicamente tra le 2:00 e le 6:00. Per negozi con traffico globale, potrebbe non esserci un vero momento di basso traffico, ma puoi identificare punti relativamente bassi dai tuoi dati di analytics.

Utilizzo di nice e ionice

Su server Linux, puoi ridurre la priorità del processo di rigenerazione in modo che non privi altri processi delle risorse. Il comando nice abbassa la priorità CPU, e ionice abbassa la priorità I/O:

nice -n 19 ionice -c 3 php bin/console prestashop:image:regenerate

Un valore nice di 19 è la priorità più bassa. La classe ionice 3 è la classe idle, il che significa che il processo ottiene tempo I/O solo quando nient'altro ne ha bisogno. Questo riduce drasticamente l'impatto sul negozio attivo ma rende la rigenerazione più lunga.

Scaling temporaneo

Se sei su un server cloud, considera di aumentare temporaneamente le risorse del server (più core CPU, più RAM, storage più veloce) per la durata della rigenerazione, per poi ridimensionare. Il costo extra di qualche ora di risorse di livello superiore è generalmente minimo rispetto all'impatto di una rigenerazione lenta e multi-giornaliera sulle prestazioni del negozio.

Evitare i timeout durante la rigenerazione

I timeout sono il problema più comune con la rigenerazione delle immagini. Ecco le impostazioni e configurazioni specifiche che li prevengono.

Configurazione PHP

La direttiva max_execution_time limita la durata di esecuzione di un processo PHP. Per l'esecuzione CLI, tipicamente è già impostata a 0 (illimitata), ma verifica controllando php -i | grep max_execution_time. Per la rigenerazione web tramite il pannello di amministrazione, aumenta questo valore nel tuo php.ini o .htaccess:

php_value max_execution_time 7200

Aumenta anche max_input_time se usi il pannello di amministrazione, poiché il timeout di invio del form è separato dal timeout di esecuzione:

php_value max_input_time 7200

Timeout del server web

La direttiva Timeout di Apache e proxy_read_timeout / fastcgi_read_timeout di Nginx possono terminare richieste di lunga durata anche se PHP stesso non è andato in timeout. Per Apache: Timeout 7200. Per Nginx, aggiungi al tuo blocco server: fastcgi_read_timeout 7200; o proxy_read_timeout 7200;.

Configurazione PHP-FPM

Se usi PHP-FPM (come la maggior parte delle configurazioni moderne), il request_terminate_timeout nella configurazione del pool può anche terminare processi di lunga durata. Impostalo a 0 per disabilitare il timeout, o adattalo al tempo massimo di esecuzione desiderato:

request_terminate_timeout = 7200

Timeout di Cloudflare e CDN

Se il tuo negozio è dietro Cloudflare o un altro CDN, il CDN ha il proprio timeout delle richieste (il piano gratuito di Cloudflare ha un timeout di 100 secondi). Questo rende la rigenerazione tramite pannello di amministrazione dietro un CDN effettivamente impossibile. Devi usare la rigenerazione CLI, bypassare il CDN per l'accesso admin, o usare una soluzione che elabori le immagini in modo asincrono.

Strategie di rigenerazione incrementale

La rigenerazione completa elabora ogni immagine nel catalogo. Per negozi con decine di migliaia di immagini, questo può richiedere molte ore. Gli approcci incrementali elaborano solo le immagini che necessitano effettivamente di nuove miniature.

Rigenerazione selettiva del tipo di immagine

Se hai aggiunto o modificato solo un tipo di immagine, non devi rigenerare tutti i tipi. Usa l'opzione --image-type nel comando della console per mirare solo al tipo di immagine specifico che è cambiato. Questo riduce il lavoro a un ottavo (o qualunque frazione dei tuoi tipi di immagine totali) di una rigenerazione completa.

Elaborazione basata sulla data

Se devi rigenerare le miniature solo per prodotti aggiunti di recente (ad esempio, dopo aver risolto un problema di elaborazione immagini), puoi interrogare il database per le immagini aggiunte dopo una data specifica ed elaborare solo quelle. La tabella ps_image non ha una colonna data per impostazione predefinita, ma la tabella associata ps_product ha i campi date_add e date_upd che possono essere usati per identificare i prodotti modificati di recente.

Rilevamento delle miniature mancanti

Invece di rigenerare tutto, scansiona le directory delle immagini per trovare immagini a cui mancano miniature specifiche e rigenera solo quelle. Questo è l'approccio più veloce quando hai aggiunto un nuovo tipo di immagine o quando una rigenerazione parziale è stata interrotta.

La logica è semplice: per ogni ID immagine nel database, verifica se il file miniatura previsto esiste su disco. Se non esiste, rigenera solo quella miniatura. Questo trasforma una rigenerazione completa di diverse ore in un processo mirato che potrebbe richiedere minuti.

Elaborazione parallela

Per cataloghi molto grandi, puoi dividere l'intervallo di ID immagine in blocchi ed elaborarli in parallelo usando più processi PHP. Ad esempio, un processo gestisce gli ID immagine da 1 a 10000, un altro da 10001 a 20000, e così via. Ogni processo funziona indipendentemente, e il throughput combinato è approssimativamente proporzionale al numero di processi paralleli (limitato dai core CPU e dalla larghezza di banda I/O).

Fai attenzione con l'elaborazione parallela e l'I/O disco. Eseguire troppi processi contemporaneamente su un disco rigido tradizionale causerà contesa I/O e rallenterà effettivamente le cose. Su storage SSD, da 4 a 8 processi paralleli funzionano tipicamente bene.

Considerazioni sul formato delle immagini

PrestaShop supporta JPEG, PNG e GIF come formati sorgente e può generare miniature in questi formati più WebP. Il formato sorgente influenza il comportamento della rigenerazione.

Immagini JPEG

JPEG è il formato più comune per le foto dei prodotti. Supporta la compressione lossy, il che significa che ogni volta che un JPEG viene salvato, si perde un po' di qualità. Questo è il motivo per cui rigenerare le miniature dagli upload originali produce risultati migliori rispetto alla rigenerazione da miniature precedentemente ridimensionate. Assicurati sempre di lavorare dall'immagine originale caricata, non da una miniatura precedentemente generata.

Immagini PNG

PNG supporta la trasparenza e la compressione lossless. Se le tue immagini prodotto usano sfondi trasparenti, le miniature PNG preservano quella trasparenza. Tuttavia, i file PNG sono tipicamente molto più grandi dei file JPEG. Considera se hai realmente bisogno della trasparenza. Se no, convertire le immagini prodotto PNG in JPEG durante la rigenerazione può ridurre significativamente lo spazio su disco e migliorare i tempi di caricamento delle pagine.

Gestione GIF

PrestaShop può accettare upload GIF, ma le miniature generate da sorgenti GIF sono statiche (l'animazione non viene preservata). Se hai immagini prodotto GIF animate, sappi che la rigenerazione produce miniature statiche dal primo frame.

Verifica post-rigenerazione

Dopo il completamento della rigenerazione, verifica i risultati prima di presumere che tutto sia corretto.

Controllo visivo della qualità delle immagini

Apri diverse pagine prodotto e ispeziona le immagini visivamente. Verifica che le miniature siano nitide, correttamente proporzionate e non stirate o pixelate. Presta particolare attenzione alle immagini che erano originalmente piccole (vicine o più piccole delle dimensioni della miniatura), poiché queste hanno più probabilità di mostrare problemi di qualità quando ingrandite.

Verifica del conteggio dei file

Confronta il numero di miniature generate con le aspettative. Se hai 5.000 immagini prodotto e 8 tipi di immagine, dovresti avere circa 40.000 file miniatura (più gli originali e potenzialmente le varianti WebP). Un conteggio significativamente inferiore indica che il processo di rigenerazione è stato interrotto o ha incontrato errori su alcune immagini.

Verifica dei permessi dei file

Verifica che i file rigenerati siano di proprietà dell'utente del server web (tipicamente www-data su Debian/Ubuntu o apache su CentOS). Se hai eseguito la rigenerazione come root, i file potrebbero non essere leggibili dal server web, causando immagini rotte nel frontend. Correggi con: chown -R www-data:www-data img/p/.

Pulizia della cache

Dopo la rigenerazione, pulisci tutte le cache. Questo include la cache interna di PrestaShop (Parametri avanzati > Prestazioni), qualsiasi cache opcode (OPcache), e qualsiasi cache CDN o reverse proxy. Le vecchie pagine cachate potrebbero ancora fare riferimento a vecchi URL o dimensioni delle immagini. Se usi un modulo che genera sprite CSS o immagini inline, rigenera anche quelli.

Se il tuo negozio è dietro Cloudflare, purga la cache per il percorso /img/ o fai un purge completo della cache. Cloudflare cacha le immagini aggressivamente, e i visitatori potrebbero vedere vecchie miniature fino alla scadenza o al purge della cache CDN.

Risoluzione dei problemi comuni di rigenerazione

Miniature nere o corrotte

Questo indica solitamente un problema con la libreria GD. L'estensione GD potrebbe non supportare il formato sorgente (ad esempio, GD compilato senza supporto JPEG). Verifica le capacità di GD con gd_info(). Un'altra causa è la memoria insufficiente: se PHP non può allocare abbastanza memoria per caricare l'immagine originale, GD potrebbe produrre un'immagine nera invece di generare un errore.

Dimensioni errate nelle miniature generate

Se le miniature hanno dimensioni inaspettate, controlla le definizioni dei tipi di immagine nel database. Il pannello di amministrazione potrebbe mostrare un valore mentre il database ne contiene un altro (questo può succedere dopo un import fallito o una modifica manuale del database). Interroga direttamente: SELECT * FROM ps_image_type WHERE name = 'home_default';

La rigenerazione si blocca senza progresso

Un processo di rigenerazione bloccato solitamente significa che ha incontrato un'immagine molto grande che ha esaurito la memoria disponibile. Controlla il log degli errori PHP per errori di allocazione memoria. La soluzione è aumentare il limite di memoria o pre-elaborare le immagini sorgente problematiche per ridurne la risoluzione prima della rigenerazione.

Errori di permesso negato

Se la rigenerazione riporta errori di permesso, il processo PHP non può scrivere nelle directory delle immagini. Questo accade comunemente in ambienti Docker dove i volumi bind-mounted hanno proprietà diverse all'interno e all'esterno del container. Assicurati che l'utente che esegue il comando di rigenerazione abbia accesso in scrittura all'intero albero della directory /img/.

Riepilogo

La rigenerazione delle immagini è un'attività di manutenzione che ogni proprietario di negozio PrestaShop incontra, solitamente durante un cambio tema o quando ottimizza le impostazioni delle immagini. Per cataloghi piccoli (sotto 500 prodotti), lo strumento del pannello di amministrazione funziona adeguatamente. Per qualsiasi cosa più grande, la rigenerazione CLI è l'unico approccio affidabile. I principi chiave sono: lavora sempre dalle immagini originali, adatta le definizioni dei tipi di immagine ai requisiti del tuo tema, gestisci proattivamente le risorse del server e i timeout, usa approcci incrementali quando possibile e verifica i risultati dopo il completamento del processo. Con WebP che sta diventando lo standard per le immagini web, la rigenerazione serve anche come meccanismo per creare varianti in formato moderno dell'intero catalogo prodotti, offrendo file di dimensioni ridotte e caricamenti pagina più rapidi ai tuoi clienti.