This package is abandoned and no longer maintained. No replacement package was suggested.

A simple, easy to use, yet powerful configuration management library for PHP.

2.0.12 2016-07-18 02:20 UTC

This package is not auto-updated.

Last update: 2020-01-24 16:17:57 UTC


PLEASE USE phoole/config library instead

Build Status Code Quality Code Climate PHP 7 ready HHVM Latest Stable Version License

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.


Install via the composer utility.

composer require "phossa2/config=2.*"

or add the following lines to your composer.json

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


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

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

     |___ 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

  • 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.


  • 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
    # app directory
    # config directory
    # app env for current host

    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(
    // 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

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

    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
        // 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
      // chaining
      // get from the chain
      $db = $delegator2->get('db');


  • 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
    • 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.


$ composer test


Please see CONTRIBUTE for more information.


  • PHP >= 5.4.0

  • phossa2/shared >= 2.0.21


MIT License