Arquivo de ambiente e pastas com escrita: o que travar antes de abrir chamado

Duas causas explicam a maior parte das telas de erro logo depois de publicar um projeto em framework: o arquivo de ambiente ausente ou sem a chave da aplicação, e as pastas de cache e de logs sem permissão de escrita. Verifique as duas antes de procurar qualquer outra explicação — juntas, elas respondem pela maioria dos erros 500 em instalação nova.

O que o arquivo de ambiente guarda

Ele reúne tudo o que muda entre a sua máquina e o servidor: endereço do site, dados de conexão do banco, credenciais de envio de e-mail, chaves de serviços externos e a chave da aplicação. Por isso ele não entra no controle de versão e não é copiado de um ambiente para o outro sem revisão.

Três valores erram com frequência na primeira publicação: o endereço do site apontando ainda para o ambiente local, o modo de depuração ligado em produção — que mostra caminho de arquivo e trecho de código a qualquer visitante quando ocorre um erro — e o nome do banco copiado sem o prefixo que a hospedagem acrescenta.

Mantê-lo fora do alcance do navegador

Com o domínio apontando para a pasta pública do projeto, o arquivo de ambiente já fica inacessível por natureza, porque está um nível acima. Se por algum motivo o projeto estiver publicado inteiro na área pública, tente abrir o arquivo pelo endereço do site: se o conteúdo aparecer, trate como incidente — troque a senha do banco e as chaves expostas e corrija a estrutura antes de qualquer outra coisa.

As pastas que precisam de escrita

O framework grava log, cache de configuração, cache de visualizações, sessão e arquivos enviados. As pastas responsáveis por isso — a de armazenamento e a de cache de inicialização, com todas as subpastas — precisam ser graváveis pelo usuário que executa o PHP. Sem isso, o erro aparece antes mesmo de o site carregar a primeira página.

A permissão certa

Em hospedagem compartilhada, o PHP roda como o seu próprio usuário, então pastas com permissão de escrita para o dono já bastam. Não use permissão total para todo mundo como atalho: além de desnecessário nesse cenário, é justamente a configuração que permite a um arquivo malicioso gravar dentro do seu projeto. Se a escrita continuar falhando com a permissão correta, o problema costuma ser o dono do arquivo — típico de arquivo enviado por um usuário de FTP diferente do da conta.

Depois de mexer, limpe o cache

Se o projeto tiver cache de configuração gerado, alterar o arquivo de ambiente não muda nada até que esse cache seja recriado — o valor antigo continua valendo. Sempre que editar o ambiente em produção, limpe e gere o cache novamente. Muita gente perde tempo achando que a alteração não foi salva quando ela apenas não foi lida.