Tryb debugowania ustawia się przez APP_DEBUG w pliku .env: true lokalnie, false na produkcji, zawsze. Stan faktyczny sprawdzisz komendą php artisan about --only=environment. Jeśli zmiana nie odnosi skutku, konfiguracja siedzi w cache'u: uruchom php artisan config:clear.
Tryb debugowania decyduje o tym, co zobaczy odwiedzający, kiedy aplikacja się wywali: pełny stos wywołań z kodem źródłowym i zmiennymi środowiskowymi albo neutralną stronę błędu. To ustawienie na jedną linijkę, a zarazem jeden z najczęstszych wycieków danych na produkcji.
Artykuł ze ścieżki Programowanie webowe. Sprawdzone na Laravelu 13.30.1 z PHP 8.4.25.
Włączanie i wyłączanie
Ustawienie zmienia się w pliku .env w katalogu głównym projektu i nigdzie indziej:
APP_ENV=local
APP_DEBUG=trueŻeby je wyłączyć, ustaw wartość na false:
APP_ENV=production
APP_DEBUG=falseStan faktyczny sprawdzisz bez pisania choćby jednej linijki kodu:
php artisan about --only=environment Environment ........................................................ local
Debug Mode ...................................................... ENABLEDTo jedyna kontrola, która się liczy: pokazuje wartość naprawdę używaną przez aplikację, razem z cache’em.
Pułapka: konfiguracja w cache’u
Ustawiasz APP_DEBUG=false, odświeżasz stronę, a stosy błędów wciąż się wyświetlają. Prawie zawsze winny jest cache konfiguracji.
Po wykonaniu php artisan config:cache Laravel zapisuje wszystkie rozwiązane wartości do bootstrap/cache/config.php i całkowicie przestaje czytać plik .env. Zachowanie zostało zmierzone:
| Krok | config('app.debug') | env('APP_DEBUG') |
|---|---|---|
APP_DEBUG=true, bez cache’u | true | true |
po config:cache, potem zmiana na false w .env | true | NULL |
po config:clear | false | false |
Dwa wnioski. Pierwszy: po każdej zmianie w .env na serwerze z konfiguracją w cache’u trzeba ten cache odbudować.
php artisan config:clear
# albo, na produkcji, od razu odbudować cache
php artisan config:cacheTo najsłabiej znana konsekwencja i dotyczy nie tylko debugowania. Wywołanie env('MA_CLE') poza plikiem z katalogu config/ zwróci null, gdy tylko przejdzie config:cache. Reguła jest ostra: env() wyłącznie w config/, wszędzie indziej config('fichier.cle').
Co zawiera config/app.php
Klucz konfiguracyjny tylko odczytuje zmienną środowiskową, z false jako wartością zapasową:
'debug' => (bool) env('APP_DEBUG', false),Nie zmieniaj tej linijki. Napisano ją tak, żeby domyślne zachowanie było bezpieczne: jeśli APP_DEBUG nie ma w .env, tryb debugowania pozostaje wyłączony. Sprawdzone przez usunięcie zmiennej, config('app.debug') faktycznie zwraca false.
Wpisanie wartości na sztywno w config/app.php ma dwie wady: plik jest wersjonowany, więc ustawienie rozejdzie się po wszystkich środowiskach, a .env zaczyna kłamać.
Akceptowane wartości podlegają regułom konwersji Laravela, zmierzonym wiersz po wierszu:
W pliku .env | config('app.debug') |
|---|---|
APP_DEBUG=true albo (true), albo 1 | true |
APP_DEBUG=false albo 0 | false |
APP_DEBUG=yes | true |
| brak zmiennej | false |
yes daje true, bo ten ciąg nie jest rozpoznawany jako wartość logiczna i zostaje rzutowany. To dobry powód, żeby trzymać się true i false.
Dlaczego false na produkcji nie podlega dyskusji
Przy APP_DEBUG=true strona błędu pokazuje stos wywołań, fragmenty kodu źródłowego i zawartość załadowanych zmiennych środowiskowych. Odwiedzający, który wywoła błąd, przeczyta więc dane dostępowe do bazy, klucze API i klucz APP_KEY, którym szyfrowane są sesje.
Nie trzeba niczego szukać: wystarczy URL wywołujący wyjątek. Właśnie dlatego aplikacje Laravel bywają przejmowane bez żadnej szczególnej luki w kodzie.
Poprawna konfiguracja serwera produkcyjnego, takiego jak ten postawiony w instalacji Laravela na Debianie, mieści się w trzech linijkach:
APP_ENV=production
APP_DEBUG=false
APP_URL=https://exemple.comA po wdrożeniu:
php artisan config:cache
php artisan about --only=environment # kontrola: Debug Mode musi pokazywać OFFTo samo rozumowanie dotyczy publicznych formularzy, które przed otwarciem dla wszystkich trzeba zabezpieczyć przed automatycznymi wysyłkami.
Błędy nadal da się przejrzeć, tyle że w logach, a nie w przeglądarce:
tail -f storage/logs/laravel.logTę ścieżkę buduje storage_path(), opisana w ścieżkach aplikacji.
Częste błędy
config:cache Laravel nie czyta już pliku .env. Każda zmiana wymaga config:clear albo odbudowania cache'u.env() zwraca NULL we wszystkich innych miejscach. Używaj config('fichier.cle').
