O modo de depuração define-se com APP_DEBUG no ficheiro .env: true em local, false em produção, sempre. Confirma o estado real com php artisan about --only=environment. Se a alteração não fizer efeito, a configuração está em cache: corre php artisan config:clear.
O modo de depuração decide o que um visitante vê quando a tua aplicação rebenta: o rastreio completo com o código-fonte e as variáveis de ambiente, ou uma página de erro neutra. É uma definição de uma linha, mas é também uma das fugas de dados mais frequentes em produção.
Artigo do percurso Desenvolvimento web. Verificado em Laravel 13.30.1 com PHP 8.4.25.
Ativar e desativar
A definição faz-se no ficheiro .env, na raiz do projeto, e em mais lado nenhum:
APP_ENV=local
APP_DEBUG=truePara o desativar, passa o valor a false:
APP_ENV=production
APP_DEBUG=falseConfirma o estado efetivo sem escrever uma única linha de código:
php artisan about --only=environment Environment ........................................................ local
Debug Mode ...................................................... ENABLEDÉ a única verificação que conta: mostra o valor realmente usado pela aplicação, cache incluída.
A armadilha: a configuração em cache
Passas APP_DEBUG=false, recarregas, e os rastreios de erro continuam a aparecer. É quase sempre a cache de configuração.
Quando o php artisan config:cache foi executado, o Laravel escreve todos os valores resolvidos em bootstrap/cache/config.php e deixa completamente de ler o ficheiro .env. O comportamento foi medido:
| Etapa | config('app.debug') | env('APP_DEBUG') |
|---|---|---|
APP_DEBUG=true, sem cache | true | true |
depois de config:cache, com passagem a false no .env | true | NULL |
depois de config:clear | false | false |
Duas lições. A primeira: depois de qualquer alteração ao .env num servidor onde a configuração está em cache, é preciso regenerá-la.
php artisan config:clear
# ou, em produção, regenerar diretamente a cache
php artisan config:cacheÉ a consequência menos conhecida, e não diz respeito apenas à depuração. Uma chamada a env('MA_CLE') fora de um ficheiro de config/ devolve null assim que o config:cache tiver corrido. A regra é estrita: env() apenas em config/, e em todo o resto config('ficheiro.chave').
O que contém o config/app.php
A chave de configuração limita-se a ler a variável de ambiente, com false como valor de recurso:
'debug' => (bool) env('APP_DEBUG', false),Não mexas nesta linha. Está escrita para que o comportamento por predefinição seja seguro: se o APP_DEBUG não existir no .env, o modo de depuração fica desativado. Verificado ao remover a variável: config('app.debug') devolve mesmo false.
Fixar o valor diretamente no config/app.php tem dois inconvenientes: o ficheiro está versionado, por isso a definição segue para todos os ambientes, e o .env passa a ser enganador.
Os valores aceites seguem as regras de conversão do Laravel, medidas linha a linha:
No .env | config('app.debug') |
|---|---|
APP_DEBUG=true ou (true) ou 1 | true |
APP_DEBUG=false ou 0 | false |
APP_DEBUG=yes | true |
| variável ausente | false |
yes vale true porque a cadeia não é reconhecida como booleano e acaba convertida. É uma boa razão para te limitares a true e false.
Porque é que false em produção não se negoceia
Com APP_DEBUG=true, a página de erro mostra o rastreio de chamadas, excertos do código-fonte e o conteúdo das variáveis de ambiente carregadas. Um visitante que provoque um erro pode assim ler as tuas credenciais da base de dados, as tuas chaves de API e a chave APP_KEY que cifra as sessões.
Não é preciso procurar muito: basta um URL que provoque uma exceção. É por isso que há aplicações Laravel comprometidas sem qualquer falha aplicacional em particular.
A configuração correta de um servidor de produção, como o que é montado na instalação do Laravel em Debian, cabe em três linhas:
APP_ENV=production
APP_DEBUG=false
APP_URL=https://exemple.comDepois, uma vez feito o deploy:
php artisan config:cache
php artisan about --only=environment # verificação: Debug Mode deve mostrar OFFO mesmo raciocínio vale para os formulários públicos, que é preciso proteger contra os envios automatizados antes da abertura ao público.
Os erros continuam consultáveis, mas nos registos e não no navegador:
tail -f storage/logs/laravel.logEste caminho constrói-se com storage_path(), descrito em os caminhos da aplicação.
Erros frequentes
config:cache, o Laravel deixa de ler o ficheiro .env. Qualquer alteração exige config:clear ou uma regeneração da cache.env() devolve NULL em todo o resto. Usa config('ficheiro.chave').
