library config

simplecomplex/config

Simple Cache like configuration interfaces; ini-files as source, cache as store.

Config

• Installation
• Requirements

Simple and sectioned configuration interfaces

ConfigInterface
is basically PSR-16 Simple Cache without time-to-live.
There's a key and a value., _(*1)

That principle isn't optimal for general use, unless you like real long and complex key names., _(*2)

SectionedConfigInterface
Splits the item key into 'section' plus 'key', facilitating a more organized structure., _(*3)

The immediate benefit is that you can namespace all items that belong to a particular library., _(*4)

The section-key pattern can be implemented and utilized in two manners:, _(*5)

• concatenation: the configuration setters and getters simply concatenate section and key
• listing: the section is a list of keys, you can access the whole section as well as a particular key

SectionedConfigInterface also allows for short-term keeping items in memory, via methods remember() and forget()., _(*6)

Implementations

Environment variable based

EnvConfig
is a simple abstraction of server environment variables., _(*7)

EnvSectionedConfig
a sectioned implementation, using concatenation., _(*8)

Ini-files as source, cache as store

The ini-file based classes parse ini-files, and save to cache stores., _(*9)

They read recursively from their ini-file paths. That allows one to clone and use ini-files from multiple version control repositories., _(*10)

Ini-files are so old-school..., _(*11)

Aye, but the ini format is less error-prone than JSON, YAML, what-not.
The syntax is so simple it's hard to make mistakes. And operations people are used to ini-files., _(*12)

Cache layer

is SimpleComplex Cache PersistentFileCache.
Cache store names are prefixed with 'config.'
Beware of conflict; do not prefix other cache stores that way., _(*13)

Types of ini-based configuration

IniConfig
is not sectioned. Simple but probably not that useful.
$value = $config->get('key'), _(*14)

IniSectionedConfig
is a powerful general usage implementation.
$value = $config->get('section', 'key'), _(*15)

Reads ini-files from a base path and an override path.
Keep development/production invariant variables (ini-files) in the base path.
Let operations keep production variables in the override path., _(*16)

Using the list-principle - and fully supporting remember() and forget() - IniSectionedConfig is optimal for accessing many/all keys of a section within a limited procedure., _(*17)

IniSectionedFlatConfig
a sectioned implementation, using concatenation., _(*18)

Optimal for types of configuration one expects to access keys of diverse sections in an unpredictable manner, but still want the organisational benefit of sections; many but exact cache reads.
SimpleComplex Locale uses this config class for localized texts., _(*19)

Abstraction

The Config class is an abstraction of sectioned configuration., _(*20)

In this package it extends IniSectionedConfig.
In an extending package it could be some other sectioned config implementation., _(*21)

CLI interface

CliConfig delivers CLI commands for setting, getting and deleting config items.
And commands for refreshing and exporting full configuration stores., _(*22)

It exposes IniSectionedConfig instances, via the Config class.
The other config classes are not accessible via CLI., _(*23)

Global config

Config defaults to deliver an instance named 'global'., _(*24)

A typical system could probably benefit from a single config instance for the bulk of items.
Since the whole thing runtime is cache based, there's no performance reason for using multiple instances., _(*25)

Dependency injection container ID: config

Recommendation: access (and thus instantiate) the global config via DI container ID 'config'.
See SimpleComplex Utils Dependency., _(*26)

Example

// Bootstrap.
Dependency::genericSetMultiple([
    'cache-broker' => function () {
        return new \SimpleComplex\Cache\CacheBroker();
    },
    'config' => function() {
        return new \SimpleComplex\Config\Config('global');
    },
]);
// ...
// Use.
/** @var \Psr\Container\ContainerInterface $container */
$container = Dependency::container();
/**
 * Create or re-initialize the 'global' config store;
 * based on ini-files placed in base and override paths,
 * cached by a PSR-16 Simple Cache cache store.
 *
 * @var \SimpleComplex\Config\IniSectionedConfig $config
 */
$config = $container->get('config');
/** @var mixed $whatever */
$whatever = $config->get('some-section', 'some-key', 'the default value');

CLI commands

# List all config commands and their help.
php cli.php config -h
# One command's help.
php cli.php config-xxx -h

# List existing config stores.
php cli.php config-list-stores

# Display/get value of a config item.
php cli.php config-get store section key

# Set a config item.
php cli.php config-set store section key value

# Delete a config item.
php cli.php config-delete store section key

# Refresh a config store from .ini file sources.
# The fresh store gets applied atomically, when fully built.
php cli.php config-refresh store

# Export a config store as JSON to a file.
php cli.php config-export store target-path-and-file

Installation

Create a 'conf' directory alongside the document root dir., _(*27)

Like:
/var/www/my-host/http
/var/www/my-host/conf, _(*28)

Create 'base' and 'override' paths within the 'conf', like:
conf/ini/base
conf/ini/override, _(*29)

For the 'global' config store, place or symlink or git clone your system's
.ini configuration files under the 'base' and 'override' paths
using file extension global.ini (= [store name].ini)., _(*30)

Like:
conf/ini/base/some-ding.global.ini
conf/ini/override/some-ding.prod.global.ini, _(*31)

If that directory structure isn't suitable, do either: - supply Config constructor with a 'paths' argument - extend Config and override it's class constant PATH_DEFAULTS, _(*32)

Requirements

• PHP >=7.0
• SimpleComplex Cache
• SimpleComplex Utils

Suggestions

• SimpleComplex Inspect