Come leggere i log degli errori di PrestaShop come un vero sviluppatore

Perche i log degli errori di PrestaShop sono importanti

Ogni negozio PrestaShop genera errori. Alcuni sono avvisi innocui che non influenzano mai i tuoi clienti. Altri sono guasti critici che bloccano completamente il checkout. La differenza tra un proprietario di negozio che passa giorni in attesa del supporto e uno che risolve i problemi in pochi minuti si riduce spesso a una singola competenza: saper leggere i log degli errori.

I log degli errori sono l'output diagnostico del tuo server e della tua applicazione PrestaShop. Registrano ogni errore PHP, ogni query del database fallita, ogni problema di permessi e ogni eccezione non gestita. Quando qualcosa va storto, la risposta si trova quasi sempre in un file di log. La sfida sta nel sapere dove cercare, cosa cercare e come interpretare cio che trovi.

Questa guida copre l'intero panorama del logging degli errori in PrestaShop. Imparerai dove si trova ogni tipo di log, come abilitare la segnalazione dettagliata degli errori, come leggere gli stack trace e come utilizzare gli strumenti da riga di comando per trovare l'ago nel pagliaio. Che tu stia facendo debug di uno schermo bianco della morte o cercando di rintracciare un errore intermittente al checkout, queste sono le conoscenze di cui hai bisogno.

Dove si trovano i log di PrestaShop

PrestaShop genera log a diversi livelli, e ogni livello ha i propri file di log. Capire quale log controllare per primo consente di risparmiare enormi quantita di tempo.

Log dell'applicazione PrestaShop (var/logs)

A partire da PrestaShop 1.7, l'applicazione utilizza il framework Symfony per il back office e il routing principale. Symfony scrive i propri log nella directory var/logs/ nella root di PrestaShop. Troverai file denominati in base all'ambiente corrente:

var/logs/dev.log contiene i log quando PrestaShop viene eseguito in modalita di sviluppo. Questo file e estremamente dettagliato e registra tutto, dalle decisioni di routing alle query del database. Puo crescere fino a centinaia di megabyte rapidamente.

var/logs/prod.log contiene i log dalla modalita di produzione. Questo file e molto meno dettagliato per impostazione predefinita, registrando solo avvisi ed errori. Questo e il file che dovresti controllare per primo quando qualcosa si rompe in un negozio live.

Questi file di log seguono il formato Monolog, che e la libreria di logging standard in Symfony. Ogni riga include un timestamp, il canale del log (come request, security o doctrine), il livello di gravita e il messaggio. Una voce tipica appare cosi:

[2024-03-15 14:22:33] request.CRITICAL: Uncaught PHP Exception Symfony\Component\HttpKernel\Exception\NotFoundHttpException: "No route found for GET /admin/nonexistent" at /var/www/html/vendor/symfony/http-kernel/EventListener/RouterListener.php line 136

I livelli di gravita, dal meno al piu grave, sono: DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT e EMERGENCY. Quando risolvi problemi, filtra prima per ERROR e CRITICAL.

Log degli errori PHP

PHP stesso mantiene un log degli errori separato dai log dell'applicazione PrestaShop. Questo log cattura gli errori che si verificano prima che il framework di logging di PrestaShop si inizializzi, o errori nel codice che non utilizza il logger Symfony. La posizione di questo file dipende dalla configurazione del server.

Sulla maggior parte dei server Linux con Apache, il log degli errori PHP si trova in /var/log/php_errors.log o /var/log/php/error.log. Sull'hosting condiviso con cPanel, si trova spesso in /home/nomeutente/logs/error.log o nella directory public_html come error_log.

Puoi trovare la posizione esatta controllando la configurazione PHP. Crea un file PHP temporaneo con phpinfo(); e cerca la direttiva error_log. In alternativa, esegui php -i | grep error_log dalla riga di comando.

I log degli errori PHP catturano errori fatali, errori di parsing, avvisi e notifiche. Una voce di errore fatale tipicamente appare cosi:

[15-Mar-2024 14:22:33 UTC] PHP Fatal error: Uncaught Error: Class 'SomeModule\SomeClass' not found in /var/www/html/modules/somemodule/somemodule.php:45

Log del web server (Apache e Nginx)

Il tuo web server mantiene i propri set di log indipendenti da PHP e PrestaShop. Questi log sono essenziali per diagnosticare errori 500, errori 404 e problemi di prestazioni.

I log di Apache si trovano tipicamente in:

