Le mode débogage se règle avec APP_DEBUG dans le fichier .env : true en local, false en production, toujours. Contrôlez l’état réel avec php artisan about --only=environment. Si le changement ne prend pas effet, la configuration est en cache : lancez php artisan config:clear.
Le mode débogage décide de ce que voit un visiteur quand votre application plante : la trace complète avec le code source et les variables d’environnement, ou une page d’erreur neutre. C’est un réglage d’une ligne, mais c’est aussi l’une des fuites de données les plus courantes en production.
Article du parcours Développement web. Vérifié sur Laravel 13.30.1 avec PHP 8.4.25.
Activer et désactiver
Le réglage se fait dans le fichier .env, à la racine du projet, et nulle part ailleurs :
APP_ENV=local
APP_DEBUG=truePour le désactiver, passez la valeur à false :
APP_ENV=production
APP_DEBUG=falseVérifiez l’état effectif sans écrire une seule ligne de code :
php artisan about --only=environment Environment ........................................................ local
Debug Mode ...................................................... ENABLEDC’est la seule vérification qui compte : elle affiche la valeur réellement utilisée par l’application, cache compris.
Le piège : la configuration en cache
Vous passez APP_DEBUG=false, vous rechargez, et les traces d’erreur s’affichent toujours. C’est presque toujours le cache de configuration.
Quand php artisan config:cache a été exécuté, Laravel écrit toutes les valeurs résolues dans bootstrap/cache/config.php et cesse complètement de lire le fichier .env. Le comportement a été mesuré :
| Étape | config('app.debug') | env('APP_DEBUG') |
|---|---|---|
APP_DEBUG=true, sans cache | true | true |
après config:cache, puis passage à false dans .env | true | NULL |
après config:clear | false | false |
Deux enseignements. Le premier : après toute modification du .env sur un serveur où la configuration est en cache, il faut la régénérer.
php artisan config:clear
# ou, en production, régénérer directement le cache
php artisan config:cacheC’est la conséquence la plus mal connue, et elle ne concerne pas que le débogage. Un appel à env('MA_CLE') ailleurs que dans un fichier de config/ renverra null dès que config:cache aura tourné. La règle est stricte : env() uniquement dans config/, et partout ailleurs config('fichier.cle').
Ce que contient config/app.php
La clé de configuration se contente de lire la variable d’environnement, avec false comme valeur de repli :
'debug' => (bool) env('APP_DEBUG', false),Ne modifiez pas cette ligne. Elle est écrite pour que le comportement par défaut soit sûr : si APP_DEBUG est absent du .env, le mode débogage reste désactivé. Vérifié en supprimant la variable, config('app.debug') renvoie bien false.
Mettre la valeur en dur dans config/app.php a deux inconvénients : le fichier est versionné, donc le réglage part sur tous les environnements, et le .env devient trompeur.
Les valeurs acceptées suivent les règles de conversion de Laravel, mesurées ligne à ligne :
Dans le .env | config('app.debug') |
|---|---|
APP_DEBUG=true ou (true) ou 1 | true |
APP_DEBUG=false ou 0 | false |
APP_DEBUG=yes | true |
| variable absente | false |
yes vaut true parce que la chaîne n’est pas reconnue comme un booléen et se retrouve castée. C’est une bonne raison de s’en tenir à true et false.
Pourquoi false en production n’est pas négociable
Avec APP_DEBUG=true, la page d’erreur affiche la trace d’appel, des extraits du code source et le contenu des variables d’environnement chargées. Un visiteur qui déclenche une erreur peut donc lire vos identifiants de base de données, vos clés d’API et la clé APP_KEY qui chiffre les sessions.
Il n’y a pas besoin de chercher : il suffit d’une URL qui provoque une exception. C’est la raison pour laquelle des applications Laravel se retrouvent compromises sans faille applicative particulière.
La configuration correcte d’un serveur de production, tel que celui monté dans l’installation de Laravel sur Debian, tient en trois lignes :
APP_ENV=production
APP_DEBUG=false
APP_URL=https://exemple.comPuis, après déploiement :
php artisan config:cache
php artisan about --only=environment # contrôle : Debug Mode doit afficher OFFLe même raisonnement vaut pour les formulaires publics, qu’il faut protéger contre les envois automatisés avant l’ouverture au public.
Les erreurs restent consultables, mais dans les journaux plutôt que dans le navigateur :
tail -f storage/logs/laravel.logCe chemin se construit avec storage_path(), décrit dans les chemins de l’application.
Erreurs fréquentes
config:cache, Laravel ne lit plus le fichier .env. Toute modification exige config:clear ou une régénération du cache.env() renvoie NULL partout ailleurs. Utilisez config('fichier.cle').
