# ADR-032 — Perfis de ambiente dirigidos por `APP_ENV`

| Campo | Valor |
|---|---|
| **Status** | Aceito (2026-10-16) |
| **Data** | 2026-10-15 |
| **Relacionadas** | ADR-001, ADR-008, ADR-024, ADR-006, ADR-030 |

## Contexto

O `.env` foi crescendo com variáveis redundantes (`APP_DEBUG`, `FORCE_HTTPS`, `LOG_LEVEL`,
`SESSION_SECURE_COOKIE`, `TELEMETRY_ENABLED`, `CACHE_STORE`, …), fáceis de divergir e difíceis
de revisar. Trocar o ambiente exigia lembrar de ajustar cada flag manualmente — inclusive no
`php.ini` (OPcache/`zend.assertions`), que não é ajustável em runtime.

## Decisão

- **`APP_ENV` é o único interruptor.** `config/environments.php` resolve o perfil ativo
  (`production` · `homolog` · `dev`; `local`/`testing` mapeiam para variantes) e os demais
  arquivos de `config/` consomem esses defaults.
- **`dev`:** **sem OPcache** e **sem caches do Laravel** (`optimize`), debug total — erros na
  tela, `error_reporting=E_ALL`, log `debug`, `db_query_log`, `log_deprecations_channel`.
- **`homolog`:** espelha produção, mas com OPcache revalidando (`validate_timestamps=1`) e log
  em `debug`.
- **`production`:** OPcache `validate_timestamps=0`, caches do Laravel via `php artisan optimize`,
  log `info`, HTTPS forçado e **cookies endurecidos** (`SECURITY_COOKIES` → prefixo `__Host-`,
  `Secure`, `Secure`+`HttpOnly`+`SameSite=Lax` e `session.use_strict_mode`).
- **OPcache/assertions no entrypoint:** `docker/php-fpm/entrypoint.sh` gera um `php.ini` extra
  (`storage/framework/php-env/zzz-env.ini`) a partir do `APP_ENV` e o injeta via
  `PHP_INI_SCAN_DIR` — são diretivas que precisam valer antes do PHP subir.
- **Defaults ideais, `.env` mínimo.** O que for ajustável em runtime vira default de `config/`;
  overrides pontuais (`APP_DEBUG`, `LOG_LEVEL`, …) continuam possíveis e são documentados em
  `config/_OTHER_CONFIGS.md`.

## Justificativa (alternativas descartadas)

- **Dezenas de flags no `.env`** — descartada: redundância e divergência entre ambientes.
- **Perfis em arquivos `.env.<env>`** — descartada: mais arquivos para manter (o `.env` é só
  identidade + segredos).
- **Ajustar OPcache em runtime** — impossível: `opcache.enable`/`zend.assertions` são de startup.
- **`docker-compose.prod.yml` separado** — descartada: quebra o "um único interruptor".

## Consequências

**Positivas**
- Trocar `APP_ENV` ajusta debug, cache, logs/observabilidade e cookies de forma consistente.
- `.env` enxuto (identidade + segredos); defaults revisáveis e versionados.

**Custos / negativas**
- Após trocar `APP_ENV`, é preciso recriar containers/reiniciar o FPM (OPcache/entrypoint).
- `php.ini` de runtime é gerado (uma duplicação consciente da tabela de perfis — ADR-001).

## Verificação

- `EnvironmentConfigTest`: perfil `testing` (debug, sem HTTPS forçado, sem request/query log) e
  canal `stack`+`daily` com 730 dias.
- Runtime: `docker compose exec php-fpm` → `opcache.enable=0`, `display_errors=1`,
  `zend.assertions=1` em `dev`; `opcache.enable=1`, `validate_timestamps=0` em `production`.
- `make check` verde; `config/_OTHER_CONFIGS.md` descreve overrides e defaults.

## Referências

- `config/environments.php`, `config/_OTHER_CONFIGS.md`, `docker/php-fpm/entrypoint.sh`.
- `wiki/specs/06-observabilidade.md`, `wiki/specs/17-up-prod.md`.