/var/log/apache2/error.log per il log degli errori su sistemi Debian e Ubuntu.
/var/log/httpd/error_log per il log degli errori su sistemi CentOS e RHEL.
/var/log/apache2/access.log per il log degli accessi, che registra ogni richiesta HTTP.

I log di Nginx si trovano tipicamente in:

/var/log/nginx/error.log per il log degli errori.
/var/log/nginx/access.log per il log degli accessi.

Se il tuo sito utilizza una configurazione di virtual host, i log potrebbero trovarsi in una posizione specifica del sito definita dalla direttiva ErrorLog (Apache) o error_log (Nginx) nel file del virtual host.

I log degli errori del web server catturano problemi come errori di permesso negato quando PHP tenta di scrivere in una directory, errori di sintassi nella configurazione dopo una modifica di .htaccess e errori di timeout del proxy se stai eseguendo PHP-FPM dietro Nginx. Questi sono i log da controllare quando vedi un generico errore 500 Internal Server Error senza dettagli nei log PHP o PrestaShop.

Log legacy di PrestaShop (Back Office)

PrestaShop mantiene anche un visualizzatore di log all'interno del back office sotto Parametri avanzati > Log. Questa interfaccia mostra le voci di log archiviate nella tabella del database ps_log. Questi log catturano eventi che PrestaShop registra esplicitamente, come tentativi di login falliti, errori di installazione dei moduli e errori nell'invio delle email.

Sebbene il visualizzatore di log del back office sia comodo, ha limitazioni significative. Non cattura errori PHP, errori del web server o la maggior parte degli errori fatali che impediscono il caricamento della pagina. Consideralo un supplemento ai log basati su file, non un sostituto.

Abilitare la modalita debug in PrestaShop

Per impostazione predefinita, PrestaShop viene eseguito in modalita produzione e nasconde i messaggi di errore dettagliati ai visitatori. Questo e corretto per un negozio live, ma rende il debug quasi impossibile. Quando qualcosa si rompe, il primo passo dovrebbe essere abilitare la modalita debug.

Metodo 1: il file defines.inc.php

Apri il file config/defines.inc.php e cerca la riga che imposta _PS_MODE_DEV_. Cambiala da false a true:

define('_PS_MODE_DEV_', true);

Questa singola modifica ha diversi effetti. La segnalazione degli errori PHP viene impostata al livello massimo, mostrando tutti gli errori, avvisi e notifiche. La cache dei template Smarty viene disabilitata, cosi le modifiche ai template appaiono immediatamente. La barra del profiler Symfony appare in fondo alle pagine del back office. E soprattutto, i dettagli degli errori vengono mostrati sullo schermo invece di mostrare una pagina di errore generica.

Metodo 2: la modalita Debug Profiling

Per un'analisi piu approfondita, puoi anche abilitare il profiling. Nello stesso file, imposta:

define('_PS_DEBUG_PROFILING_', true);

Questo aggiunge informazioni dettagliate su tempi e utilizzo della memoria in fondo a ogni pagina, mostrando quali hook richiedono piu tempo, quali moduli consumano piu memoria e quante query al database genera ogni pagina. Questo e inestimabile per il debug delle prestazioni ma non dovrebbe mai essere lasciato attivo in produzione.

Avviso di sicurezza

La modalita debug espone informazioni sensibili tra cui percorsi dei file, credenziali del database negli stack trace e struttura interna dell'applicazione. Non lasciare mai la modalita debug abilitata su un negozio in produzione accessibile al pubblico. Se hai bisogno di fare debug di un negozio live, considera la possibilita di limitare la modalita debug al tuo indirizzo IP racchiudendo il define in un controllo dell'IP, oppure utilizza un ambiente di staging.

Leggere gli stack trace

Quando PrestaShop incontra un errore fatale o un'eccezione non gestita in modalita debug, visualizza uno stack trace. Uno stack trace e un'istantanea della catena di chiamate che ha portato all'errore, che si legge dal punto di errore all'indietro fino al punto di ingresso originale. Imparare a leggere gli stack trace e la singola competenza di debug piu preziosa che puoi sviluppare.

Anatomia di uno stack trace

Un tipico stack trace di PrestaShop appare cosi:

PHP Fatal error: Uncaught TypeError: Argument 1 passed to Product::getProductProperties() must be of the type int, null given, called in /var/www/html/classes/Product.php on line 4523

