Download the PHP package m1/env without Composer

Env

Env is a lightweight library bringing .env file parser compatibility to PHP. In short - it enables you to read .env files with PHP.

• Why?
• Requirements
• Install
• Usage
  • Basic
  • Context variables
  • Syntax
    • Assignment
    • Strings
    • Numbers
    • Booleans
    • Null
    • Variables
      • Default Value/Assignment
    • Comments
  • .env example
• Notes
  • Source
• Other library comparisons
• Todo
• Change log
• Testing
• Contributing
• Security
• Credits
• License

Why?

Env aims to bring a unified parser for env together for PHP rather than having a few incomplete or buggy parsers written into other libraries. This library is not meant as a complete package for config loading like other libraries as this is out of scope for this library. If you need something like that check out Vars which incorporates this library so you can load Env and other file types if you want, or checkout PHP Dotenv if you only need .env parsing

Requirements

Env requires PHP version 5.3+ - supported and tested on 5.3, 5.4, 5.5, 5.6, 7 and hhvm.

Install

Via Composer

Usage

Basic

test.env

example.php

Context variables

test_context.env

example_context.php

Syntax

The Syntax is slightly more relaxed than bash, but still remains quite bash like

Assignment

To assign values the syntax is key = value, unlike bash the assignment is pretty relaxed, any of the below are valid:

However keys can not start with a number, e.g.:

Will throw a ParseException

You can also add export to the start of variables to source the file in bash (see here for more info):

Strings

Strings can either be in quotes (single or double) or without:

To escape new lines or quotes is the standard backslash:

If you feature two quoted strings as a value then only the first quoted string will be assigned to the key:

Numbers

Numbers are fairly standard:

Decimal numbers will be automatically cast to floats:

If you quote numbers they will be counted as strings, or if you have two numbers on one line:

Booleans

Booleans can be true, false, yes and no:

Booleans are case-insensitive:

Booleans in quotes will be treated as strings:

Null

Both of the below are counted as null values:

Whereas an empty string is counted as a string:

Variables

Variables are based of the bash syntax:

The types of variable get passed to the calling variable if there is only one variable. If there are more than one variable, the calling variable is automatically cast to a string:

Also if the variable is in quotes then the variable will be automatically cast as a string:

But you can use variables without quotes and they'll be cast as strings:

Variables are useful to use in strings like so:

Null values are passed and casted as empty strings if in quotes:

Single Quotes with variables will be counted as strings:

Parameter Expansion

You can do parameter expansion, so far you can only do default values and assign default values like in the bash syntax:

The default value parameter expansion syntax is :-, the explanation on the bash-hackers wiki for this is:

SYNTAX:

${PARAMETER:-WORD}

${PARAMETER-WORD}

If the parameter PARAMETER is unset (never was defined) or null (empty), this one expands to WORD, otherwise it expands to the value of PARAMETER, as if it just was ${PARAMETER}. If you omit the : (colon), like shown in the second form, the default value is only used when the parameter was unset, not when it was empty.

For example:

The assign default value parameter expansion is :=, the explanation on the bash-hackers wiki for this is:

SYNTAX:

${PARAMETER:=WORD}

${PARAMETER=WORD}

This one works like the using default values, but the default text you give is not only expanded, but also assigned to the parameter, if it was unset or null. Equivalent to using a default value, when you omit the : (colon), as shown in the second form, the default value will only be assigned when the parameter was unset.

For example:

Comments

To comment, just use the # syntax, you can also comment inline like so:

If you put a # without a space in a unquoted string, it will be parsed as a string:

.env example

The result from this library and the expected result of the above is:

Notes

Source

If you need the .env variables in other applications, you can source the env, but make sure it's valid bash syntax, as this parser allows a more relaxed form of bash syntax.

This library will always be able to parse bash syntax, but for now the opposite (env syntax -> bash syntax) may not be true, however this is being worked on to bring a strict parser version for 3.0

Other library comparisons

The difference between this library and other similar libraries:

zrcing/phpenv:

• Converts all value types to string
• Does not support null values
• Does not support int, float or bool types
• Does not support variables

Dotenv\Dotenv:

• Does not support unquoted values like 33 33, this should be cast to string. See TEST12
• Does not support concatenation of variables unquoted like ${VAR} ${VAR2}, this should be cast to string. See TEST33
• Both of the above crash Dotenv without a helpful exception
• Converts all value types to string
• Does not support null values
• Does not support int, float or bool types
• Does not support variables
• Does not support parameter expansions
• Does not support inline comments where there is no value. See TEST66

Todo

• Other bash parameter expansions

Change log

Please see CHANGELOG for more information what has changed recently.

Testing

Contributing

Please see CONDUCT for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• m1
• All Contributors

License

The MIT License (MIT). Please see License File for more information.