Environment Variables & .env Cascade#

The .env family of files is loaded with the standard cascade of symfony/dotenv.

Load order (priority)#

.env — committed defaults
.env.local — local override (gitignored)
.env.{APP_ENV} — environment-specific defaults (committed)
.env.{APP_ENV}.local — environment-specific local override (gitignored)

A nonexistent file is silently skipped.
A value already in $_ENV / $_SERVER / getenv() **takes

precedence** over the base .env (the process environment wins). The .local files override the committed versions.

Do not write secrets in .env. .env is normally committed. Put auth tokens etc. in the gitignored .env.local.

Example .env:

APP_ENV=dev
DATABASE_DSN=mysql:host=127.0.0.1;dbname=app;charset=utf8mb4
DATABASE_USER=app
DATABASE_PASSWORD=secret

Available environment variables#

Variable	Use
`APP_ENV`	`dev`/`development` enables PSX on-the-fly compilation + profiler. Anything else (including unset) is treated as production
`DATABASE_DSN`	PDO connection string. If unset, the Db layer is not registered
`DATABASE_USER`	DB username
`DATABASE_PASSWORD`	DB password
`DATABASE_TIMEOUT`	Connection timeout in seconds (`PDO::ATTR_TIMEOUT`)
`DATABASE_READ_TIMEOUT`	MySQL read timeout in seconds (optional)
`USEPHP_SNAPSHOT_SECRET`	Secret key for signing snapshot state (required if using `StorageType::Snapshot` in production)
`PROFILER_EXCLUDED_PATHS`	Profiler-excluded paths (comma-separated, prefix match)
`HTTP_CLIENT_TIMEOUT`	HTTP client overall request timeout in seconds (optional)
`HTTP_CLIENT_CONNECT_TIMEOUT`	HTTP client connection-establishment timeout in seconds (optional)
`LOG_LEVEL`	Logger threshold. One of the 8 PSR-3 levels (default dev=`debug`/production=`info`; a misspelling soft-fails to the default)
`LOG_FILE`	Logger output path (STDERR if unset)
`APP_LOCALE`	Internationalization default/active locale (default `en`)
`APP_LOCALES`	Supported locales (comma-separated. Default is `APP_LOCALE` only. Two or more enable locale switching)
`LOCALE_COOKIE`	Cookie name that carries the locale (default `locale`. CDN-safe, no session needed)
`LOCALE_PATH_PREFIX`	Opt-out of `/{locale}/...` routing (default `true`)

DATABASE_* are optional, and the Db layer is registered in the DI container only when DATABASE_DSN is set (see Database).

APP_LOCALE / APP_LOCALES / LOCALE_COOKIE / LOCALE_PATH_PREFIX are also optional; if you set none of them it stays single-locale (English) at no cost (see Internationalization).

Variables specific to this site#

The above are framework (relayer) variables. This documentation site (relayer-doc) itself additionally reads the article store's TURSO_DATABASE_URL / TURSO_AUTH_TOKEN (var/docs.db if unset) and the following. All are set as Fly secrets.

Variable	Use
`GA_MEASUREMENT_ID`	GA4 measurement ID (only the `G-XXXXXXXXXX` form is accepted). Only when set does it emit gtag.js in the production `<head>`. If unset, it emits nothing = dev/local has no measurement

See Deployment for details.