PrestaShop Pagina Bianca Dopo l'Aggiornamento del Core: Guida al Ripristino

Perché le Pagine Bianche Si Verificano Dopo gli Aggiornamenti di PrestaShop

Una pagina bianca vuota, spesso chiamata White Screen of Death (WSOD), è uno dei problemi più comuni e allarmanti che i proprietari di negozi PrestaShop affrontano dopo l'aggiornamento del software core. Avvii un aggiornamento dalla versione 1.7.8.7 alla 1.7.8.8, o dalla 8.1.0 alla 8.1.5, il processo sembra completarsi, e poi l'intero negozio, sia il front office che il back office, mostra solo uno schermo bianco. Nessun messaggio di errore, nessun contenuto parziale, solo il vuoto.

Comprendere perché questo accade richiede la comprensione di ciò che fa un aggiornamento del core di PrestaShop. Il processo di aggiornamento sostituisce centinaia di file PHP, modifica le tabelle del database, rigenera gli indici delle classi, svuota le cache e potenzialmente esegue query di migrazione. Qualsiasi errore in qualsiasi punto di questa catena può lasciare il negozio in uno stato inconsistente in cui PHP incontra un errore fatale ma non ha modo di visualizzarlo perché la segnalazione degli errori è disabilitata in modalità produzione.

Le cause più comuni rientrano in diverse categorie: moduli incompatibili che fanno riferimento a classi core rimosse o modificate, discrepanze della versione PHP tra la vecchia e la nuova versione di PrestaShop, conflitti dei file di override dove le personalizzazioni si scontrano con i file core modificati, risorse server insufficienti che causano la terminazione del processo di aggiornamento a metà, e fallimenti della migrazione del database che lasciano le tabelle in uno stato inconsistente.

Passo 1: Abilitare la Modalità Debug

La primissima azione quando ti trovi di fronte a una pagina bianca è rendere visibili gli errori. PrestaShop sopprime l'output degli errori in modalità produzione per evitare di esporre informazioni sensibili ai visitatori. Devi abilitare temporaneamente la modalità debug per vedere cosa sta effettivamente andando storto.

Il metodo più veloce è modificare il file /config/defines.inc.php. Cerca la riga che definisce _PS_MODE_DEV_ e cambiala:

define('_PS_MODE_DEV_', true);

Se non puoi accedere ai file via FTP o SSH perché anche il tuo pannello di hosting è inaccessibile, alcuni provider di hosting offrono un file manager attraverso il loro pannello di controllo (cPanel, Plesk, DirectAdmin) che funziona indipendentemente dalla tua installazione PrestaShop.

In PrestaShop 8.x, puoi anche abilitare la modalità debug attraverso il file .env nella directory principale. Cambia APP_ENV=prod in APP_ENV=dev e imposta APP_DEBUG=1. Questo attiva la toolbar di debug Symfony e le pagine di errore dettagliate.

Dopo aver abilitato la modalità debug, ricarica la pagina. Invece di uno schermo bianco, dovresti ora vedere un messaggio di errore dettagliato con un percorso file, un numero di riga e uno stack trace. Questo messaggio di errore è la chiave per diagnosticare e risolvere il problema.

Passo 2: Controllare i Log degli Errori

Se l'abilitazione della modalità debug mostra ancora una pagina bianca (cosa che può accadere se l'errore si verifica prima che PHP carichi il framework di PrestaShop), controlla direttamente i log degli errori del server.

Sui server Apache, il log degli errori si trova tipicamente in /var/log/apache2/error.log o /var/log/httpd/error_log. Su Nginx con PHP-FPM, controlla /var/log/nginx/error.log e /var/log/php-fpm/error.log (o /var/log/php8.1-fpm.log a seconda della tua versione PHP). Su hosting condiviso, i log degli errori sono generalmente accessibili attraverso il pannello di controllo dell'hosting o in una directory logs all'interno del tuo account di hosting.

PrestaShop mantiene anche i propri file di log nella directory /var/logs/ (PrestaShop 1.7) o /var/log/ (PrestaShop 8.x). Cerca file con la data corrente. Questi log basati su Symfony possono contenere informazioni dettagliate su cosa è andato storto durante il processo di aggiornamento.

Inoltre, controlla la directory /log/ nella directory principale di PrestaShop per eventuali file di log degli errori. Alcune versioni di PrestaShop scrivono errori critici qui quando non possono visualizzarli sullo schermo.

Causa Comune 1: Moduli Incompatibili

I moduli sono la causa più frequente di pagine bianche dopo gli aggiornamenti. Un modulo che funzionava perfettamente su PrestaShop 1.7.8.7 può mandare in crash l'intero negozio sulla 1.7.8.8 se utilizza classi o metodi core interni che sono cambiati nell'aggiornamento.

