PHPackages                             publiux/phpdotenv - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. publiux/phpdotenv

ActiveLibrary[Utility & Helpers](/categories/utility)

publiux/phpdotenv
=================

Loads environment variables from `.env` to `getenv()`, `$\_ENV` and `$\_SERVER`, and Docker secrets automagically.

v3.0.1(8y ago)0178BSD-3-Clause-AttributionPHPPHP >=5.3.9

Since Feb 1Pushed 8y ago1 watchersCompare

[ Source](https://github.com/publiux/phpdotenv)[ Packagist](https://packagist.org/packages/publiux/phpdotenv)[ RSS](/packages/publiux-phpdotenv/feed)WikiDiscussions master Synced 2d ago

READMEChangelog (2)Dependencies (1)Versions (4)Used By (0)

PHP dotenv
==========

[](#php-dotenv)

Loads environment variables from `.env` to `getenv()`, `$_ENV` and `$_SERVER` automagically.

This is a PHP version of the original [Ruby dotenv](https://github.com/bkeepers/dotenv).

[![Build Status](https://camo.githubusercontent.com/17103387ffb9f7850054e95a03d2d71dc9e5d62760acc37f48d6957c000b54cb/68747470733a2f2f7472617669732d63692e6f72672f766c756361732f706870646f74656e762e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/vlucas/phpdotenv)

Why .env?
---------

[](#why-env)

**You should never store sensitive credentials in your code**. Storing [configuration in the environment](http://www.12factor.net/config) is one of the tenets of a [twelve-factor app](http://www.12factor.net/). Anything that is likely to change between deployment environments – such as database credentials or credentials for 3rd party services – should be extracted from the code into environment variables.

Basically, a `.env` file is an easy way to load custom configuration variables that your application needs without having to modify .htaccess files or Apache/nginx virtual hosts. This means you won't have to edit any files outside the project, and all the environment variables are always set no matter how you run your project - Apache, Nginx, CLI, and even PHP 5.4's built-in webserver. It's WAY easier than all the other ways you know of to set environment variables, and you're going to love it.

- NO editing virtual hosts in Apache or Nginx
- NO adding `php_value` flags to .htaccess files
- EASY portability and sharing of required ENV values
- COMPATIBLE with PHP's built-in web server and CLI runner

Installation with Composer
--------------------------

[](#installation-with-composer)

```
curl -s http://getcomposer.org/installer | php
php composer.phar require vlucas/phpdotenv
```

Usage
-----

[](#usage)

The `.env` file is generally kept out of version control since it can contain sensitive API keys and passwords. A separate `.env.example` file is created with all the required environment variables defined except for the sensitive ones, which are either user-supplied for their own development environments or are communicated elsewhere to project collaborators. The project collaborators then independently copy the `.env.example` file to a local `.env` and ensure all the settings are correct for their local environment, filling in the secret keys or providing their own values when necessary. In this usage, the `.env`file should be added to the project's `.gitignore` file so that it will never be committed by collaborators. This usage ensures that no sensitive passwords or API keys will ever be in the version control history so there is less risk of a security breach, and production values will never have to be shared with all project collaborators.

Add your application configuration to a `.env` file in the root of your project. **Make sure the `.env` file is added to your `.gitignore` so it is not checked-in the code**

```
S3_BUCKET="dotenv"
SECRET_KEY="souper_seekret_key"
```

Now create a file named `.env.example` and check this into the project. This should have the ENV variables you need to have set, but the values should either be blank or filled with dummy data. The idea is to let people know what variables are required, but not give them the sensitive production values.

```
S3_BUCKET="devbucket"
SECRET_KEY="abc123"
```

You can then load `.env` in your application with:

```
$dotenv = new Dotenv\Dotenv(__DIR__);
$dotenv->load();
```

Optionally you can pass in a filename as the second parameter, if you would like to use something other than `.env`

```
$dotenv = new Dotenv\Dotenv(__DIR__, 'myconfig');
$dotenv->load();
```

All of the defined variables are now accessible with the `getenv`method, and are available in the `$_ENV` and `$_SERVER` super-globals.

```
$s3_bucket = getenv('S3_BUCKET');
$s3_bucket = $_ENV['S3_BUCKET'];
$s3_bucket = $_SERVER['S3_BUCKET'];
```

You should also be able to access them using your framework's Request class (if you are using a framework).

```
$s3_bucket = $request->env('S3_BUCKET');
$s3_bucket = $request->getEnv('S3_BUCKET');
$s3_bucket = $request->server->get('S3_BUCKET');
$s3_bucket = env('S3_BUCKET');
```

### Nesting Variables

[](#nesting-variables)

It's possible to nest an environment variable within another, useful to cut down on repetition.

This is done by wrapping an existing environment variable in `${…}` e.g.

```
BASE_DIR="/var/webroot/project-root"
CACHE_DIR="${BASE_DIR}/cache"
TMP_DIR="${BASE_DIR}/tmp"
```

### Immutability

[](#immutability)

By default, Dotenv will NOT overwrite existing environment variables that are already set in the environment.

If you want Dotenv to overwrite existing environment variables, use `overload`instead of `load`:

```
$dotenv = new Dotenv\Dotenv(__DIR__);
$dotenv->overload();
```

### Docker Secrets

[](#docker-secrets)

Dotenv now support Docker secrets. By default, Dotenv can load these secrets as environment variables when the secret file is located in `/run/secrets`. To change this default, you can instantiate a new instance by passing a third argument to the constructor as follows:

```
$dotenv = new Dotenv\Dotenv(__DIR__, 'myconfig', '/secrets');
$dotenv->load();
```

To tell Dotenv to load a Docker secret, the name of the secret file in the secrets directory must end with two pipes `||` and contain no value. For example,

```
S3_BUCKET="dotenv"
SECRET_KEY="souper_seekret_key"
MYSQL_PASSWORD||
```

In this example, `MYSQL_PASSWORD` is a docker secret. By default, Dotenv will search `/run/secrets/MYSQL_PASSWORD` and load the value stored in that file as an environment variable name `MYSQL_PASSWORD`.

Requiring Variables to be Set
-----------------------------

[](#requiring-variables-to-be-set)

Using Dotenv, you can require specific ENV vars to be defined ($\_ENV, $\_SERVER or getenv()) - throws an exception otherwise. Note: It does not check for existence of a variable in a '.env' file. This is particularly useful to let people know any explicit required variables that your app will not work without.

You can use a single string:

```
$dotenv->required('DATABASE_DSN');
```

Or an array of strings:

```
$dotenv->required(['DB_HOST', 'DB_NAME', 'DB_USER', 'DB_PASS']);
```

If any ENV vars are missing, Dotenv will throw a `RuntimeException` like this:

```
One or more environment variables failed assertions: DATABASE_DSN is missing

```

### Empty Variables

[](#empty-variables)

Beyond simply requiring a variable to be set, you might also need to ensure the variable is not empty:

```
$dotenv->required('DATABASE_DSN')->notEmpty();
```

If the environment variable is empty, you'd get an Exception:

```
One or more environment variables failed assertions: DATABASE_DSN is empty

```

### Integer Variables

[](#integer-variables)

You might also need to ensure that the variable is of an integer value. You may do the following:

```
$dotenv->required('FOO')->isInteger();
```

If the environment variable is not an integer, you'd get an Exception:

```
One or more environment variables failed assertions: FOO is not an integer

```

### Boolean Variables

[](#boolean-variables)

You may need to ensure a variable is in the form of a boolean, accepting "On", "1", "Yes", "Off", "0" and "No". You may do the following:

```
$dotenv->required('FOO')->isBoolean();
```

If the environment variable is not a boolean, you'd get an Exception:

```
One or more environment variables failed assertions: FOO is not a boolean

```

### Allowed Values

[](#allowed-values)

It is also possible to define a set of values that your environment variable should be. This is especially useful in situations where only a handful of options or drivers are actually supported by your code:

```
$dotenv->required('SESSION_STORE')->allowedValues(['Filesystem', 'Memcached']);
```

If the environment variable wasn't in this list of allowed values, you'd get a similar Exception:

```
One or more environment variables failed assertions: SESSION_STORE is not an
allowed value

```

### Comments

[](#comments)

You can comment your `.env` file using the `#` character. E.g.

```
# this is a comment
VAR="value" # comment
VAR=value # comment
```

Usage Notes
-----------

[](#usage-notes)

When a new developer clones your codebase, they will have an additional **one-time step** to manually copy the `.env.example` file to `.env` and fill-in their own values (or get any sensitive values from a project co-worker).

phpdotenv is made for development environments, and generally should not be used in production. In production, the actual environment variables should be set so that there is no overhead of loading the `.env` file on each request. This can be achieved via an automated deployment process with tools like Vagrant, chef, or Puppet, or can be set manually with cloud hosts like Pagodabox and Heroku.

### Command Line Scripts

[](#command-line-scripts)

If you need to use environment variables that you have set in your `.env` file in a command line script that doesn't use the Dotenv library, you can `source`it into your local shell session:

```
source .env

```

Contributing
------------

[](#contributing)

1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Make your changes
4. Run the tests, adding new ones for your own code if necessary (`phpunit`)
5. Commit your changes (`git commit -am 'Added some feature'`)
6. Push to the branch (`git push origin my-new-feature`)
7. Create new Pull Request

###  Health Score

29

—

LowBetter than 59% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity10

Limited adoption so far

Community20

Small or concentrated contributor base

Maturity60

Established project with proven stability

 Bus Factor2

2 contributors hold 50%+ of commits

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

3024d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/344ed0b9242de3f0840ab90c3ab528adb1d8b1aefdb6ab59d452a2baed142c4d?d=identicon)[publiux](/maintainers/publiux)

---

Top Contributors

[![vlucas](https://avatars.githubusercontent.com/u/187?v=4)](https://github.com/vlucas "vlucas (56 commits)")[![GrahamCampbell](https://avatars.githubusercontent.com/u/2829600?v=4)](https://github.com/GrahamCampbell "GrahamCampbell (46 commits)")[![jpuck](https://avatars.githubusercontent.com/u/15305396?v=4)](https://github.com/jpuck "jpuck (8 commits)")[![thedavidmeister](https://avatars.githubusercontent.com/u/629710?v=4)](https://github.com/thedavidmeister "thedavidmeister (6 commits)")[![publiux](https://avatars.githubusercontent.com/u/2847188?v=4)](https://github.com/publiux "publiux (6 commits)")[![lucasmichot](https://avatars.githubusercontent.com/u/513603?v=4)](https://github.com/lucasmichot "lucasmichot (6 commits)")[![GabeMedrash](https://avatars.githubusercontent.com/u/8576080?v=4)](https://github.com/GabeMedrash "GabeMedrash (4 commits)")[![Ultrabenosaurus](https://avatars.githubusercontent.com/u/1901532?v=4)](https://github.com/Ultrabenosaurus "Ultrabenosaurus (4 commits)")[![aaemnnosttv](https://avatars.githubusercontent.com/u/1621608?v=4)](https://github.com/aaemnnosttv "aaemnnosttv (3 commits)")[![localheinz](https://avatars.githubusercontent.com/u/605483?v=4)](https://github.com/localheinz "localheinz (3 commits)")[![nyxsoftwaresystems](https://avatars.githubusercontent.com/u/71080572?v=4)](https://github.com/nyxsoftwaresystems "nyxsoftwaresystems (3 commits)")[![shuber](https://avatars.githubusercontent.com/u/2419?v=4)](https://github.com/shuber "shuber (3 commits)")[![vinkla](https://avatars.githubusercontent.com/u/499192?v=4)](https://github.com/vinkla "vinkla (3 commits)")[![carusogabriel](https://avatars.githubusercontent.com/u/16328050?v=4)](https://github.com/carusogabriel "carusogabriel (2 commits)")[![xjchengo](https://avatars.githubusercontent.com/u/4819996?v=4)](https://github.com/xjchengo "xjchengo (2 commits)")[![jrchamp](https://avatars.githubusercontent.com/u/625298?v=4)](https://github.com/jrchamp "jrchamp (2 commits)")[![louim](https://avatars.githubusercontent.com/u/923718?v=4)](https://github.com/louim "louim (2 commits)")[![rabbitfang](https://avatars.githubusercontent.com/u/2784296?v=4)](https://github.com/rabbitfang "rabbitfang (1 commits)")[![slaFFik](https://avatars.githubusercontent.com/u/282234?v=4)](https://github.com/slaFFik "slaFFik (1 commits)")[![stanlemon](https://avatars.githubusercontent.com/u/86314?v=4)](https://github.com/stanlemon "stanlemon (1 commits)")

---

Tags

environmentenvdotenv

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/publiux-phpdotenv/health.svg)

```
[![Health](https://phpackages.com/badges/publiux-phpdotenv/health.svg)](https://phpackages.com/packages/publiux-phpdotenv)
```

###  Alternatives

[vlucas/phpdotenv

Loads environment variables from `.env` to `getenv()`, `$\_ENV` and `$\_SERVER` automagically.

13.5k602.4M5.4k](/packages/vlucas-phpdotenv)[symfony/dotenv

Registers environment variables from a .env file

3.8k226.7M2.3k](/packages/symfony-dotenv)[diarmuidie/envpopulate

Tool to interactively populate a `.env` file based on an `.env.example` file whenever Composer installs or updates.

1892.0k](/packages/diarmuidie-envpopulate)[zepgram/magento-dotenv

Simple autoloader to integrate the Symfony Dotenv component into Magento2

1371.3k](/packages/zepgram-magento-dotenv)[nystudio107/dotenvy

Speed up your production sites by ditching .env for key/value variable pairs as Apache, Nginx, and shell equivalents.

326.9k](/packages/nystudio107-dotenvy)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)