Download the PHP package josegonzalez/dotenv without Composer

PHP Dotenv

A .env file parsing and loading library for PHP.

• What is it and why should I use it?
• Rules to follow
• General Security Information

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:

Usage

Create a new loader:

Most methods return the loader directly, so the following is also possible:

You can use a .env file with any of the following features:

Example .env files are available in the fixtures directory.

Defining Constants

You can also define constants automatically from your env file:

Already defined constants will result in an immediate LogicException.

Adding to $_ENV

Already defined $_ENV entries will result in an immediate LogicException, unless $overwriteENV is set to true (default false).

Adding to $_SERVER

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 with mod_php.

Already defined apache_getenv() entries will result in an immediate LogicException, unless $overwriteAPACHE is set to true (default false).

Making available to getenv()

Already defined getenv() entries will result in an immediate LogicException, unless $overwriteENV is set to true (default false).

Setting key prefixes

Return as array

Return as json

Require environment variables

Turning off exceptions

Skip existing environment variables

It is possible to skip existing enviroment variables (e.g. in a containerized / Docker setup).

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:

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.

Note that you can optionally set configuration for your filters. These are passed to the __invoke method as the second argument.:

Filters can also be callables functions, which is useful in one-off situations. They are wrapped by the special CallableFilter.

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:

Finally, to invoke a filter, you must call filter() after calling parse().

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 uses parse_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.

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:

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:

• 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:

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.