Configuração
Variáveis de ambiente, config PHP e requisitos de produção.
Arquivo de ambiente
O bootstrap carrega .env via Dotenv e então inclui config/app.php. Valores secretos devem ficar no ambiente, não em arquivos versionados.
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost:8000
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=app_db
DB_USERNAME=app_user
DB_PASSWORD=senha-local
SESSION_SECURE=false
CORS_ALLOWED_ORIGINS=http://localhost:3000A chave pode ser criada/atualizada com php mvc key:generate; o comando requer que .env exista.
Arquivos de configuração
config/app.php: ambiente, exibição de erros, timezone, charset, cookies de sessão e URL base.config/database.php: conexão padrão MySQL por PDO.config/api.php: timeout de ApiClient, CORS, provider de pagamento e provider CEP.config/mail.php: driver de e-mail e credenciais SMTP.
APP_URL e proxy
Se APP_URL estiver preenchida, ela precisa conter esquema HTTP(S) e host válidos. Sem valor, a detecção é permitida fora de produção. Em produção a aplicação lança exceção sem URL configurada. Cabeçalhos encaminhados de proxy só são considerados quando o endereço remoto está em TRUSTED_PROXIES.
Configuração segura
Cookies usam HttpOnly e modo estrito; SESSION_LIFETIME configura a duração. Embora config/app.php aplique SESSION_SAME_SITE em ini_set, Session::start() chama session_set_cookie_params() com SameSite=Lax, sobrescrevendo esse valor. Cookies secure são forçados em produção. APP_DEBUG resulta falso em produção mesmo se a variável disser true. Consulte Sessões e CSRF e Middleware e proteção.
config/api.php, mas isso não significa que um gateway esteja implementado. O provider resolvido atualmente cai no NullPaymentGateway.Escolha valores por ambiente
Mantenha segredos em variáveis do ambiente, fora do controle de versão. O bloco abaixo é um perfil de desenvolvimento; em produção, use HTTPS, APP_DEBUG=false e APP_URL absoluta.
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost:8000
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=app_db
DB_USERNAME=app_user
DB_PASSWORD=senha-local
SESSION_SECURE=false
CORS_ALLOWED_ORIGINS=http://localhost:3000| Grupo | Variáveis principais | Efeito |
|---|---|---|
| Aplicação | APP_ENV, APP_DEBUG, APP_KEY, APP_URL, APP_TIMEZONE | Erro exibido, URL base e fuso |
| Banco | DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD | Conexão MySQL/PDO; charset/collation têm defaults em config/database.php |
| Sessão | SESSION_LIFETIME, SESSION_SECURE, SESSION_SAME_SITE | Duração e atributos dos cookies |
| API | API_TIMEOUT, CORS_ALLOWED_ORIGINS, TRUSTED_PROXIES | Cliente de saída, origens e proxy confiável |
| Correio | MAIL_DRIVER, MAIL_HOST, MAIL_PORT e remetente | Comportamento do Mailer |
Produção e cabeçalhos de proxy
APP_URL deve conter esquema e host HTTP(S) válidos e é obrigatória em produção. Fora de produção, a aplicação pode inferi-la da requisição. Valores X-Forwarded-* só influenciam URL/IP quando REMOTE_ADDR corresponde a uma entrada em TRUSTED_PROXIES; configure essa lista apenas com os endereços dos proxies que você controla.
APP_ENV=production
APP_DEBUG=false
APP_URL=https://app.exemplo.com
SESSION_SECURE=true
CORS_ALLOWED_ORIGINS=https://cliente.exemplo.comOs guias de sessão/CSRF e middleware/CORS detalham os efeitos desses valores.
Variáveis lidas pelo código
A tabela distingue variáveis consumidas por configuração/bootstrap e valores apenas citados como exemplos. DB_CHARSET e DB_COLLATION são lidas em config/database.php, embora não apareçam no .env.example; seus defaults são utf8mb4 e utf8mb4_unicode_ci.
| Área | Chaves reais | Observação verificável |
|---|---|---|
| Aplicação | APP_NAME, APP_URL, APP_ENV, APP_DEBUG, APP_KEY, APP_TIMEZONE | APP_URL absoluta HTTP(S) obrigatória em produção; APP_DEBUG efetivo é false em produção. |
| MySQL/PDO | DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD, DB_CHARSET, DB_COLLATION | Única conexão real declarada: MySQL. |
| Sessão | SESSION_LIFETIME, SESSION_SECURE, SESSION_SAME_SITE | Lifetime e Secure são aplicados por Session; Session::start fixa SameSite em Lax e sobrescreve SESSION_SAME_SITE. |
MAIL_DRIVER, MAIL_FROM_NAME, MAIL_FROM_ADDRESS, MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD, MAIL_ENCRYPTION | Drivers configurados: dev, log e smtp; dev/log não enviam mensagem. | |
| API/CORS/proxy | API_TIMEOUT, CORS_ALLOWED_ORIGINS, TRUSTED_PROXIES | Timeout de saída, origens em lista separada por vírgula e IPs de proxy confiável. |
| Integrações | CEP_PROVIDER, PAYMENT_PROVIDER, MERCADOPAGO_ACCESS_TOKEN, MERCADOPAGO_PUBLIC_KEY, ASAAS_API_KEY, ASAAS_ENVIRONMENT | Chaves de configuração não provam que todo fluxo/provider funcione; confira o estado real das integrações. |
Não publique valores secretos. APP_KEY, credenciais SMTP, banco e gateways devem ser configurados fora do repositório. Para uploads/sessões, confira as permissões de escrita de storage/; o framework usa diretórios sob essa árvore para sessões, logs e cache.
APP_DEBUG: configuração efetiva e ressalva do Router
config/app.php força a constante efetiva APP_DEBUG para false quando APP_ENV=production. Porém, o fallback de erro de Router::handleServerError() consulta diretamente $_ENV['APP_DEBUG'] === 'true', em vez da constante já normalizada. Com APP_ENV=production e APP_DEBUG=true no ambiente, esse caminho pode incluir mensagem e stack trace na resposta 500.
APP_DEBUG=false no ambiente de produção e valide o valor no deploy. Enquanto essa divergência existir, não presuma que a normalização da constante oculta detalhes em todo caminho de erro. Esta documentação descreve a implementação atual; corrigir a divergência exige alteração no framework, fora do escopo documental.