Il messaggio di errore appare tipicamente come: Fatal error: Class 'NomeClasse' not found oppure Fatal error: Call to undefined method NomeClasse::nomeMetodo() oppure Fatal error: Declaration of ClasseModulo::hookMethod() must be compatible with ClasseCore::hookMethod().

Per risolvere, devi identificare e disabilitare il modulo problematico. Se puoi accedere al back office (a volte solo il front office va in crash), vai in Moduli e disabilita i moduli recentemente installati o aggiornati uno alla volta fino a quando il problema si risolve.

Se anche il back office è inaccessibile, disabilita i moduli attraverso il database. Connettiti al database usando phpMyAdmin o un client MySQL ed esegui:

UPDATE ps_module SET active = 0 WHERE name = 'nome_modulo_problematico';

Se non sai quale modulo sta causando il problema, puoi disabilitare tutti i moduli di terze parti contemporaneamente impostando la loro colonna active a 0. Prima identifica quali moduli sono di terze parti controllando la directory /modules/ per i moduli non PrestaShop. Poi disabilitali selettivamente.

Un approccio più aggressivo è rinominare la directory del modulo. Ad esempio, rinomina /modules/qualchemodulo/ in /modules/qualchemodulo_disabilitato/. PrestaShop non può caricare un modulo la cui directory non corrisponde al nome registrato, disabilitandolo efficacemente senza toccare il database.

Causa Comune 2: Incompatibilità della Versione PHP

Ogni versione di PrestaShop richiede un intervallo specifico di versioni PHP. PrestaShop 1.7.6 e precedenti richiedono PHP 7.1 a 7.3. PrestaShop 1.7.7 a 1.7.8 supportano PHP 7.2 a 8.0. PrestaShop 8.0 richiede PHP 7.2 a 8.1. PrestaShop 8.1 richiede PHP 8.0 a 8.2. PrestaShop 9.0 richiede PHP 8.1 o superiore.

Se il tuo ambiente di hosting ha cambiato le versioni PHP durante o contemporaneamente all'aggiornamento di PrestaShop, potresti incontrare errori di sintassi o chiamate a funzioni deprecate. Gli errori comuni di compatibilità PHP includono: Deprecated: Function create_function() is deprecated (PHP 7.2+ con codice scritto per PHP 5.x), Fatal error: Uncaught Error: Call to undefined function mysql_connect() (PHP 7.0+ ha rimosso l'estensione mysql), e Fatal error: Array and string offset access syntax with curly braces is no longer supported (PHP 8.0+).

Controlla la tua versione PHP attuale guardando l'output di phpinfo() o eseguendo php -v dalla riga di comando. Se la versione è fuori dall'intervallo supportato per la tua versione di PrestaShop, passa a una versione PHP compatibile attraverso il pannello di controllo del tuo hosting.

Causa Comune 3: Conflitti degli Override

Il sistema di override di PrestaShop consente a moduli e sviluppatori di modificare il comportamento core posizionando file di classe modificati nella directory /override/. Durante un aggiornamento, le classi core cambiano, ma i file di override rimangono. Se un override fa riferimento a una firma di metodo che è cambiata, una proprietà che è stata rimossa o una classe che è stata rinominata, l'override causa un errore fatale.

Il file di indice delle classi in /var/cache/prod/class_index.php (o /cache/class_index.php nelle versioni precedenti) mappa i nomi delle classi alle loro posizioni di file, inclusi gli override. Un indice delle classi obsoleto o corrotto può caricare il file sbagliato per una classe, causando crash immediati.

Per verificare se gli override sono il problema, disabilita temporaneamente il sistema di override. Modifica /config/defines.inc.php e aggiungi o modifica:

define('_PS_HOST_MODE_', false);

Poi elimina il file di indice delle classi per forzare PrestaShop a rigenerarlo senza override. Se il negozio si carica dopo questa modifica, il problema è in uno dei tuoi file di override.

Per identificare l'override problematico specifico, guarda nelle directory /override/classes/ e /override/controllers/. Rimuovi i file di override uno alla volta, eliminando l'indice delle classi dopo ogni rimozione, fino a trovare quello che causa il crash. Una volta identificato, aggiorna l'override per renderlo compatibile con la nuova versione core o rimuovilo completamente se non è più necessario.

Causa Comune 4: Cache e File Compilati

PrestaShop genera template Smarty compilati, cache del container Symfony, mappe delle classi e vari altri file in cache che diventano non validi dopo un aggiornamento. Se il processo di aggiornamento non ha svuotato correttamente queste cache, il negozio tenta di utilizzare file in cache che fanno riferimento alla vecchia struttura del codice.

Svuota tutte le cache manualmente eliminando il contenuto di queste directory (elimina il contenuto, non le directory stesse):

