La modalità debug si imposta con APP_DEBUG nel file .env: true in locale, false in produzione, sempre. Controlla lo stato reale con php artisan about --only=environment. Se il cambiamento non ha effetto, la configurazione è in cache: lancia php artisan config:clear.
La modalità debug decide cosa vede un visitatore quando la tua applicazione va in errore: la traccia completa con il codice sorgente e le variabili d’ambiente, oppure una pagina di errore neutra. È un’impostazione da una riga, ma è anche una delle fughe di dati più comuni in produzione.
Articolo del percorso Sviluppo web. Verificato su Laravel 13.30.1 con PHP 8.4.25.
Attivare e disattivare
L’impostazione si fa nel file .env, alla radice del progetto, e da nessun’altra parte:
APP_ENV=local
APP_DEBUG=truePer disattivarla, porta il valore a false:
APP_ENV=production
APP_DEBUG=falseControlla lo stato reale senza scrivere una riga di codice:
php artisan about --only=environment Environment ........................................................ local
Debug Mode ...................................................... ENABLEDÈ l’unica verifica che conta: mostra il valore davvero usato dall’applicazione, cache compresa.
La trappola: la configurazione in cache
Metti APP_DEBUG=false, ricarichi la pagina, e le tracce di errore continuano a comparire. Nella quasi totalità dei casi è la cache di configurazione.
Quando php artisan config:cache è stato eseguito, Laravel scrive tutti i valori risolti in bootstrap/cache/config.php e smette del tutto di leggere il file .env. Il comportamento è stato misurato:
| Passaggio | config('app.debug') | env('APP_DEBUG') |
|---|---|---|
APP_DEBUG=true, senza cache | true | true |
dopo config:cache, poi passaggio a false nel .env | true | NULL |
dopo config:clear | false | false |
Due insegnamenti. Il primo: dopo ogni modifica del .env su un server in cui la configurazione è in cache, bisogna rigenerarla.
php artisan config:clear
# oppure, in produzione, rigenerare direttamente la cache
php artisan config:cacheÈ la conseguenza meno conosciuta, e non riguarda solo il debug. Una chiamata a env('MA_CLE') fuori da un file di config/ restituirà null non appena config:cache sarà girato. La regola è netta: env() solo dentro config/, e ovunque altrove config('fichier.cle').
Cosa contiene config/app.php
La chiave di configurazione si limita a leggere la variabile d’ambiente, con false come valore di ripiego:
'debug' => (bool) env('APP_DEBUG', false),Non modificare questa riga. È scritta perché il comportamento predefinito sia sicuro: se APP_DEBUG manca dal .env, la modalità debug resta disattivata. Verificato eliminando la variabile: config('app.debug') restituisce effettivamente false.
Scrivere il valore fisso in config/app.php ha due inconvenienti: il file è versionato, quindi l’impostazione parte su tutti gli ambienti, e il .env diventa fuorviante.
I valori accettati seguono le regole di conversione di Laravel, misurate riga per riga:
Nel .env | config('app.debug') |
|---|---|
APP_DEBUG=true oppure (true) oppure 1 | true |
APP_DEBUG=false oppure 0 | false |
APP_DEBUG=yes | true |
| variabile assente | false |
yes vale true perché la stringa non viene riconosciuta come booleano e finisce castata. È un buon motivo per attenersi a true e false.
Perché false in produzione non è negoziabile
Con APP_DEBUG=true, la pagina di errore mostra lo stack trace, degli estratti del codice sorgente e il contenuto delle variabili d’ambiente caricate. Un visitatore che provoca un errore può quindi leggere le tue credenziali di database, le tue chiavi API e la chiave APP_KEY che cifra le sessioni.
Non c’è bisogno di cercare: basta un URL che sollevi un’eccezione. È il motivo per cui certe applicazioni Laravel finiscono compromesse senza alcuna falla applicativa particolare.
La configurazione corretta di un server di produzione, come quello montato in l’installazione di Laravel su Debian, sta in tre righe:
APP_ENV=production
APP_DEBUG=false
APP_URL=https://exemple.comPoi, dopo il deploy:
php artisan config:cache
php artisan about --only=environment # controllo: Debug Mode deve mostrare OFFLo stesso ragionamento vale per i form pubblici, che vanno protetti dagli invii automatici prima dell’apertura al pubblico.
Gli errori restano consultabili, ma nei log invece che nel browser:
tail -f storage/logs/laravel.logQuesto percorso si costruisce con storage_path(), descritto in i percorsi dell’applicazione.
Errori frequenti
config:cache, Laravel non legge più il file .env. Ogni modifica richiede config:clear o una rigenerazione della cache.env() restituisce NULL ovunque altrove. Usa config('fichier.cle').
