Colorado Timberline APIA Practical Guide to Successful Integration

PHP Configuration System

The Configuration System

The configuration system is very simple; it allows you to use PHP arrays and optionally to specify environmental associations with sections of a configuration file.

Naming Conventions

Filename

Suppose you want a configuration file to store user information, you would simply create a file in the config directory named users.php. Inside of that file, you would start out by defining an array named $a_ct_user

$a_ct_user = array();

From there you can start adding values to the array and they will be available when you load the configuration via the CtApiConfig class.
This array is returned to you by CtApiConfig::load(); so let’s assume the populated array looks something like this:

$a_ct_user = array(
'nathan' => array(
'password' => 'reallyInsecure',
'email' => 'youWishItWasHere@aol.com'
),
'sally' => array(
'password' => 'g0F1sh',
'email' => 'sillyGirl@care.com'
);

Loading a configuration file

Non-Environmentally aware configuration files

Configuration files are loaded with the CtApiConfig class as such

$aUserConfig = CtApiConfig::load('user');

// from the populated example above you could access nathan's email via
$sNatesEmail = $aUserConfig['nathan']['email'];
Environmentally aware configuration files

There are 3 environment levels supported by CtApiConfig; dev, staging and prod. If you want your configuration file to have environmental information associated with it, the stub for your array would be

$a_ct_user = array(
'dev' => array(),
'staging' => array(),
'prod' => array()
);

Now when you load this configuration file, the subsection corresponding to the current environment will be selected.

Setting Current Environment

CtApiConfig has a static setter method, setEnv(), which takes one of 3 constants, DEV, STAGING, PROD as an argument.

CtApiConfig::setEnv(CtApiConfig::STAGING);

Setting Environmental Configuration at Runtime

Suppose you want to bypass the stock CT configuration system altogether. You can pass CtConfig an array (just like the arrays in envs.php for each environment to the CtApiConfig::set() method.

// set environmental config at runtime
CtApiConfig::set('envs', array(
'sHttpProtocol' => 'http',
'sDomain' => 'api.staging.co-timber.com',
'sBaseUrl' => 'v15',
'sAffiliateId' => 'CT_55555',
'sPassword' => '',
'sLogLevel' => ''
));
Changing specific values at runtime

To accomplish this you must load the configuration, then set the configuration for the same key having modified the contents locally.

$aConfig = CtApiConfig::load('envs');
$aConfig['sLogLevel'] = 'none';
CtApiConfig::set('envs', $aConfig);

Configuration Caching

CtApiConfig loads files from disk initially, but upon subsequent invocations of CtApiConfig::load(), values will be served from CtApiConfig instance variables. To force CtApiConfig to purge its internal cache call CtApiConfig::load() and pass true as the optional second parameter. This situation will likely be rare, however a more common situation is where you might want to change configuration values at runtime by providing values from a source other than the standard php files, as discussed above.

Subscribing to Configuration Changes

Coming Soon ..