socarrat/environment

A super simple dotenv file parser that is compatible with getenv().

v0.1.0 2023-05-06 19:01 UTC

Requires (Dev)

• phpunit/phpunit: ^9.5

MIT

• Romein van Buren

README

A super simple .env file parser that is compatible with getenv().

Features

• Parses .env files and does it well
• Parses .env files from the filesystem and from string input
• Special characters
• Compatible with getenv(): no need to adapt your existing applications
• Fault-tolerant
• Well-tested
• Multi-line values
• Support for comments (WIP)
• Invalid file warnings (WIP)

Installation

Download this package on Packagist:

composer require socarrat/environment

Usage

The EnvironmentManager is responsible for parsing .env files on the filesystem (or, if you like, as strings). It does so on request: you need to call one (or more) of the parsing methods (see API) to load your environment variables.

How about getenv()?

One of the parameters of the parse functions is bool $putenv. If you set this to true (default), putenv() will be called for every parsed variable. If you already use getenv(), there's no need to adapt your program: you only need to call a parse function once at the start.

Examples

See the examples/ directory for some usage examples.

.env file format

The basics

A .env file contains key-value pairs of environment-specific settings. Each line contains a key-value pair. Keys should be capitalised, and should only contain A-Z characters and underscores. Thereafter comes an = sign, and then the value. See the following example:

DB_ENGINE=mysql
DB_NAME=example

Quoted values

To avoid confusion, you could enclose the value in double quotes ".

DB_PASSWORD="Welkom2018"

Note that single quotes ' are NOT stripped from the value! For example, the value of DB_TABLE='users' is 'users' and not users.

Multi-line values

Multi-line values are supported, provided that the value is enclosed in double quotes.

TEXT="Calculate density using:

  ρ = m/V

where ρ is the density,
      m is the mass,
  and V is the volume.
"

Special characters

You can use the following special characters in your values:

Example:

ESCAPED_VALUES="Escape \t tabs \t, \n newlines \n, and \"quotes\" with a \\backslash\\"

Whitespace handling

Whitespace is handled thus:

• Leading whitespace before keys is ignored.

• Trailing whitespace after values is always trimmed, except when the value including whitespace is enclosed by double quotes.

• Leading whitespace on a newline that is part of the value is honoured.

• Trailing whitespace on a newline that is part of the value is always ignored, except when the line is the last line that is part of the value and the whitespace comes before the closing double quote.

API

class Socarrat\Environment\EnvironmentManager

static public function getParsedEnv(): array

Returns all parsed environment variables as an associative array.

static public function parseFS(string $rootDir, bool $putenv = true)

Parses .env files from the filesystem.

This method reads the files in the order specified in EnvironmentManager::$fileOrder. You can set this order using setFileOrder.

static public function parseString(string $envFile, bool $putenv = true)

Parses a single .env file passed as a string.

static public function setFileOrder(array $order): void

Sets the order (passed as the $order parameter) in which .env files are loaded. Lower index means higher importance.

The default file order is:

[
	".env.local",
	".env.shared",
	".env",
]

Testing

This library is unit-tested by PHPunit using the tests in the tests/ directory. You can run the test suite on your machine (composer run-script test). Test results for each commit (run on Ubuntu 22.04) are available on GitHub.

Copyright

(c) 2023 Romein van Buren. Licensed under the MIT license.

For the full copyright and license information, please view the license.md file that was distributed with this source code.