/var/cache/prod/ e /var/cache/dev/ per la cache Symfony. Elimina tutto all'interno di queste directory. PrestaShop le rigenererà al prossimo caricamento della pagina.

/cache/smarty/compile/ e /cache/smarty/cache/ per le cache dei template Smarty. I template compilati obsoleti sono una causa molto comune di pagine bianche dopo gli aggiornamenti.

/var/cache/prod/class_index.php (o /cache/class_index.php) per la mappa delle classi. Questo file deve essere rigenerato dopo qualsiasi aggiornamento.

Nelle configurazioni PHP-FPM, resetta anche OPcache. OPcache memorizza il bytecode PHP compilato in memoria e potrebbe servire il vecchio codice anche dopo che i file sono stati sostituiti. Riavvia il servizio PHP-FPM o, se non puoi farlo, crea un piccolo file PHP che chiama opcache_reset() e accedici tramite il browser.

Causa Comune 5: Fallimenti della Migrazione del Database

Gli aggiornamenti di PrestaShop spesso includono modifiche allo schema del database: nuove colonne, indici modificati, nuove tabelle o migrazioni di dati. Se il processo di aggiornamento è stato interrotto (timeout, limite di memoria, disconnessione), il database potrebbe trovarsi in uno stato di migrazione parziale.

Controlla il database PrestaShop per la tabella ps_configuration e cerca il valore PS_VERSION_DB. Se questo valore non corrisponde alla versione dei file sul disco, l'aggiornamento non si è completato correttamente. PrestaShop potrebbe tentare di rieseguire le migrazioni al prossimo caricamento, oppure potrebbe semplicemente fallire.

I fallimenti della migrazione del database sono i più difficili da recuperare senza un backup. Se hai un backup del database da prima dell'aggiornamento, ripristinarlo e rieseguire l'aggiornamento è spesso il percorso più sicuro. Se non hai un backup, potresti dover applicare manualmente i file di migrazione SQL mancanti trovati nella directory /install/upgrade/sql/.

Procedura di Ripristino Passo-Passo

Segui questa sequenza quando recuperi da una pagina bianca dopo un aggiornamento core. L'ordine è importante perché ogni passo o risolve il problema o elimina una possibile causa.

Passo 1: Abilita la modalità debug in /config/defines.inc.php impostando _PS_MODE_DEV_ a true. Ricarica la pagina e leggi il messaggio di errore.

Passo 2: Elimina il contenuto di /var/cache/prod/, /var/cache/dev/, /cache/smarty/compile/ e /cache/smarty/cache/. Elimina class_index.php. Ricarica la pagina.

Passo 3: Se l'errore punta a un modulo specifico, disabilita quel modulo rinominando la sua directory o impostando active = 0 nella tabella del database ps_module. Ricarica la pagina.

Passo 4: Se l'errore punta a un file di override, sposta il contenuto della directory /override/ in una posizione di backup temporanea. Elimina di nuovo class_index.php. Ricarica la pagina.

Passo 5: Verifica che la tua versione PHP sia compatibile con la versione di PrestaShop a cui hai aggiornato. Controlla phpinfo() o php -v. Cambia versione PHP se necessario.

Passo 6: Controlla i permessi dei file. Il processo di aggiornamento potrebbe aver creato file con proprietà errata. Tutti i file PrestaShop devono essere leggibili dall'utente del server web, e le directory /var/, /cache/, /img/, /upload/, /download/, /translations/, /themes/ e /modules/ devono essere scrivibili.

Passo 7: Se nessuno dei passaggi precedenti risolve il problema e hai un backup del database, ripristina il database e i file dal backup, poi tenta nuovamente l'aggiornamento dopo aver affrontato eventuali problemi identificati durante la diagnosi.

Procedura di Aggiornamento Sicura per Aggiornamenti Futuri

La prevenzione è di gran lunga migliore del ripristino. Segui questa procedura per ogni aggiornamento del core di PrestaShop per minimizzare il rischio di pagine bianche e perdita di dati.

Prima dell'aggiornamento: Crea un backup completo sia del database che di tutti i file. Non solo il database, non solo i file, ma entrambi. Conserva questi backup in una posizione esterna al tuo account di hosting se possibile. Verifica di poter effettivamente ripristinare da questi backup prima di procedere.

Disabilita tutti i moduli di terze parti. Questo è il singolo passo più efficace che puoi compiere per prevenire le pagine bianche. I moduli core (quelli forniti con PrestaShop) sono progettati per essere compatibili con l'aggiornamento, ma i moduli di terze parti non hanno questa garanzia. Disabilitali prima dell'aggiornamento e riabilitali uno alla volta dopo, testando il negozio dopo ogni riattivazione.

Disabilita il sistema di override. Se hai override personalizzati, disabilitali prima dell'aggiornamento. Rivaluta ogni override dopo l'aggiornamento per determinare se è ancora compatibile e ancora necessario.

