josegonzalez / dotenv
dotenv file parsing for PHP
Installs: 7 422 261
Dependents: 149
Suggesters: 7
Security: 0
Stars: 279
Watchers: 11
Forks: 36
Open Issues: 4
Requires
- php: >=5.5.0
- m1/env: 2.*
Requires (Dev)
- php-coveralls/php-coveralls: ~2.0
- php-mock/php-mock-phpunit: ~1.1||~2.0
- squizlabs/php_codesniffer: ~2.9||~3.7
README
PHP Dotenv
A .env
file parsing and loading library for PHP.
Requirements
- PHP 5.5+
Installation
[Using Composer]
Run composer require josegonzalez/dotenv:
Or add the plugin to your project's composer.json
- something like this:
{ "require": { "josegonzalez/dotenv": "3.3.0" } }
Usage
Create a new loader:
<?php $Loader = new josegonzalez\Dotenv\Loader('path/to/.env'); // Parse the .env file $Loader->parse(); // Send the parsed .env file to the $_ENV variable $Loader->toEnv(); ?>
Most methods return the loader directly, so the following is also possible:
<?php $Loader = (new josegonzalez\Dotenv\Loader('path/to/.env')) ->parse() ->toEnv(); // Throws LogicException if ->parse() is not called first ?>
You can use a .env
file with any of the following features:
# comments are allowed FOO=bar # you can also have comments on the end of a line export BAR=baz # you can optionally begin with an `export` statement # both single and double quotes are allowed BAZ='qux' QUX="quux" # as are escaped quotes or similar: QUUX="corge \" grault" CORGE='garply" waldo' # unquoted values containing [null, true, false] are turned into # their PHP equivalents PHP_NULL=null PHP_TRUE=true PHP_FALSE=false # when quoted, they are simply string values STRING_NULL="null" STRING_TRUE="true" STRING_FALSE="false" # spaces are allowed as well # in a slightly more relaxed form from bash GRAULT =fred GARPLY = plugh SPACES=" quote values with spaces" # will contain preceding space # When using newlines, you should use quoted values QUOTED_NEWLINE="newline\\nchar" # you can even have nested variables using `${VAR}` syntax # remember to define the nested var *before* using it WALDO=${xyzzy} # not yet defined, so will result in WALDO = `{}` THUD=${GARPLY} # will be defined as `plugh` # note that variables beginning with a character # other than [a-zA-Z_] shall throw a ParseException 01SKIPPED=skipped # However, numbers *are* allowed elsewhere in the key NOT_SKIPPED1=not skipped # will have the value `not`
Example
.env
files are available in the fixtures directory.
Defining Constants
You can also define constants automatically from your env file:
<?php $Loader = (new josegonzalez\Dotenv\Loader('path/to/.env')) ->parse() ->define(); // Throws LogicException if ->parse() is not called first ?>
Already defined constants will result in an immediate LogicException
.
Adding to $_ENV
<?php $overwriteENV = true; $Loader = (new josegonzalez\Dotenv\Loader('path/to/.env')) ->parse() ->toEnv($overwriteENV); // Throws LogicException if ->parse() is not called first ?>
Already defined $_ENV
entries will result in an immediate LogicException
, unless $overwriteENV
is set to true
(default false
).
Adding to $_SERVER
<?php $overwriteSERVER = true; $Loader = (new josegonzalez\Dotenv\Loader('path/to/.env')) ->parse() ->toServer($overwriteSERVER); // Throws LogicException if ->parse() is not called first ?>
Already defined $_SERVER
entries will result in an immediate LogicException
, unless $overwriteSERVER
is set to true
(default false
).
Making available to apache_getenv()
This should be preferred over
getenv
when using the Apache web server withmod_php
.
<?php $overwrite = true; $Loader = (new josegonzalez\Dotenv\Loader('path/to/.env')) ->parse() ->apacheSetenv($overwriteAPACHE); // Throws LogicException if ->parse() is not called first // May throw a PHP Error if either apache_setenv() or apache_putenv() are not available ?>
Already defined apache_getenv()
entries will result in an immediate LogicException
, unless $overwriteAPACHE
is set to true
(default false
).
Making available to getenv()
<?php $overwrite = true; $Loader = (new josegonzalez\Dotenv\Loader('path/to/.env')) ->parse() ->putenv($overwriteENV); // Throws LogicException if ->parse() is not called first ?>
Already defined getenv()
entries will result in an immediate LogicException
, unless $overwriteENV
is set to true
(default false
).
Setting key prefixes
<?php $environment = (new josegonzalez\Dotenv\Loader('path/to/.env')) ->parse() ->prefix('FOO') ->toServer(); // BAR=baz becomes FOOBAR=baz ?>
Return as array
<?php $environment = (new josegonzalez\Dotenv\Loader('path/to/.env')) ->parse() ->toArray(); // Throws LogicException if ->parse() is not called first ?>
Return as json
<?php $jsonEnvironment = (string)((new josegonzalez\Dotenv\Loader('path/to/.env'))->parse()); ?>
Require environment variables
<?php $Loader = (new josegonzalez\Dotenv\Loader('path/to/.env')) ->parse() ->expect('FOO', 'BAR', 'BAZ'); // Throws RuntimeException if variables are missing ?>
Turning off exceptions
<?php $Loader = (new josegonzalez\Dotenv\Loader('path/to/.env')) ->raiseExceptions(false) ->parse() ->expect('FOO', 'BAR', 'BAZ'); // Returns false if variables are missing ?>
Skip existing environment variables
It is possible to skip existing enviroment variables (e.g. in a containerized / Docker setup).
<?php $Loader = (new josegonzalez\Dotenv\Loader('path/to/.env')) ->parse() ->skipExisting() //Skip any environment variables that are already present ->putenv(); ?>
Filtering environments
It is possible to optionally filter the environment data produced by php-dotenv through the use of filter classes. A filter class has an __invoke
method like so:
<?php class LollipopFilter { /** * Sets every key's value to the string `lollipop` * * @param array $environment Array of environment data * @param array $config Array of configuration data that includes the callable * @return array */ public function __invoke(array $environment, array $config) { $newEnvironment = []; foreach ($environment as $key => $value) { $newEnvironment[$key] = 'lollipop'; } return $newEnvironment; } } ?>
You can attach filters using the setFilters()
method, which will override all currently specified filters. If an invalid filter is specified, a LogicException will be thrown.
<?php $Loader = (new josegonzalez\Dotenv\Loader('path/to/.env')) ->setFilters(['LollipopFilter']); // Takes an array of namespaced class names ?>
Note that you can optionally set configuration for your filters. These are passed to the __invoke
method as the second argument.:
<?php $Loader = (new josegonzalez\Dotenv\Loader('path/to/.env')) ->setFilters([ 'LollipopFilter' => ['paintshop'], ]); // Takes an array of namespaced class names ?>
Filters can also be callables functions, which is useful in one-off situations. They are wrapped by the special CallableFilter
.
<?php $Loader = (new josegonzalez\Dotenv\Loader('path/to/.env')) ->setFilters([function ($data) { return $data; }]); ?>
If you need special configuration for your callable filters, you can prefix your callable with __callable__N
, where N
is the integer index the callable is in your array. The callable itself should be contained in a callable
config key, as follows:
<?php $Loader = (new josegonzalez\Dotenv\Loader('path/to/.env')) ->setFilters([ '__callable__0' => [ 'callable' => function ($data, $config) { return $data; }, 'someKey' => 'value', ] ]); ?>
Finally, to invoke a filter, you must call filter()
after calling parse()
.
<?php $Loader = (new josegonzalez\Dotenv\Loader('path/to/.env')) ->setFilters(['LollipopFilter']) ->parse() ->filter(); ?>
Available Filters
The following filters are built into php-dotenv.
josegonzalez\Dotenv\Filter\CallableFilter
: Wraps a callable and invokes it upon the environment.josegonzalez\Dotenv\Filter\LowercaseKeyFilter
: Lowercases all the keys for an environment to a single-depth.josegonzalez\Dotenv\Filter\NullFilter
: Returns the environment data without any changes.josegonzalez\Dotenv\Filter\RemapKeysFilter
: Remaps specific keys in a$config
array to a set of values at a single-depth.josegonzalez\Dotenv\Filter\UnderscoreArrayFilter
: Expands a flat array to a nested array. For example,['0_Foo_Bar' => 'Far']
becomes[['Foo' => ['Bar' => 'Far']]]
.josegonzalez\Dotenv\Filter\UppercaseFirstKeyFilter
: Uppercases the first letter for all the keys for an environment to a single-depth..josegonzalez\Dotenv\Filter\UrlParseFilter
: When there is a key with the suffix_URL
, this filter usesparse_url
to add extra data to the environment.
Static Environment Definition
You can also call it via the static load
method call, which takes an array of arguments. If a method name is specified, the method is called with the value in the $options
array being sent into the method.
<?php josegonzalez\Dotenv\Loader::load(array( 'filepath' => 'path/to/.env', 'expect' => array('FOO', 'BAR', 'BAZ'), 'toEnv' => true, 'toServer' => true, 'define' => true, )); ?>
Validating External Environments
In some cases it may be necessary to validate that a given array of environment data matches your requirements. You can use the Loader->expect()
functionality via the standalone Expect
class:
<?php use josegonzalez\Dotenv\Expect; $expect = new Expect($env); $expect('FOO'); // Raises a RuntimeException if `env` is missing FOO // You can turn off exception raising using the second `raise` argument $expect = new Expect($env, false); $expect('FOO'); // Returns false if `env` is missing FOO ?>
What is it and why should I use it?
When developing and deploying your applications you are typically interacting with various environments - production and development for instance. These environments both execute your code, but will do so using different credentials. You may also wish to distribute your application to developers without accidentally giving them access to important external services.
Simple examples include authentication keys to your email provider or database connection credentials. You would never want to accidentally send testing emails to all your users, or run a DROP TABLE
statement against production because you ran your unit tests.
How do you tackle these differing credentials? The php-dotenv
helps solve this issue by allowing you to configure your environments in a universal fashion, making it easy to safely switch between environments, as well as share those environments with multiple projects/languages.
Need more reasons? Check out the twelve-factor app docs on configuration.
Rules to follow
When using php-dotenv
, you should strive to follow the following rules:
-
Add your
.env
file to a gitignore and use a.env.default
or.env.example
to set defaults for your projects. This allows your development team to override defaults in a method that works for their local environment. -
Always set sane development defaults for any credential. If necessary, disable features when those credentials are "invalid".
-
Where necessary, add comments to credentials with information as to what they are, how they are used, and how one might procure new ones.
-
As
php-dotenv
uses more lax procedures for defining environment variables, ensure your.env
files are compatible with your shell. A good way to test this is to run the following:# source in your .env file source .env # check the environment env
-
Avoid running
php-dotenv
in production settings, and instead set environment variables in your webserver, process manager, or in bash before running your commands. A simple way to ensure this is to check for the existence of a sentinel environment variable that is only set in production:// APP_NAME isn't set in staging/dev if (!env('APP_NAME')) { $loader = new josegonzalez\Dotenv\Loader([ __DIR__ '/.env', __DIR__ '/.env.default' ]); $loader->parse()->toEnv(); }
General Security Information
If you configure php-dotenv
to output configuration in any of the ways listed above and then dump them, they may be available to undesired users. For instance, using a project like filp/whoops in conjunction with $Loader->toServer()
can result in outputting sensitive data to your users if you leave whoops enabled in production.
For this reason, php-dotenv
never populates data to an environment variable by default and requires that the developer make a conscious decision about how they want to use loaded environment variables
Many error reporting tools have the option of whitelisting or blacklisting sensitive data, and you should familiarize yourself with said tooling.
License
The MIT License (MIT)
Copyright (c) 2013 Jose Diaz-Gonzalez
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.