Why does getenv('DATABASE_URL') return false in PHP under PHP-FPM when the variable is set in the service's environment?

## Where the variable goes missing PHP-FPM has two kinds of process: - The **master**, started by systemd, a container entrypoint or an init script. It inherits the environment of whatever started it — including `DATABASE_URL` if you set it there. - The **workers**, forked from the master, which execute PHP code. Each pool decides what environment its workers get, through `clear_env`: | `clear_env` | Worker environment | |---|---| | `yes` (default) | Emptied, then only the pool's `env[...]` entries are added | | `no` | Inherited from the master, plus the pool's `env[...]` entries | The PHP-FPM sample configuration describes `clear_env` as preventing "arbitrary environment variables from reaching FPM worker processes". With the default, `getenv('DATABASE_URL')` returns `false`, `$_ENV` lacks it, and so does `$_SERVER` — even though the same variable is visible to a CLI script run in the same container. ## Fix 1: pass specific variables with env[] ```ini [app] env[DATABASE_URL] = $DATABASE_URL env[APP_ENV] = production env[PATH] = /usr/local/bin:/usr/bin:/bin ``` - A value beginning with **`$`** is looked up in the **master's** environment when the pool is configured; if the master does not have it, the worker gets an empty string, not a missing variable. - A plain value is used literally. - These entries are added after the clearing, so they work with `clear_env = yes`. This is the precise option: PHP code sees exactly the variables you list. It also documents, in one file, which configuration the application depends on. ## Fix 2: clear_env = no Setting `clear_env = no` passes the master's whole environment to the workers. It is common in container images, where the environment is built specifically for the application and the list of variables changes often. The trade-off: - Every variable of the service reaches PHP code — including ones meant for other tools, such as cloud credentials or a proxy password. - Any code path that dumps the environment (a debug page, `phpinfo()`, an error handler that logs `$_SERVER`) now exposes all of them. ## Things that still surprise people 1. **Reload or restart needed.** Values are copied from the master's environment when the pool is set up. Editing `env[]` lines needs a reload; changing the service's environment needs a full restart, because the master only has the environment it was started with. 2. **Empty, not missing.** `env[X] = $X` with `X` unset in the master gives `getenv('X') === ''`, which code checking for `false` treats as present. 3. **CLI differs.** Cron jobs and queue workers run the CLI, not FPM, and see the shell's environment directly; a variable can work in console commands and fail in web requests. 4. **The web server is a different source.** Variables set in the web server's FastCGI parameters arrive in `$_SERVER` as request parameters, not in the worker's process environment; `getenv()` in FPM can return those too, so the two sources are easy to confuse. ## A container example A typical image starts `php-fpm` as PID 1 with variables injected by the orchestrator. Two working setups: ```ini ; explicit list (preferred when the set is stable) [www] env[DATABASE_URL] = $DATABASE_URL env[CACHE_URL] = $CACHE_URL ``` ```ini ; pass everything (simpler, broader exposure) [www] clear_env = no ``` ## Different values per pool Because `env[]` lines live in each pool section, one FPM master can give each application its own environment: the shop pool with `env[DATABASE_URL] = $SHOP_DATABASE_URL`, the blog pool with `env[DATABASE_URL] = $BLOG_DATABASE_URL`. Each application reads the same variable name and gets its own database, and neither sees the other's credentials — which `clear_env = no` would give away. ## Checking what a worker sees A temporary script behind the pool, `var_dump(getenv('DATABASE_URL'));`, shows the worker's view; compare with `printenv DATABASE_URL` in the container shell, which shows the master's. If they differ, the pool's `clear_env` and `env[]` lines are the place to look. Remove the script afterwards; reading configuration in application code is a separate concern from getting it into the worker.