Controlla le note di rilascio. Ogni rilascio di PrestaShop include note su requisiti di compatibilità, problemi noti e modifiche che possono causare incompatibilità. Leggile prima di aggiornare, non dopo che qualcosa si è rotto.

Metti il negozio in modalità manutenzione. Questo impedisce ai clienti di effettuare ordini durante l'aggiornamento e di incontrare errori. Naviga in Parametri del Negozio, Generali, Manutenzione nel back office e abilita la modalità manutenzione.

Durante l'aggiornamento: Monitora il processo di aggiornamento. Non chiudere la scheda del browser e non navigare altrove. Se l'aggiornamento richiede più tempo del previsto, controlla i log degli errori del server per errori di timeout o memoria. Se il processo sembra bloccato, attendi almeno 10 minuti prima di intraprendere qualsiasi azione, poiché negozi grandi possono avere migrazioni di database significative da elaborare.

Dopo l'aggiornamento: Svuota tutte le cache. Verifica che il back office si carichi correttamente. Controlla il front office. Riabilita i moduli uno alla volta, controllando il negozio dopo ciascuno. Riabilita gli override uno alla volta se applicabile. Disabilita la modalità manutenzione. Monitora i log degli errori per le successive 24 ore.

Strategie di Rollback

Quando il ripristino non è possibile o richiede troppo tempo, tornare alla versione precedente potrebbe essere l'opzione migliore. Tuttavia, PrestaShop non ha un meccanismo di rollback integrato, quindi devi pianificare questa possibilità prima di iniziare l'aggiornamento.

Rollback completo dal backup: Ripristina sia il database che i file dal backup pre-aggiornamento. Questo è l'approccio più pulito ma richiede che tu abbia fatto un backup completo prima dell'aggiornamento. Dopo il ripristino, verifica che il negozio funzioni correttamente e che nessun ordine o dato cliente creato durante il periodo di aggiornamento fallito sia andato perso (se il negozio era in modalità manutenzione, nulla dovrebbe essere cambiato).

Rollback parziale dei file: Se solo i file sono corrotti ma il database è integro, puoi sostituire i file di PrestaShop con la versione precedente mantenendo il database attuale. Scarica la versione precedente esatta di PrestaShop dall'archivio ufficiale dei rilasci, estraila e sovrascrivi i file sul tuo server. Mantieni i tuoi moduli personalizzati, temi e file di configurazione. Questo approccio è rischioso perché il database potrebbe essere stato parzialmente migrato, creando un'inconsistenza tra i file e lo schema del database.

Fix in avanti: A volte il percorso più veloce non è tornare indietro ma correggere l'errore specifico. Se l'errore è causato da un singolo modulo o override incompatibile, correggere o rimuovere quel singolo componente potrebbe richiedere minuti rispetto alle ore di un rollback completo. Questo approccio è migliore quando hai identificato chiaramente la causa dal messaggio di errore.

L'Importanza dei Backup del Database

Ogni sezione di questa guida menziona i backup, e per una buona ragione. Un database PrestaShop contiene ogni prodotto, ogni ordine, ogni account cliente, ogni impostazione di configurazione e ogni contenuto del tuo negozio. Perderlo significa perdere i dati del tuo business.

I backup giornalieri automatizzati non sono opzionali per un negozio PrestaShop in produzione. Configura il sistema di backup del tuo provider di hosting, usa un modulo di backup del database o imposta un cron job che esegue mysqldump a intervalli regolari. Conserva i backup in più posizioni. Testa periodicamente la tua procedura di ripristino per assicurarti che i backup siano effettivamente utilizzabili.

Prima di qualsiasi aggiornamento, crea un backup manuale in aggiunta ai tuoi backup automatizzati. Nominalo chiaramente con la data e la versione di PrestaShop, in modo da poterlo identificare immediatamente se hai bisogno di ripristinare.

Quando Cercare Aiuto Professionale

Se hai seguito tutti i passi di questa guida e ti trovi ancora di fronte a una pagina bianca, o se i messaggi di errore indicano problemi profondi del core che richiedono correzioni a livello di codice, potrebbe essere il momento di coinvolgere uno sviluppatore PrestaShop. Forniscigli i messaggi di errore che hai raccolto, le versioni di PrestaShop coinvolte (prima e dopo l'aggiornamento), la tua versione PHP e qualsiasi azione che hai già intrapreso. Queste informazioni ridurranno significativamente il tempo necessario per diagnosticare e risolvere il problema.

Tentare di modificare manualmente i file core di PrestaShop senza comprendere l'architettura del framework può creare problemi aggiuntivi. Se il messaggio di errore fa riferimento a container Symfony, dependency injection o configurazione del kernel, queste sono aree in cui modifiche errate possono propagarsi in fallimenti multipli.