Stack trace:
#0 /var/www/html/classes/Product.php(4523): Product::getProductProperties(NULL, Array)
#1 /var/www/html/modules/somemodule/somemodule.php(127): Product::getProductProperties(1, Array)
#2 /var/www/html/classes/Hook.php(523): SomeModule->hookDisplayHome(Array)
#3 /var/www/html/classes/Hook.php(460): Hook::coreCallHook(Object(SomeModule), 'hookDisplayHome', Array)
#4 /var/www/html/classes/Hook.php(408): Hook::exec('displayHome', Array)

Leggi lo stack trace dall'alto verso il basso. La prima riga ti dice cosa e andato storto: una funzione si aspettava un intero ma ha ricevuto null. La riga #0 ti dice dove si e verificato l'errore. La riga #1 ti dice cosa ha chiamato il codice alla riga #0. La riga #2 ti dice cosa ha chiamato #1, e cosi via.

In questo esempio, la catena e chiara: PrestaShop ha eseguito l'hook displayHome, che ha chiamato il metodo hookDisplayHome in SomeModule, che ha chiamato Product::getProductProperties() con un valore null dove era previsto un intero. Il bug si trova nel modulo alla riga 127, dove passa un valore errato.

Trovare il frame rilevante

Gli stack trace in PrestaShop possono essere lunghi, a volte 20 o 30 frame di profondita. La chiave e trovare il frame che contiene il tuo codice o il modulo che causa il problema. Cerca percorsi contenenti /modules/ o /themes/ perche queste sono le fonti piu probabili di bug. I frame che fanno riferimento a /classes/, /src/ o /vendor/ sono codice core di PrestaShop o librerie di terze parti, che hanno meno probabilita di essere la fonte del problema a meno che tu non abbia modificato i file core.

Pattern di errore comuni in PrestaShop

Dopo aver letto migliaia di log degli errori di PrestaShop, emergono ripetutamente certi pattern. Riconoscere questi pattern ti permette di diagnosticare problemi in pochi secondi invece che in ore.

Errori Class Not Found

PHP Fatal error: Uncaught Error: Class 'ModuleName\ClassName' not found

Questo significa che l'autoloader non riesce a trovare la classe specificata. Le cause comuni includono: un file vendor/autoload.php mancante (il modulo necessita di composer install), una dichiarazione di namespace non corrispondente, un file che non e stato incluso nello ZIP del modulo durante l'installazione, o un problema di case sensitivity sui server Linux dove ClassName.php e classname.php sono file diversi.

Errori Permission Denied

Warning: file_put_contents(/var/www/html/var/cache/prod/some_file): failed to open stream: Permission denied

Questi si verificano quando l'utente del web server (solitamente www-data su Debian/Ubuntu o apache su CentOS) non ha il permesso di scrittura su un file o directory. Correggi questo correggendo la proprieta: chown -R www-data:www-data var/cache/ e i permessi: chmod -R 775 var/cache/.

Errori Memory Limit

PHP Fatal error: Allowed memory size of 134217728 bytes exhausted (tried to allocate 65536 bytes)

Il numero 134217728 byte equivale a 128MB, che e il limite di memoria PHP predefinito. PrestaShop raccomanda almeno 256MB. Aumentalo nel file php.ini: memory_limit = 512M. Se l'errore persiste anche con limiti di memoria elevati, il codice probabilmente ha un memory leak, spesso causato dal caricamento di troppi prodotti o categorie in una singola query senza paginazione.

Errori di connessione al database

Link to database cannot be established: SQLSTATE[HY000] [2002] Connection refused

Questo significa che PrestaShop non riesce a connettersi al server MySQL. Verifica che il server del database sia in esecuzione, che le credenziali in app/config/parameters.php siano corrette e che l'host del database sia raggiungibile dal web server.

Errori dei template Smarty

SmartyException: Unable to load template file 'module:somemodule/views/templates/hook/display.tpl'

Il file del template e mancante, scritto male o nella directory sbagliata. Verifica che il file esista nel percorso previsto e che il nome del file corrisponda esattamente, incluso il maiuscolo/minuscolo.

Errori del token CSRF

Invalid token. Please try to log in again.

Questo appare nel back office quando l'invio di un modulo include un token di sicurezza scaduto o mancante. Succede tipicamente quando una sessione scade durante una lunga sessione di modifica, quando piu schede sono aperte sulla stessa pagina admin, o quando un modulo genera i propri URL del modulo in modo errato.

Usare grep per trovare errori

Quando i file di log sono grandi, scorrerli manualmente e poco pratico. Il comando grep e il tuo migliore alleato per trovare rapidamente le voci rilevanti.

Ricerca base degli errori

Per trovare tutti gli errori fatali nel log degli errori PHP:

grep 'Fatal error' /var/log/php_errors.log

Per trovare errori di un modulo specifico:

