Environments and secrets: EXP_ENV and settings/override #

This page is for developers who switch environments with APP_ENV, keep secrets in .env.local, Rails credentials or a vault, and expect dev, test and prod to behave differently. Exponential names the environment of a machine with one constant, EXP_ENV, and lets every settings file have a variant for it (Settings per environment (EXP_ENV)).

Contents #

1. Naming the environment
2. Settings variants
3. What the name changes
4. Secrets
5. Environment variables
6. Compared with other frameworks

Naming the environment #

Copy config.env.php.example to config.env.php in the root of the installation:

<?php
define( 'EXP_ENV', 'test' );

config.env.php is read before config.php by the web entry points and the command line scripts, and the shipped .gitignore keeps it out of version control. A name is lowercase letters, digits, - or _, starts with a letter and has at most 32 characters; an invalid name is treated as no environment.

Settings variants #

The environment name goes right after .ini:

A variant is read right after its standard file in every layer and overrides that layer only, so a siteaccess setting still wins over a base variant. Each environment has its own INI cache files. Typical variants: the mail transport (file outside production), debug output, hosts, the Solr address.

# settings/override/site.ini.test.append.php
<?php /*
[MailSettings]
Transport=file

[DebugSettings]
DebugOutput=enabled
*/ ?>

What the name changes #

Templates read the name with {exp_environment()}; PHP with eZINI::environment() (the name or false). The admin designs admin4 and admin4l can show the environment as a badge (site.ini [AdminEnvironment] Level=auto). Unlike Symfony's dev environment or Django's DEBUG, the name does not switch on a profiler or debug toolbar by itself: you switch those in the environment's variant file.

Secrets #

Never in your extension's repository, a .ini file the web server might show, templates, job payloads, logs, URLs or commit messages. Ship each key as an empty value with a comment in your extension's INI file, and fail with a clear message when it is empty (Environment settings and secrets).

$key = eZINI::instance( 'expdemo.ini' )->variable( 'ArchiveSettings', 'ApiKey' );
if ( $key === '' )
    throw new RuntimeException( 'expdemo.ini [ArchiveSettings] ApiKey is not set; put it in settings/override/expdemo.ini.append.php' );

Environment variables #

Settings are not read from environment variables the way %env(...)%, env() or os.environ read them. A few environment variables do exist for specific purposes, for example EXP_DEMO_MODE=1 for public demos (Environment variables). If your platform injects secrets as environment variables, read them in your own code with getenv() and document it, or have your deployment write them into settings/override/.

Compared with other frameworks #

Related pages #

• Configuration: INI files
• Settings per environment (EXP_ENV)
• Security standard
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.