Environment settings and secrets #

This page is for application creators who handle settings that differ per machine and secrets such as API keys and passwords. Both must stay out of the code repository.

Contents #

1. Settings per environment
2. Where secrets live
3. Reading secrets in code
4. Checklist

Settings per environment #

From Settings per environment (EXP_ENV):

1. Copy config.env.php.example to config.env.php and set define( 'EXP_ENV', 'test' );. It is read before config.php by web and command line, and .gitignore keeps it out of version control.
2. Put the environment's settings in a variant file: the environment name right after .ini (settings/override/site.ini.test.append.php, extension/<ext>/settings/site.ini.test.append.php).
3. Clear the INI cache once; each environment has its own cache files.

Typical variants: the mail transport (file outside production), debug output, hosts, the Solr address.

Where secrets live #

Never in: your extension's repository, a .ini file the web server might show (use .ini.append.php, which wraps the content in a PHP comment), templates, job payloads, logs, URLs or commit messages.

Reading secrets in code #

$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' );

Ship the key in your extension's expdemo.ini as an empty value with a comment, so installations see where to set it.

Checklist #

• To do: config.env.php stays out of Git (the shipped .gitignore lists it); in a project repository of your own, keep settings/override/ out of version control too.
• To do: Secrets have mode 0640 and belong to the web server's group.
• To do: Each environment has its own keys; production keys are never on development machines.
• To do: A leaked key can be revoked without a code change.

Demo mode. The environment variable EXP_DEMO_MODE=1 belongs to public demos only: an app that talks to a demo gets HTTP 403 when it tries to change or reset an administrator's password. Environment variables, Demo mode.

Related pages #

• Settings and INI files in your application
• Security for applications
• Security standard
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.