README

Convert dotenv files to PHP.

Why use it?

Storing configuration in the environment is a tenant of a Twelve Factor App and has many advantages. For example, it allows you to keep your passwords separate from your code.

However, it's not always practical to set environment variables on development machines or continuous integration servers where multiple projects are run. In these scenarios, we can load variables from a .env as needed.

Instead of parsing a .env at runtime with complex PHP dependencies, we can use dotenv-to-php to compile our .env to native PHP.

It's fast. The conversion is instantaneous. At runtime, simply load your env vars using the generated PHP. You can even use it in production.
It's simple. No runtime dependency. The transpiler is only 42 lines with comments, contains no regex, and no custom parsers. Contrast this with phpdotenv.

1. Install

You can just download the one file -OR- add it as a dev dependency via composer:

composer require --dev jchook/dotenv-to-php

2. Create .env

If you don't already have one, create a .env file in the root directory of your project. Add all environment-specific variables (anything likely to change between servers or deployments) on individual lines like so:

# Application
APP_HOST="myapp.com"
APP_URI="https://$APP_HOST/"
APP_NAME="My Application"

# Database
DB_HOST=localhost
DB_USER=myapp
DB_PASS=mypass

Notice that you should quote values with spaces, etc. and that it's possible to reference previously defined variables as in normal shell environments. Comments beginning with # are ignored.

Do not commit your .env file to source control. Instead, store it somewhere secure, or use a tool like vault.

3. Build .env.php

Simply call bin/dotenv-to-php via command-line to convert your .env file to PHP.

/path/to/dotenv-to-php

Usage is roughly dotenv-to-php [infile] [outfile]. If no infile or outfile is specified, they default to .env and $infile.php respectively. You can also specify - (hyphen) for stdin or stdout... respectively.

4. Integrate

In your PHP application, simply include the compiled .env.php file. Your loaded environment variables will be available via $_SERVER, $_ENV, and getenv().

<?php

// somewhere in index.php
include_once __DIR__ . '/.env.php';

// Anywhere you need it...
echo $_SERVER['DB_USER']; // myapp

?>

Ideally you can integrate the .env.php file generation into your existing build process (either for CI or local development). All examples below assume that your dotenv file is saved in the current working directory as .env.

Composer

If you installed via composer, you can integrate it as a script in your composer.json file:

{
	"scripts": {
		"build-env": "dotenv-to-php .env .env.php"
	}
}

Then invoke via:

composer build-env

Node JS

Many folks are using node js to compile their static assets such as javascript. If you want to plug-in to this existing build process, you can use the built-in child_process module.

const childProcess = require('child_process');
childProcess.spawn('/path/to/dotenv-to-php', ['.env', '.env.php']);

Webpack 4+

You can easily incorporate the above into an ad-hoc webpack plugin. In your webpack.config.js file:

const childProcess = require('child_process');
module.exports = {
	
	// ... other config here ...
	
	plugins: [
		
		// ... other plugins here ...
		
		// Build PHP env
		{apply: (compiler) => {
			compiler.hooks.afterEnvironment.tap('DotEnvToPhp', (compilation) => {
				childProcess.spawn('/path/to/dotenv-to-php', ['.env', '.env.php']);
			});
		}}
	]
};

License

MIT.

jchook / dotenv-to-php

Maintainers

Details