Home

InitPHP DotENV — Wiki

Welcome to the official documentation for initphp/dotenv — a small, dependency-free environment-variable loader for PHP 8.0+.

It reads a .env (or .env.php) file, pushes the values into PHP's environment ($_ENV, $_SERVER, getenv()), and reads them back with type coercion and ${VAR} interpolation — without ever overwriting a real environment variable.

composer require initphp/dotenv

use InitPHP\DotENV\DotENV;

DotENV::create(__DIR__);          // loads __DIR__/.env (or .env.php)

DotENV::get('APP_ENV', 'local');  // → string|int|float|bool|null
env('APP_ENV', 'local');          // global helper, same shared state

Given this .env:

APP_ENV   = production
APP_DEBUG = false
DB_PORT   = 5432
SITE_URL  = https://example.test
PAGE_URL  = ${SITE_URL}/page
ZIP_CODE  = 007

you get correctly typed values back:

DotENV::get('APP_ENV');   // "production"  (string)
DotENV::get('APP_DEBUG'); // false         (bool)
DotENV::get('DB_PORT');   // 5432          (int)
DotENV::get('PAGE_URL');  // "https://example.test/page"  (interpolated)
DotENV::get('ZIP_CODE');  // "007"         (string — leading zero preserved)

The package in one table

Symbol	Role
DotENV	Static facade over a shared repository — the usual entry point.
Repository	The worker doing the loading/parsing/reading; use directly for an isolated instance.
env()	Global helper function, equivalent to DotENV::get().
DotENVException	The single exception type, extends \InvalidArgumentException.

Start here

• New to the package? Read Installation, then Quick Start.
• Writing a .env file? The .env File Format spells out every parsing rule.
• Wondering why 007 stays a string? Value Types & Coercion.
• Chaining values with ${VAR}? Variable Interpolation.
• Coming from 2.x? Read Migration from 2.x — 3.0 raises the PHP floor and changes value coercion.
• Looking for a specific method? The full API Reference lists every public member.

What you get

• Two file formats. Plain-text .env or a .env.php that returns a native PHP array.
• Smart, loss-free typing. true/false/null/empty become real PHP values; numbers become int/float only when it round-trips, so 007, +90555…, oversized integers and 1e3 stay strings. See Value Types & Coercion.
• ${VAR} interpolation. References are resolved on read, support multiple and nested references on one line, and never recurse forever on a cycle. See Variable Interpolation.
• Real env vars always win. create() never overwrites a name already defined in $_ENV, $_SERVER, or getenv(). See Loading & Precedence.
• One exception type. Every failure raises DotENVException; one catch covers everything, and $debug = false turns failures into silent no-ops. See Error Handling.
• Test-friendly. flush() / reset() unload exactly what was loaded, leaving the real environment untouched. See Testing.

At a glance — behaviour

Input in the file	get() returns
KEY=hello	"hello" (string)
KEY=true / KEY=false	true / false (bool)
KEY=null	null
KEY=empty or KEY=	"" (string)
KEY=42 / KEY=-3.5	42 (int) / -3.5 (float)
KEY=007 / KEY=+15551234	"007" / "+15551234" (string)
KEY=" spaced "	" spaced " (quotes stripped, content verbatim)
KEY=#ffffff	"#ffffff" (leading # kept)
KEY=val # note	"val" (inline comment stripped)
KEY=${OTHER}/x	OTHER's value + /x (interpolated)

Package metadata

• License: MIT
• Minimum PHP: 8.0
• Required extensions: none beyond the PHP core
• Runtime dependencies: none
• Packagist: initphp/dotenv
• Source: github.com/InitPHP/DotENV
• Issues: github.com/InitPHP/DotENV/issues
• Discussions: github.com/orgs/InitPHP/discussions

If something in this wiki is unclear, wrong, or out of date, open an issue — documentation fixes are merged eagerly.