README

PLEASE USE phoole/config library instead

phossa2/config is a simple, easy to use, yet powerful configuration management library for PHP. The design idea was inspired by another github project mrjgreen/config but some cool features added.

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

Installation

Install via the composer utility.

composer require "phossa2/config=2.*"

or add the following lines to your composer.json

{
    "require": {
       "phossa2/config": "2.*"
    }
}

Features

• Simple interface, get($id, $default = null) and has($id).

• One central place for all config files for ease of management.

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

• Use an environment value, such as production or production/host1 for switching between different configurations.

• Use of references in configuration value is fully supported, such as ${system.tmpdir}.

• On demand configuration loading (lazy loading).

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

• Array access for ease of use. e.g. $config['db.user'] = 'www';.

• Reference lookup delegation and config chaining.

• Support .php, .json, .ini, .xml and .serialized type of config files.

Usage

• Use environment value

  Usually application running environment is different on different servers. A good practice is setting environment in a .env file somewhere on the host, and put all configuration files in one central config/ directory.

  A sample .env file,

  # installation base
  BASE_DIR=/www
  
  # app directory
  APP_DIR=${BASE_DIR}/app
  
  # config directory
  CONFIG_DIR=${APP_DIR}/config
  
  # app env for current host
  APP_ENV=production/host1

  In a sample bootstrap.php file,

  use Phossa2\Config\Config;
  use Phossa2\Env\Environment;
  use Phossa2\Config\Loader\ConfigFileLoader;
  
  // load environment from '.env' file
  (new Environment())->load(__DIR__ . '/.env');
  
  // create config instance with the config file loader
  $config = new Config(
      new ConfigFileLoader(
          getenv('CONFIG_DIR'),
          getenv('APP_ENV')
      )
  );
  
  // object access of $config
  $db_config = $config->get('db');
  
  // array access of $config
  $config['db.user'] = 'www';

• Central config directory and configuration grouping

  • Configuration grouping

    Configurations are gathered into one directory and are grouped into files and subdirectories for ease of management.

    For example, the config/system.php holds system.* configurations

    // system.php
    return [
        'tmpdir' => '/usr/local/tmp',
        // ...
    ];

    Later, system related configs can be retrieved as

    // object acess of config
    $dir = $config->get('system.tmpdir');
    
    // array access of $config
    $dir = $config['system.tmpdir'];

    Or being used in other configs as references.

  • Configuration files loading order

    If the environment is set to production/host1, the config files loading order are,

    1. config/config/*.php

    2. config/production/*.php

    3. config/production/host1/*.php

    Configuration values are overwritten and replaced those from later loaded files.

• Use of references

  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', // use reference here
              'hash_level' => 2
          ]
      ],
      ...
  ];

  You may reset the reference start and ending matching pattern as follows,

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

• ArrayAccess and DOT notation

  Config class implements ArrayAccess interface. So config values can be accessed just like an array.

  // test
  if (!isset($config['db.auth.user'])) {
      // set
      $config['db.auth.user'] = 'www';
  }

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

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

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

  // db config file
  return [
      // array notation
      'auth' => [
          'host' => 'localhost',
          'port' => 3306
      ],
  
      // flat notation
      'auth.user' => 'dbuser'
  ];

• Reference lookup delegation and config chaining

  • Config delegation

    Reference lookup delegation is similar to the delegation idea of Interop Container Delegate Lookup

    • Calls to the get() method should only return an entry if the entry is part of the config registry. If the entry is not part of the registry, a NULL will be returned as described in ConfigInterface.

    • Calls to the has() method should only return true if the entry is part of the config registry. If the entry is not part of the registry, false should be returned.

    • If the fetched entry has dependencies (references), instead of performing the reference lookup in this config registry, the lookup is performed on the delegator.

    • Important By default, the lookup SHOULD be performed on the delegator only, not on the config registry itself.

      $config1 = new Config();
      $config2 = new Config();
      $delegator = new Delegator();
      
      // add some values
      $config1['db.user'] = '${system.user}';
      $config2['system.user'] = 'root';
      
      // reference unresolved in $config1
      var_dump($config1['db.user'] === '${system.user}'); // true
      
      // add both configs to the delegator
      $delegator->addConfig($config1);
      $delegator->addConfig($config2);
      
      // reference resolved thru the delegator
      var_dump($config1['db.user'] === 'root'); // true

    Delegator class implements the ConfigInterface and ArrayAccess interfaces, thus can be used just like a normal config.

    $dbUser = $delegator['db.user'];

  • Config chaining

    Config chaining can be achieved via multiple-level delegations. For example,

    // configs
    $config1 = new Config();
    $config2 = new Config();
    
    // delegators
    $delegator1 = new Delegator();
    $delegator2 = new Delegator();
    
    // register $config1 with $delegator1
    $delegator1->addConfig($config1);
    
    // chaining
    $delegator2->addConfig($delegator1);
    $delegator2->addConfig($config2);
    
    // get from the chain
    $db = $delegator2->get('db');

APIs

• ConfigInterface API

  • get(string $id, $default = null): mixed

    $default is used if no config value is found.

    The return value might be a string, array or even object.

  • has(string $id): bool

    Test if $id exists or not. Returns a boolean value.

• WritableInterface API

  • set(string $id, mixed $value): bool

    Set the configuration manually in this session. The value will NOT be reflected in any config files unless you modify config file manually.

    $value may be a string, array or object.

    This feature can be disabled by

    // disable writing to the $config
    $config->setWritable(false);

  • setWritable(bool $writable): bool

    Enable or disable the set() functionality. Returns true on success.

  • isWritable(): bool

    Test to see if current config writable or not.

• ReferenceInterface API

  • setReferencePattern(string $start, string $end): $this

    Reset the reference start chars and ending chars. The default are '${' and '}'

  • hasReference(string $string): bool

    Test to see if there are references in the $string

  • deReference(string $string): mixed

    Dereference all the references in the $string. The result might be string, array or even object.

  • deReferenceArray(mixed &$data): $this

    Recursively dereference everything in the $data. $data might be string or array. Other data type will be ignored and untouched.

• DelegatorInterface API

  • addConfig(ConfigInterface $config): $this

    Added one Phossa2\Config\Interfaces\ConfigInterface instance to the delegator.

• Others

  • setErrorType(int $type): $this

    Set either Config::ERROR_IGNORE, Config::ERROR_WARNING or Config::ERROR_EXCEPTION for the config.

Change log

Please see CHANGELOG from more information.

Testing

$ composer test

Contributing

Please see CONTRIBUTE for more information.

Dependencies

• PHP >= 5.4.0

• phossa2/shared >= 2.0.21

License

MIT License