README

Loads environment variables from a .env or .env.php file into PHP's environment ($_ENV, $_SERVER, getenv()), with type coercion and ${VAR} interpolation.

Requirements

PHP 8.0 or higher
No extensions beyond the PHP core

Installation

composer require initphp/dotenv

Quick start

/home/www/.env:

# Comment line
SITE_URL = http://lvh.me
PAGE_URL = ${SITE_URL}/page

; Another comment
TRUE_VALUE  = true
FALSE_VALUE = false
NULL_VALUE  = null
EMPTY_VALUE = empty

NUMERIC_VALUE = 13
PI_NUMBER     = 3.14
ZIP_CODE      = 007

require 'vendor/autoload.php';

use InitPHP\DotENV\DotENV;

DotENV::create('/home/www/.env');     // or DotENV::create('/home/www');

DotENV::get('SITE_URL');      // "http://lvh.me"
DotENV::get('PAGE_URL');      // "http://lvh.me/page"
DotENV::get('TRUE_VALUE');    // true       (bool)
DotENV::get('FALSE_VALUE');   // false      (bool)
DotENV::get('NULL_VALUE');    // null
DotENV::get('EMPTY_VALUE');   // ""         (string)
DotENV::get('NUMERIC_VALUE'); // 13         (int)
DotENV::get('PI_NUMBER');     // 3.14       (float)
DotENV::get('ZIP_CODE');      // "007"      (string — leading zero preserved)

DotENV::get('NOT_FOUND', 'hi'); // "hi"

env('SITE_URL');              // global helper, same shared state

Prefer an isolated instance (e.g. for DI or tests)? Use the Repository directly:

use InitPHP\DotENV\Repository;

$env = new Repository();
$env->create('/home/www/.env');
$env->get('SITE_URL');

File format in brief

KEY = VALUE — split on the first =; whitespace around the key is trimmed.
Comments start a line with anything other than a letter/digit/_/- (#, ;, //); inline comments start at a # preceded by whitespace.
Quote a value ("..." or '...') to keep it verbatim, including a leading # such as #ffffff.
${OTHER} references are expanded when the value is read.
true / false / null / empty and round-tripping numbers are coerced; everything else stays a string.

Full details: docs/.

API summary

Call	Returns	Purpose
`DotENV::create(string $path, bool $debug = true)`	`void`	Load a `.env`/`.env.php` file or a directory containing one.
`DotENV::get(string $name, mixed $default = null)`	`mixed`	Read a value (`$_ENV` → `$_SERVER` → `getenv()`).
`DotENV::env(string $name, mixed $default = null)`	`mixed`	Alias of `get()`.
`DotENV::flush()`	`void`	Unload everything this instance defined.
`DotENV::reset()`	`void`	`flush()` and drop the shared instance.
`env(string $name, mixed $default = null)`	`mixed`	Global helper for `DotENV::get()`.

See the API reference for details.

Notes

Immutability: values already in $_ENV or $_SERVER are never overwritten, so real environment variables win over a committed .env.
$debug: when false, create() swallows every error (missing file, wrong type, unreadable) instead of throwing a DotENVException.
Security: keep .env files out of the web root, and remember a .env.php file is executed as code — see the security notes.

Upgrading from 2.x

3.0 is a maintenance-focused major release. The public API (DotENV::create, get, env and the env() helper) is unchanged, but note:

PHP 8.0+ is now required (was 5.6+).
Numbers are only coerced when it is loss-free. 007 and +90555… now stay strings instead of becoming 7 and a float.
Real bug fixes change previously broken results: directory-path loading, multiple ${VAR} references on one line, quoted values with spaces around =, and values like #ffffff all work now.
The internal Lib class is renamed Repository; Lib remains as a deprecated alias.

See the changelog for the full list.

Contributing

Bug reports and pull requests are welcome. The CI runs PHP-CS-Fixer, PHPStan (max level) and PHPUnit across PHP 8.0–8.4; run the same bundle locally with:

composer ci

Credits

Muhammet ŞAFAK <info@muhammetsafak.com.tr>

initphp / dotenv

Maintainers

Package info

Fund package maintenance!

Statistics

Security