grep 'somemodule' /var/www/html/var/logs/prod.log

Per trovare errori solo di oggi (assumendo il formato della data nel log):

grep '2024-03-15' /var/www/html/var/logs/prod.log | grep 'ERROR\|CRITICAL'

Filtraggio avanzato

Per vedere gli errori con contesto circostante (3 righe prima e dopo ogni corrispondenza):

grep -C 3 'Fatal error' /var/log/php_errors.log

Per contare quante volte si verifica ogni errore unico:

grep 'Fatal error' /var/log/php_errors.log | sort | uniq -c | sort -rn | head -20

Questa pipeline ordina gli errori, conta i duplicati, ordina per conteggio in ordine decrescente e mostra i primi 20. Questo e incredibilmente utile per identificare gli errori piu frequenti che richiedono attenzione per primi.

Per cercare attraverso piu file di log contemporaneamente:

grep -r 'Fatal error' /var/log/ --include='*.log'

Il flag -r cerca ricorsivamente e --include limita la ricerca ai file con estensione .log.

Monitoraggio dei log in tempo reale con tail -f

Quando stai attivamente facendo debug di un problema, hai bisogno di vedere gli errori nel momento in cui si verificano. Il comando tail -f segue un file di log in tempo reale, mostrando le nuove voci man mano che vengono scritte.

Monitoraggio base in tempo reale

Per monitorare il log di produzione di PrestaShop in tempo reale:

tail -f /var/www/html/var/logs/prod.log

Per monitorare il log degli errori PHP:

tail -f /var/log/php_errors.log

Per monitorare piu file di log contemporaneamente:

tail -f /var/www/html/var/logs/prod.log /var/log/php_errors.log /var/log/apache2/error.log

Monitoraggio filtrato in tempo reale

Per monitorare solo le voci di livello errore in tempo reale, combina tail con grep:

tail -f /var/www/html/var/logs/prod.log | grep --line-buffered 'ERROR\|CRITICAL'

Il flag --line-buffered e importante qui. Senza di esso, grep bufferizza il suo output e potresti non vedere le corrispondenze immediatamente.

Per evidenziare parole chiave specifiche mostrando tutto l'output:

tail -f /var/www/html/var/logs/prod.log | grep --color=always -E 'ERROR|CRITICAL|$'

Questo evidenzia ERROR e CRITICAL a colori mostrando comunque tutte le righe.

Il flusso di lavoro del debug

Il flusso di lavoro di debug piu efficace combina il monitoraggio in tempo reale con il test attivo. Apri una finestra del terminale con tail -f in esecuzione sui file di log rilevanti. Nel browser, riproduci l'azione che causa l'errore. Osserva il terminale per le nuove voci di log che appaiono nell'esatto momento in cui attivi il problema. Questo approccio elimina le congetture e ti mostra precisamente cosa succede quando si verifica l'errore.

Rotazione e gestione dei log

I file di log crescono continuamente e possono consumare tutto lo spazio disco disponibile se lasciati senza gestione. La maggior parte dei server Linux utilizza logrotate per gestire questo automaticamente, ma i log propri di PrestaShop in var/logs/ potrebbero non essere inclusi nella configurazione predefinita di logrotate.

Comprendere Logrotate

L'utilita logrotate viene eseguita giornalmente (solitamente tramite cron) e gestisce la rotazione, la compressione e l'eliminazione dei file di log. I file di configurazione si trovano in /etc/logrotate.d/. La rotazione dei log di Apache e Nginx e tipicamente configurata di default.

Per la directory var/logs di PrestaShop, potrebbe essere necessario creare una configurazione logrotate personalizzata:

