$_ENV

What Are Environment Variables?

In simple terms: Environment variables are named settings provided by the system that runs your program — for example, the database password, the API key for a payment service, or whether the application runs in "development" or "production" mode. The code stays the same everywhere; only the environment changes.

Technically: Every process on Linux, macOS, and Windows has an environment: a set of NAME=value strings inherited from the process that started it (a shell, a web server, a container runtime, or a process manager). PHP exposes them through the $_ENV superglobal (when enabled), through getenv(), and — depending on the server API — through $_SERVER.

Why Configuration Belongs in the Environment

Hard-coding settings causes real problems:

// Bad: credentials inside the code

\$pdo \= new PDO('mysql:host=localhost;dbname=shop', 'root', 'MySecretPass123');

 

• Secrets leak when the code is pushed to a Git repository or shared.
• Different environments (your laptop, a staging server, production) need different values, so the code would have to be edited for each.

Reading configuration from the environment solves both problems: the same code reads DB_PASSWORD, and each machine provides its own value. This approach is a core principle of the widely used Twelve-Factor App methodology.

---

$_ENV Is Often Empty

<?php

// Run: php env-check.php

var_dump(count(\$_ENV));

var_dump(getenv('HOME'));

var_dump(getenv('DOES_NOT_EXIST'));

 

Output (Linux, with the recommended php.ini; the home directory depends on your user)

int(0)

string(10) "/home/asha"

bool(false)

 

Why $_ENV Is Empty

$_ENV is filled only if the variables_order setting contains the letter E. The recommended php.ini files set variables_order = "GPCS" — without E — for performance reasons, so $_ENV stays empty. The environment variables still exist; they are simply not copied into $_ENV.

Method	Works With Recommended Settings?	Notes
getenv('NAME')	Yes	Returns the value as a string, or false if not set
$_SERVER['NAME']	Usually	Depends on the server API; the CLI includes environment variables
$_ENV['NAME']	Only if variables_order contains E, or a library fills it	Many .env loaders write values here

 

---

Setting Environment Variables

Command Line

APP_ENV=production DB_PORT=3307 php config.php

 

Variables placed before the command apply to that process only.

Web Servers and PHP-FPM

Environment	How to Set Variables
Apache	SetEnv APP_ENV production in the virtual host configuration
Nginx + PHP-FPM	fastcgi_param APP_ENV production; in Nginx, or env[APP_ENV] = production in the FPM pool configuration
Docker	environment: in docker-compose.yml, or -e APP_ENV=production
Hosting panels and PaaS	A "Environment Variables" settings page

 

PHP-FPM note: By default, FPM's clear_env = yes setting removes environment variables inherited from the shell that started FPM. Define variables explicitly with env[...] in the pool configuration (or set clear_env = no).

---

.env Files for Local Development

During development, it is convenient to keep settings in a .env file in the project root:

APP_ENV=local
APP_DEBUG=true
DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=shop
DB_USER=shop_user
DB_PASSWORD=change-me

 

PHP does not read .env files by itself. The popular library vlucas/phpdotenv loads them (and frameworks such as Laravel use it):

composer require vlucas/phpdotenv

 

<?php

require __DIR__ . '/vendor/autoload.php';

 

\$dotenv \= Dotenv\Dotenv::createImmutable(__DIR__);

\$dotenv->safeLoad();

\$dotenv->required(['DB_HOST', 'DB_NAME', 'DB_USER', 'DB_PASSWORD']);

 

echo \$_ENV['DB_NAME'];

 

How It Works

• createImmutable() reads .env but does not overwrite variables that already exist in the real environment. This lets a server's real environment variables take priority over the file.
• safeLoad() does not fail if the .env file is missing (typical in production, where real environment variables are used); load() would throw an exception.
• required() throws an exception at startup if essential settings are missing, so misconfiguration is discovered immediately rather than at the first database query.
• Loaded values are placed in $_ENV and $_SERVER.

Keep .env Out of Version Control

# .gitignore
.env

 

Commit a .env.example file with the variable names and harmless placeholder values instead, so other developers know what to configure. Also make sure the .env file is outside the public web root, so it can never be downloaded through a URL.

---

Reading Configuration With Defaults and Types

Environment values are always strings. A small helper can provide defaults and convert common literal values:

<?php

// config.php

function env(string \$key, mixed \$default \= null): mixed

{

    \$value \= \$_ENV[\$key] ?? \$_SERVER[\$key] ?? getenv(\$key);

 

    if (\$value \=== false || \$value \=== null) {

        return \$default;

    }

 

    return match (strtolower(trim(\$value))) {

        'true' \=> true,

        'false' \=> false,

        'null' \=> null,

        '' \=> \$default,

        default \=> \$value,

    };

}

 

\$config \= [

    'env' \=> env('APP_ENV', 'local'),

    'debug' \=> env('APP_DEBUG', true),

    'db_host' \=> env('DB_HOST', '127.0.0.1'),

    'db_port' \=> (int) env('DB_PORT', 3306),

];

 

var_export(\$config);

echo "\n";

 

Run

APP_ENV=production APP_DEBUG=false DB_PORT=3307 php config.php

 

Output

array (

  'env' \=> 'production',

  'debug' \=> false,

  'db_host' \=> '127.0.0.1',

  'db_port' \=> 3307,

)

 

Step-by-Step Explanation

1. The helper checks $_ENV, then $_SERVER, then getenv(), so it works whether values come from a .env loader or the real environment.
2. The string 'false' is converted to the boolean false. Without this, if (getenv('APP_DEBUG')) would treat 'false' as true, because any non-empty string is truthy.
3. DB_HOST is not set, so the default is used.
4. Numeric settings are cast explicitly with (int).

Laravel's env() helper follows the same idea. In frameworks, env() is typically called only inside configuration files, and the rest of the application reads the resulting configuration values.

---

Security Considerations

• Never print the environment. phpinfo(), debug pages, and error reports can display all environment variables, including passwords. Disable debug output in production and never leave phpinfo() pages online.
• Do not log secrets. Mask passwords and tokens when logging configuration.
• Limit access. Restrict who can read server configuration files and .env files.
• Prefer $_ENV/$_SERVER in threaded environments. getenv() and putenv() are not thread-safe in multi-threaded server setups; libraries like phpdotenv therefore write to $_ENV and $_SERVER by default.
• Consider dedicated secret managers (cloud secret stores, Vault) for large or regulated systems.

---

Common Mistakes

Expecting $_ENV to Contain Values

Effect: $_ENV['DB_HOST'] is undefined with the recommended php.ini.

Fix: Use getenv(), a .env loader, or a helper that checks several sources.

Treating 'false' as Boolean

Effect: Debug mode turns on when APP_DEBUG=false.

Fix: Convert strings explicitly ('true'/'false').

Committing .env Files

Effect: Credentials are exposed in the repository history.

Fix: Ignore .env in Git, commit .env.example, and rotate any leaked secrets.

Forgetting PHP-FPM's clear_env

Effect: Variables set in the shell are missing in web requests.

Fix: Configure env[...] entries in the FPM pool.

Reading Environment Variables Throughout the Code

Effect: Hidden dependencies scattered across the application.

Fix: Read the environment once into a configuration array or object, and pass configuration where it is needed.

---

Best Practices

• Store credentials and environment-specific settings in environment variables, never in code.
• Use .env files only for local development, keep them out of Git, and validate required variables at startup.
• Convert values to the correct types and provide defaults in one central configuration step.
• Never expose environment variables through phpinfo(), error pages, or logs.

Official reference: https\://www.php.net/manual/en/reserved.variables.environment.php