PHPackages                             maatwebsite/yamlenv - 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. [Parsing & Serialization](/categories/parsing)
4. /
5. maatwebsite/yamlenv

ActiveLibrary[Parsing & Serialization](/categories/parsing)

maatwebsite/yamlenv
===================

Reads `env.yml` and makes a validated list of variables available as environment variables

1.0.0(7y ago)1116.7k↓33.3%3LGPLPHPPHP >=5.5.9

Since Dec 9Pushed 7y ago2 watchersCompare

[ Source](https://github.com/Maatwebsite/yamlenv)[ Packagist](https://packagist.org/packages/maatwebsite/yamlenv)[ RSS](/packages/maatwebsite-yamlenv/feed)WikiDiscussions master Synced 1mo ago

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

Maatwebsite\\Yamlenv
====================

[](#maatwebsiteyamlenv)

Reads env.yml and makes a validated list of variables available as environment variables.

This is package is based on [vlucas/phpdotenv](https://github.com/vlucas/phpdotenv).

[![Build Status](https://camo.githubusercontent.com/ef49823305c08015fe17446af99d3c17e4a5a36aae73b287f71a0feabcf4c819/68747470733a2f2f7472617669732d63692e6f72672f4d616174776562736974652f79616d6c656e762e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/Maatwebsite/yamlenv.svg?branch=master)

Why choose Yaml over .env?
--------------------------

[](#why-choose-yaml-over-env)

The benefits of using a env.yml file or similar has been proven a long time ago. The popularity of [vlucas/phpdotenv](https://github.com/vlucas/phpdotenv) and similar packages is a testament of this. There is no reason why you shouldn't use a package like that in your projects, especially if the amount of variables you need to manage is relatively small.

In case of larger, enterprise scale, applications, the amount of environment settings might very quickly become unmanageable. If it's a multi tenant system even more so. And if you're supporting different versions of the application with its own list of required environment settings, it soon becomes a necessity to automate this process.

These are largely the reasons we decided to move towards Yaml. It provides a few simple advantages over env.yml files:

- It allows nesting, to allow grouping of certain settings ( like database connection credentials ).
- It is easily readable by human as well as multiple automated deployment tools ( Ansible e.g. ).
- There are at least as many ( probably more ) trustworthy packages that work with Yaml ( Symfony being the most important one )

In our initial use case it was the combination of nesting and Ansible compatibility that made us decide to build this package.

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

[](#installation-with-composer)

```
composer require maatwebsite/yamlenv ~1.0
```

Usage
-----

[](#usage)

The documentation below is, for a large part, the same as Vlucas/Dotenv. The filenames are changed of course and classnames. We tried to keep the package as close in usage to Dotenv as possible, for ease of use. So give credit to Vlucas for providing such a great base to work from!

Of course there are a few things unique to Yamlenv, and that has been added as well.

The `env.yml` file is generally kept out of version control since it can contain sensitive API keys and passwords. A separate `env.yml.dist` file can be 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.yml.dist` file to a local `env.yml` 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.yml`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.yml` file in the root of your project. **Make sure the `env.yml` file is added to your `.gitignore` so it is not checked-in the code**

```
S3_BUCKET: "yamlenv"
SECRET_KEY: "secret_key"
```

Now create a file named `env.yml.dist` 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.yml` in your application with:

```
$yamlenv = new Yamlenv\Yamlenv(__DIR__);
$yamlenv->load();
```

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

```
$yamlenv = new Yamlenv\Yamlenv(__DIR__, 'myconfig');
$yamlenv->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');
```

### Uppercase keys

[](#uppercase-keys)

With Yamlenv you can pass boolean true as the third contructor parameter. This will make sure all your keys will be cast to uppercase

```
s3_bucket: "will_be_uppercase"
```

```
$yamlenv = new Yamlenv\Yamlenv(__DIR__, 'emv.yml', true);
$yamlenv->load();
```

```
$s3_bucket = getenv('S3_BUCKET'); // return will_be_uppercase
$s3_bucket = getenv('s3_bucket'); // returns null
```

### Nesting Variables

[](#nesting-variables)

Like with Dotenv it's possible to nest an environment variable within another. However, because we are using the Yaml format, nesting us supported natively.

```
DB:
  USER: username
  PASS: password
  HOST: localhost
```

These variables will be flattened into a single level before being added to the environment variables. The different keys will be concatenated into a single key, separated with underscores. So the above example wil give the same results as below:

```
DB_USER: username
DB_PASS: password
DB_HOST: localhost
```

This also works with multiple levels:

```
FOO:
  BAR:
    LOREM:
        IPSUM: multilevelfun
```

```
FOO_BAR_LOREM_IPSUM: multilevelfun
```

### Immutability

[](#immutability)

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

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

```
$yamlenv = new Yamlenv\Yamlenv(__DIR__);
$yamlenv->overload();
```

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

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

Using Yamlenv, you can require specific ENV vars to be defined, and throw an Exception if they are not. 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:

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

Or an array of strings:

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

If any ENV vars are missing, Yamlenv 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:

```
$yamlenv->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 the the variable is of an integer value. You may do the following:

```
$yamlenv->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

```

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

```
$yamlenv->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.yml` file using the `#` character. E.g. This follows the normal Yaml syntax rules

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

When nesting variables, it is important to always use key->value based children. While the below is valid Yaml, it does not result in usable variables.

```
FOO:
  - one
  - two
```

Correct would be:

```
FOO:
  BAR: one
  BAZ: two
```

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

[](#usage-notes)

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

Yamlenv 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.yml` 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.

###  Health Score

36

—

LowBetter than 82% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity33

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity64

Established project with proven stability

 Bus Factor1

Top contributor holds 50% of commits — single point of failure

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 ~92 days

Recently: every ~147 days

Total

8

Last Release

2789d ago

Major Versions

0.2.0 → 1.0.02018-09-19

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/20562729?v=4)[spartner](/maintainers/spartner)[@spartner](https://github.com/spartner)

---

Top Contributors

[![FrankPeters](https://avatars.githubusercontent.com/u/3206714?v=4)](https://github.com/FrankPeters "FrankPeters (1 commits)")[![jochemfuchs](https://avatars.githubusercontent.com/u/4397250?v=4)](https://github.com/jochemfuchs "jochemfuchs (1 commits)")

---

Tags

yamlenvironmentenv

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/maatwebsite-yamlenv/health.svg)

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

###  Alternatives

[spatie/yaml-front-matter

A to the point yaml front matter parser

3411.8M67](/packages/spatie-yaml-front-matter)[pragmarx/yaml

Load your Laravel config files using yaml

1152.8M29](/packages/pragmarx-yaml)[sspooky13/yaml-standards

Standards for yaml files

11518.3k3](/packages/sspooky13-yaml-standards)[thunderer/serializard

Flexible serializer

2767.3k1](/packages/thunderer-serializard)[mhujer/yaml-sort-checker

YAML sort checker checks if your YML files are properly sorted to prevent merge conflicts

2361.6k](/packages/mhujer-yaml-sort-checker)[pagerange/metaparsedown

Adds ability to have meta data in markdown files parsed by eursev/parsedown or eruseve/parsedown-extra

2637.2k2](/packages/pagerange-metaparsedown)

PHPackages © 2026

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