README

See new lib at phoole/config

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