/var/www/html/var/logs/*.log {
  daily
  missingok
  rotate 14
  compress
  delaycompress
  notifempty
  create 0640 www-data www-data
}

Questa configurazione ruota i log giornalmente, mantiene 14 giorni di storia, comprime i log vecchi e crea nuovi file di log con i permessi corretti.

Pulizia manuale dei log

Se un file di log e cresciuto enormemente e hai bisogno di svuotarlo senza perdere l'handle del file (importante se un processo sta attivamente scrivendo su di esso):

truncate -s 0 /var/www/html/var/logs/prod.log

Non eliminare il file e ricrearlo, perche qualsiasi processo che ha il file aperto continuera a scrivere sull'inode del file eliminato fino al riavvio. L'approccio con truncate svuota i contenuti preservando l'inode.

Comprendere i contesti di errore specifici di PrestaShop

Gli errori di PrestaShop spesso arrivano con un contesto unico per la piattaforma. Comprendere questo contesto ti aiuta a localizzare e correggere i problemi piu velocemente.

Errori relativi agli hook

Quando un errore si verifica all'interno di un hook, lo stack trace includera riferimenti a Hook::exec() e Hook::coreCallHook(). Il nome dell'hook ti dice esattamente in quale momento del processo di rendering della pagina si verifica l'errore. Per esempio, gli errori displayHome si verificano nella homepage, gli errori actionValidateOrder si verificano durante il checkout, e gli errori displayBackOfficeHeader si verificano quando si carica qualsiasi pagina del back office.

Se un errore in un hook manda in crash una pagina, puoi disabilitare temporaneamente il modulo responsabile dal database:

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

Questo ti permette di accedere al back office per diagnosticare e correggere correttamente il problema.

Conflitti degli override

Il sistema di override di PrestaShop permette ai moduli di estendere le classi core, ma sorgono conflitti quando due moduli fanno override della stessa classe. L'errore appare tipicamente come un conflitto nella firma del metodo o un cambiamento di comportamento inatteso. Controlla la directory override/ per vedere quali override sono attivi e controlla il file cache/class_index.php che mappa le classi ai loro file di override. Eliminare questo file di cache forza PrestaShop a rigenerare la mappa degli override.

Errori relativi alla cache

Molti errori di PrestaShop sono causati da file di cache obsoleti. Se vedi errori che non corrispondono al codice corrente (per esempio, un errore che fa riferimento a un numero di riga che non esiste nel file), la cache e probabilmente obsoleta. Svuotala eliminando i contenuti di var/cache/prod/ e var/cache/dev/. Su PrestaShop 1.6, svuota invece cache/smarty/compile/ e cache/smarty/cache/.

Errori di installazione e aggiornamento dei moduli

Le installazioni dei moduli possono fallire silenziosamente, lasciando il modulo in uno stato parzialmente installato. Controlla var/logs/prod.log per le voci durante il timestamp dell'installazione. I problemi comuni includono tabelle del database mancanti (l'SQL nel metodo install() del modulo e fallito), hook mancanti (la chiamata registerHook() e fallita) e errori di voce duplicata nella tabella ps_authorization_role quando si reinstalla un modulo che non e stato completamente disinstallato.

Costruire una checklist di debug

Quando incontri un errore in PrestaShop, segui questa checklist sistematica per trovare la causa in modo efficiente:

Primo, identifica il tipo di errore. E uno schermo bianco (errore 500), un messaggio di errore specifico, un layout rotto o un comportamento inatteso? Ogni tipo indica file di log diversi.

Secondo, controlla prima il log piu specifico. Per gli errori PHP, controlla il log degli errori PHP. Per gli errori HTTP, controlla il log degli errori del web server. Per gli errori dell'applicazione, controlla var/logs/prod.log.

Terzo, abilita la modalita debug se i log non rivelano informazioni sufficienti. Cambia _PS_MODE_DEV_ a true e riproduci l'errore.

Quarto, usa tail -f sui log rilevanti e riproduci l'errore nel browser. Questo ti fornisce una visualizzazione in tempo reale di esattamente cosa succede.

Quinto, leggi lo stack trace dall'alto verso il basso. Trova il frame che fa riferimento al codice del tuo modulo o tema. E li che deve essere applicata la correzione.

Sesto, cerca il messaggio di errore nelle issue di GitHub di PrestaShop e nei forum. E molto probabile che qualcuno abbia incontrato e risolto lo stesso problema prima.

Settimo, dopo aver applicato una correzione, svuota tutte le cache e monitora i log per confermare che l'errore sia scomparso. Una correzione che non produce un log pulito non e una correzione completa.

Riepilogo

Leggere i log degli errori di PrestaShop non e un'arte misteriosa riservata agli sviluppatori senior. E una competenza pratica costruita sulla conoscenza di dove si trovano i log, come filtrarli e come interpretare cio che contengono. I log in var/logs/, il log degli errori PHP e il log del web server servono ciascuno uno scopo diverso e insieme forniscono un quadro completo di qualsiasi problema. Abilitare la modalita debug ti fornisce messaggi di errore dettagliati. Gli stack trace ti mostrano l'esatta catena di chiamate di funzione che ha portato all'errore. Strumenti come grep e tail -f rendono possibile trovare e monitorare gli errori in modo efficiente anche in file di log grandi e molto attivi. Padroneggia queste tecniche e risolverai i problemi piu velocemente, con meno frustrazione e con molta meno dipendenza dal supporto esterno.