API Reference

API Reference

The package exposes one worker class (Repository), a static facade over a shared instance of it (DotENV), one global helper (env()), and one exception type (DotENVException).

All classes live in the InitPHP\DotENV namespace (the exception in InitPHP\DotENV\Exceptions).

---

The Repository class

InitPHP\DotENV\Repository — the concrete worker. Use it directly for an isolated instance; the facade wraps a single shared one.

use InitPHP\DotENV\Repository;

$env = new Repository();
$env->create('/path/to/project');
$debug = $env->get('APP_DEBUG', false);

create()

public function create(string $path, bool $debug = true): void

Reads and defines a .env or .env.php file.

• $path — a path to a .env/.env.php file, or to a directory that contains one. For a directory, .env is tried first, then .env.php.
• $debug — when true (default), problems throw a DotENVException; when false, problems are ignored and the method returns without defining anything.

Values already present in $_ENV, $_SERVER, or getenv() are not overwritten. See Loading & Precedence.

get()

public function get(string $name, mixed $default = null): mixed

Returns an environment value, resolved $_ENV → $_SERVER → getenv(). String values are coerced and ${VAR} references are interpolated. Returns $default when the name is not defined anywhere.

The resolved value is cached on first read; later external changes to the same name are not seen until flush(). An undefined name is not cached.

$env->get('APP_ENV');            // value or null
$env->get('APP_ENV', 'local');   // value or 'local'

env()

public function env(string $name, mixed $default = null): mixed

Alias of get().

flush()

public function flush(): void

Removes every value this repository defined — from $_ENV, $_SERVER and getenv() — and clears the read cache. Pre-existing environment variables are left untouched (only what this instance loaded is removed).

$env->create('/app');
$env->flush();          // unload; the real environment is unchanged

---

The DotENV facade

InitPHP\DotENV\DotENV — a static facade that forwards create(), get(), env() and flush() to a single shared Repository, plus two lifecycle helpers.

use InitPHP\DotENV\DotENV;

DotENV::create(__DIR__);
DotENV::get('APP_ENV');
DotENV::env('APP_ENV');
DotENV::flush();

The forwarded calls (create, get, env, flush) have the same signatures as on Repository.

instance()

public static function instance(): Repository

Returns the shared repository, creating it on first use. Handy if you need the object itself (for DI, or to pass it somewhere).

$repo = DotENV::instance(); // the shared Repository

reset()

public static function reset(): void

Flushes the shared repository and discards it, so the next facade call builds a fresh one. Useful in tests and long-running workers. Pre-existing environment variables are left untouched.

DotENV::create(__DIR__);
DotENV::flush();   // unload, keep the instance
DotENV::reset();   // unload and drop the instance

---

The env() helper

A global function registered through Composer's files autoloader:

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

Equivalent to DotENV::get($name, $default), sharing the same shared repository. It is only defined if no other env() function already exists, so it won't clash with a framework that ships its own.

$appEnv = env('APP_ENV', 'production');

---

DotENVException

InitPHP\DotENV\Exceptions\DotENVException — the single exception type. It extends \InvalidArgumentException:

\InvalidArgumentException
 └── InitPHP\DotENV\Exceptions\DotENVException

So both of these catch it:

use InitPHP\DotENV\Exceptions\DotENVException;

try {
    DotENV::create('/app/.env');
} catch (DotENVException $e) {           // specific
    // ...
} catch (\InvalidArgumentException $e) { // or the parent
    // ...
}

See Error Handling for when it is thrown.

---

Backwards compatibility: Lib

Before 3.0 the worker class was named InitPHP\DotENV\Lib. That name still resolves — it is registered as an alias of Repository — so existing code keeps working:

$env = new \InitPHP\DotENV\Lib(); // works; instanceof Repository

It is deprecated. Use Repository in new code. See Migration from 2.x.

Quick index

Member	Type	Returns
Repository::create($path, $debug = true)	method	void
Repository::get($name, $default = null)	method	mixed
Repository::env($name, $default = null)	method	mixed
Repository::flush()	method	void
DotENV::create / get / env / flush	static (forwarded)	as above
DotENV::instance()	static	Repository
DotENV::reset()	static	void
env($name, $default = null)	function	mixed
DotENVException	class	extends \InvalidArgumentException