marcin-orlowski / process-dotenv
Little tool to help build DotEnv (.env) files from templates
Installs: 9 596
Dependents: 0
Suggesters: 0
Security: 0
Stars: 7
Watchers: 3
Forks: 0
Open Issues: 0
Requires
- php: >=5.1.2
Requires (Dev)
README
.env
(AKA DotEnv) files are often used to store project configuration (i.e. for Laravel
based PHP projects). As they usually contain sensitive information as API keys or DB credentials, .env
files should
never be versioned. This also means that if you need to use/run your project in automated pipeline, i.e. with
Continuous Integration (CI) tools like TeamCity or Travis-CI, you need to create proper .env
file before using the
code. As .env
file usually contains all the project configuration, there will be much more fields than said i.e.
API key. Additionally, as project develops, new entries can be added and existing entries altered or tweaked.
It's a developers' common practice to create .env.dist
file, fill as much as possible (ommiting sensitive information)
and put it into VCS.
So if we treat said .env.dist
as template file, then with the right tool in hand we'd be able to
create corresponding .env
file easily. And this is where process-dotenv
steps in. The goal of this
small tool is pretty simple - generate .env
file based on the template .env.dist
, filling/replacing
specified template keys with provided values (taken either from env vars, for supplied as invocation
arguments).
NOTE: Whenever I say .env
or .env.dist
I only mean file format, not file name. Your
file names can be anything you like as long its content follows dot-env file format!
NOTE: To avoid accidental overwrites process-dotenv
outputs processed content to standard output. To to
create physical .env
file need to redirect stdout to a file. Please see examples for more details.
Env variable subsitution
NOTE: all samples mimics shell session, so ommit $
line for use in scripts.:
Let's assume our .env.dist
template file looks like this:
KEY=val
BAR=zen
FOO=
Now, knowing your app requires KEY
to be valid API key for tests to pass we can have it replaced with
process-dotenv
:
$ KEY=barbar
$ vendor/bin/process-dotenv .env.dist > .env
which shall produce .env
file with the following content:
KEY=barbar
BAR=zen
FOO=
As you noticed, original value of KEY
is replaced with what we provided via enviromental variable,
while BAR
and FOO
, for which we did not provide replacements, were copied unaltered.
Argument subsitution
Aside of env variables you can also pass key=val
pairs as process-dotenv
invocation arguments to
achieve the same results:
$ vendor/bin/process-dotenv .env.dist KEY=barbar > .env
IMPORTANT: first argument always refers to source dot-env file, followed by (optional) KEY=VAL
pairs.
You can pass as many pairs as you need and file names can be whatever you like.
Combined substitution
Both substitution methods can be used together. When key is provided as argument and also exists as enviromental variable, then command line provided value takes precedence:
$ KEY=barbar
$ vendor/bin/process-dotenv .env.dist KEY=value > .env
would produce:
KEY=value
BAR=zen
FOO=
Requirements
- PHP 5+ (CLI)
Installation
Use composer to install this package as your dependency:
$ composer require marcin-orlowski/process-dotenv
It will install process-dotenv
script in usual vendor/bin
folder.
Troubleshoting
Please remember that certain, especially generic key names can already be set up by
your shell or system. For example USER
is usually present and holds id of currently logged
in user,HOME
points to home directory of said user are variables already
set, etc. You can list all of them with printenv
or export
to ensure none of your keys
matches, but it is good habit to be more creative and avoid such short and potentially conflicting
names.
Simple test to see if your .env.dist
uses such "risky" keys is to run process-dotenv
without any own substitution provided and diff result file with dist file:
$ vendor/bin/process-dotenv .env.dist | diff .env.dist
If you got conflicts then you can either change your keys or at least substitute that key
via command line arguments to ensure system's values won't pollute your resulting .env
:
$ vendor/bin/process-dotenv .env.dist USER= HOME= > .env
but this is pretty error prone and is not recommended.
NOTE: in case you use conflicting key (i.e. USER
) but you want it to keep the
value set in .env.dist
you currently must pass it as command like pair. process-dotenv
cannot tell which env variables is "good" and which is "bad", so as soon as it find one exists,
it will simply use its value. That's why you must override it via command line pair.
License
- Copyright © 2016-2021 by Marcin Orlowski
- Process Dotenv tool is open-sourced software licensed under the MIT license