README

Introduction

phossa-config is a configuration management library for PHP. The design idea is inspired by another github project mrjgreen/config but with lots of cool features.

It requires PHP 5.4 and supports PHP 7.0+, HHVM. It is compliant with PSR-1, PSR-2, PSR-4.

Features

One central place for all config files

config/
 |
 |____ production/
 |        |
 |        |____ host1/
 |        |       |___ redis.php
 |        |       |___ db.php
 |        |
 |        |____ db.php
 |
 |____ system.php
 |____ db.php
 |____ redis.php

Use an environment value, e.g. production or production/host1 for switching between development, staging or production.
Support .php, .json, .ini and .xml type of configuration files.
Reference is possible, such as ${system.tmpdir} in configuration file and environment file.
On demand configuration loading (lazy loading).
Able to load all configuration files in one shot with $config->get(null)
Configuration cache.

Hierachy configuration structure with dot notation like db.auth.host.

// returns an array
$db_config = $config->get('db');

// returns a string
$db_host = $config->get('db.auth.host');

Both flat notation and array notation fully supported and co-exist at the same time.

// db config file
return [
    // array notation
    'auth' => [
        'host' => 'localhost',
        'port' => 3306
    ],

    // flat notation
    'auth.user' => 'dbuser'
];

Un*x shell style environment file '.env' is supported with dereferencing feature and magic environment values like ${__DIR__} and ${__FILE__}

Installation

Install via the composer utility.

composer require "phossa/phossa-config=1.*"

or add the following lines to your composer.json

{
    "require": {
      "phossa/phossa-config": "1.*"
    }
}

Usage

Running Environment

Usually running environment is different for different servers. A good practice is setting environment in a .env file in the installation root and put all configuration files in the config/ directory.

Sample .env file,

# debugging true|false, change to 'false' ON production server
APP_DEBUG=true

# App environment, change to 'prod' ON production server
APP_ENV=dev

# app root directory, default to current dir
APP_ROOT=${__DIR__}

# central configuration directory
CONFIG_DIR=${APP_ROOT}/config

In the bootstrap.php file,

// load environment
(new Phossa\Config\Env\Environment())->load(__DIR__.'/.env');

// create config object
$config = new Phossa\Config\Config(
    getenv('CONFIG_DIR'), // loaded from .env file
    getenv('APP_ENV')     // loaded from .env file
);

// load all configs in one shot
$conf_data = $config->get(null);

Grouping

Configurations are grouped into groups, namely files. For example, the system.php holds all system.* configurations
```
// system.php
return [
    'tmpdir' => '/usr/local/tmp',
    ...
];
```
Later, system related configs can be retrieved as
```
$dir = $config->get('system.tmpdir');
```
Or being used in other configs as reference.

Caching

A cache pool can be passed to the config constructor to have it read all configs from the cache or save all configs to cache.

// create config object
$config = new Phossa\Config\Config(
    dirname(__DIR__) . '/config',     // the config dir
    'staging/server2',                // config env
    'php',                            // file type
    new Phossa\Config\Cache\Cache(__DIR__ . '/cache') // cache location
);

// if cache exists, this will read all configs from the cache
$conf_data = $config->get(null);

// ...

// write to cache
$config->save();

Pros of using caching
- Speed up. Read from one file instead of lots of configuration files.
- References like ${system.tmpdir} are done already.
Cons of using caching
- Config data might be stale. need to using $config->save() to overwrite or $cache->clear() to clear the cache.
- Need write permission to a cache directory.
- Might expose your configuration if you are not careful with cache data.

Reference

References make your configuration easy to manage.

For example, in the system.php

// group: system
return [
    'tmpdir' => '/var/local/tmp',
    ...
];

In your cache.php file,

// group: cache
return [
    // a local filesystem cache driver
    'local' => [
        'driver' => 'filesystem',
        'params' => [
            'root_dir'   => '${system.tmpdir}/cache',
            'hash_level' => 2
        ]
    ],
    ...
];

You may reset the reference start and ending chars,

// now reference is something like '%system.tmpdir%'
$config = (new Config())->setReferencePattern('%', '%');

Or even disable the reference feature,

// now reference is not recognised
$config = (new Config())->setReferencePattern('', '');

Overwriting

If the environment is set to production/host1, the precedence order is,
- config/production/host1/db.php over
- config/production/db.php over
- config/config/db.php
Config API
- get($key, $default = null)
  
  $key is the a flat notation like db.auth.host or NULL to get all of the configurations. $default is used if no configs found.
  
  Return value might be a string or array base on the $key.
- set($key, $value)
  
  Set the configuration manually in this session. The value will NOT be reflected in any config files unless you modify config file manually.
  
  $value can be a string or array.
- has($key)
  
  Test if $key exists or not. Returns a boolean value.
- save()
  
  Save current full configurations into a cache.

Changes

1.0.6 added setReferencePattern(), hasReference() and deReference()

Dependencies

PHP >= 5.4.0
phossa/phossa-shared ~1.0.10

License

MIT License

phossa / phossa-config

Maintainers

Details