Dotenv · NeoPHP

The Dotenv package reads .env files and populates $_ENV and $_SERVER, without any dependency. The kernel uses it to load .env, .env.local, .env.{APP_ENV} and .env.{APP_ENV}.local; real environment variables always win.

Environment files

The kernel loads, in this order (later files override earlier ones):

File	Committed	Purpose
`.env`	yes	default values
`.env.local`	no	local overrides (not loaded when `APP_ENV=test`)
`.env.{APP_ENV}`	yes	values for one environment (`.env.prod`, `.env.test`...)
`.env.{APP_ENV}.local`	no	local overrides for one environment

When APP_ENV is not defined, it is set to dev. Real environment variables (server, Docker...) always win over the files; a variable defined by a previous file can be overridden by a later one.

The values are read in the YAML configuration with the %env(NAME)% placeholders (see the Config documentation).

File format

APP_NAME="My application"
APP_ENV=dev
APP_DEBUG=1
export DB_USER=root
DATABASE_URL="mysql://${DB_USER}@localhost/app"
CACHE_DIR=${CACHE_ROOT:-/tmp/cache}
PASSWORD='p@ss${not_interpolated}'
GREETING="Hello\nWorld"
TIMEOUT=30 # seconds
PRIVATE_KEY="-----BEGIN KEY-----
abc
-----END KEY-----"

Syntax	Behavior
`NAME=value`	names: letters, digits, `_` and `.`; spaces around `=` allowed
`export NAME=value`	the `export` prefix is ignored
`# comment`	full-line comment; `value # comment` after an unquoted value
`'value'`	literal: no escape, no interpolation
`"value"`	escapes `\n`, `\r`, `\t`, `\"`, `\\`, `\$`; interpolation; can span several lines
`${NAME}`	value of a variable defined earlier in the file or in the environment (unquoted and double-quoted values)
`${NAME:-default}`	`default` when the variable is undefined or empty

A malformed line, a missing closing quote or characters after a quoted value throw a DotenvException with the line and the file.

Framework variables

Variable	Default	Description
`APP_ENV`	`dev`	environment name
`APP_DEBUG`	`true` unless `APP_ENV=prod`	shows the detailed error page
`APP_NAME`		application name (`framework.app.name`)
`APP_SECRET`	none	key used to sign cookies, generated by `neo install`
`APP_URL`	none	base URL of the absolute URLs generated in the console (`framework.app.url`)
`DATABASE_URL`	`sqlite:///%kernel.root_path%/var/data.db`	URL of the default database connection
`MAILER_DSN`, `MAILER_RECIPIENTS`		mailer transport and redirection (see the Mailer documentation)

php bin/neo install creates .env; when .env already exists, it adds the variables that are missing (see the Installer documentation).

Usage

<?php

declare(strict_types=1);

use NeoPHP\Package\Dotenv\DotenvManager;

$dotenv = new DotenvManager();

$dotenv->loadEnv(__DIR__);
$dotenv->load(__DIR__ . '/.env.extra');

$values = $dotenv->parse("A=1\nB=\${A}2");
$dotenv->populate(['FEATURE_X' => '1'], true);

In the application, inject NeoPHP\Package\Dotenv\Contract\DotenvInterface.

API

DotenvInterface

NeoPHP\Package\Dotenv\Contract\DotenvInterface, implemented by DotenvManager (extends AbstractDotenv):

Method	Description
`parse(string $content, ?string $path = null): array`	parses a content into `name => value` without populating; `$path` is used in error messages
`load(string ...$paths): void`	parses and populates files; a missing or unreadable file throws a `DotenvException`
`loadEnv(string $directory, string $envKey = 'APP_ENV', string $defaultEnv = 'dev'): void`	loads the `.env` files of a directory in the order above; missing files are ignored
`populate(array $values, bool $overrideExisting = false): void`	writes values in `$_ENV` and `$_SERVER` (not `$_SERVER` for `HTTP_*`); real variables are kept unless `$overrideExisting`

AbstractDotenv::LOADED_VARS (NEOPHP_DOTENV_VARS): variable listing the names loaded from files, so that later files can override them.

Other classes

Class	Description
`Parser\Parser`	`parse(string $content, ?string $path = null, array $known = []): array`; `$known` values are used for interpolation
`Provider\DotenvProvider`	registers `DotenvInterface`
`Exception\DotenvException`	unreadable file or syntax error; `DotenvException::syntax(string $message, int $line, ?string $path)`

Changelog

v1.0.0 — .env, .env.local, .env.{APP_ENV} and .env.{APP_ENV}.local files, quotes, multi-line values, interpolation.