neam/php-app-config

A PHP framework-agnostic approach to make the current [config](http://12factor.net/config) available to PHP applications and shell-scripts.

PHP App Config

A PHP framework-agnostic approach to make the current config available to PHP applications and shell-scripts., _(*1)

For use by the application wherever it may be fit, for instance in the application's / PHP framework's configuration files., _(*2)

Installation

• Install via composer:

composer require neam/php-app-config:dev-develop

• Copy the example/config folder into the root directory of your project.

cp -r vendor/neam/php-app-config/example/config config

• Make sure that all app entry scripts include the file called include.php right after including the composer autoloader (adjust the path as necessary in each entry script):

// Make app config available as PHP constants
require(dirname(__FILE__) . '/../vendor/neam/php-app-config/include.php');

• Replace config vars in your app with the corresponding PHP constants. Example of usage within Yii configuration:

Before:, _(*3)

'db' => array(
    'connectionString' => 'mysql:host=localhost;dbname=db',
    'emulatePrepare' => true,
    'username' => 'root',
    'password' => 'supersecret',
    'charset' => 'utf8',
    'enableParamLogging' => true, // Log SQL parameters
    //'schemaCachingDuration'=>3600*24,
),

After:, _(*4)

'db' => array(
    'connectionString' => 'mysql:host=' . DATABASE_HOST . (defined('DATABASE_PORT') && DATABASE_PORT != '' ? ';port=' . DATABASE_PORT : '') . ';dbname=' . DATABASE_NAME,
    'emulatePrepare' => true,
    'username' => DATABASE_USER,
    'password' => DATABASE_PASSWORD,
    'charset' => 'utf8',
    'enableParamLogging' => true, // Log SQL parameters
    //'schemaCachingDuration'=>3600*24,
),

How it works

Configuration directives are looked for in the following places: * $_ENV (which can be populated during a bootstrapping phase as in the local example config file) * php-fpm environment variables (set in php-fpm configuration files and available through getenv()) * apache sub-process environment variables (set in Apache 2.x vhost config and available through apache_getenv()) * php-cgi params (set in nginx location blocks using fastcgi_param and available through $_SERVER), _(*5)

The include.php file will load a file (defaulting to project-root/config/local/include.php) that defines what application-specific configuration directives to expect., _(*6)

To change the expected config include file, set the CONFIG_INCLUDE environment variable to the path to the include relative to the project root. For instance, in order to use project-root/config/remote/include.php, set the CONFIG_INCLUDE environment variable to config/remote/include.php., _(*7)

Within the config include file, you define which directives to expect using the Config::expect() method:, _(*8)

Config::expect("DATABASE_URL", $default = null, $required = true);

The include.php file will then call Config::defineConstants() which will define expected configuration directives as constants., _(*9)

Using the example config includes

The included example configuration includes sample config profiles used to deploy to Heroku-style services and/or running the code locally., _(*10)

Remote deployment (Docker Cloud / Platform as a Service)

• Deploy the app to Docker Cloud or a PaaS
• Set the CONFIG_INCLUDE config var to config/remote/include.php

Example - Heroku

$ heroku config:set CONFIG_INCLUDE=config/remote/include.php

• Set the expected config vars (DATABASE_URL, GA_TRACKING_ID etc) to their respective values

Your app should now run on Heroku using the expected config vars as PHP constants., _(*11)

Local

The example local config include will first expect the remote, then load the overrides.php file, followed by a non-versioned file called secrets.php. To use the local configuration:, _(*12)

• Create ang gitignore your secret local configuration file

cp .env.dist .env
echo ".env" >> .gitignore

• Add general defaults/overrides that all developers use locally in the overrides.php file
• Add secret defaults/overrides that should not be versioned to the secrets.php file

Your app should now run locally using the expected config vars as PHP constants., _(*13)

Useful commands

To show your current config, you can run the following in a shell:, _(*14)

php -d variables_order="EGPCS" vendor/neam/php-app-config/export.php

To use the config in a shell-script:, _(*15)

source vendor/neam/php-app-config/shell-export.sh
# now the config is available to the shell-script

To export the current configuration to a file which can be sourced by a shell script:, _(*16)

php -d variables_order="EGPCS" vendor/neam/php-app-config/export.php > .exported.php-app-config.inc.sh