config

A slim configuration loader library for PHP. It loads PHP, JSON, YAML config files, easy to use, yet powerful. It requires PHP 7.2+ and is compliant with PSR-1, PSR-4, PSR-12.

Installation

Install via the composer utility.

composer require "phoole/config=1.*"

or add the following lines to your composer.json

{
"require": {
"phoole/config": "1.*"
}
}

Features

• Simple interface, get($id), has($id), with($id, $value).

• 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
  

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

• Get environment values using $config->get('ENV.USER') or ${ENV.USER}

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

• Support .php, .json, .yml(need yaml extension installed) 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,

  usePhoole\Config\Config;
  usePhoole\Env\Environment;
  // load server environment from '.env' file
  (newEnvironment())->load(__DIR__ . '/.env');
  // create config instance with the config file loader$config = newConfig(getenv('CONFIG_DIR'), getenv('APP_ENV'));
  // object access of $config$db_config = $config->get('db');

• 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.phpreturn [
    'tmpdir' => '/usr/local/tmp',
    // ...
    ];

    Later, system related configs can be retrieved as

    $dir = $config->get('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 (assume config files are *.php),

    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

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

  In your cache.php file,

  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('%{', '}%');

• Access environment values

  Environment values can be accessed through special node 'ENV'. e.g.

  $tmpdir = $config->get('ENV.APP_TMPDIR');

  or in reference format,

  return [
  'tmpdir' => '${ENV.APP_TMPDIR}'
  ];

• DOT notation

  Hierarchy 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 filereturn [
  // array notation'auth' => [
  'host' => 'localhost',
  'port' => 3306
  ],
  // flat notation'auth.user' => 'dbuser'
  ];

• After initial loading, $config is immutable. If you want to add new conf values. You may use,

  $newconf = $config->with('redis', ['host' => 'localhost']);

  where $newconf is a new configuration object.

APIs

• ConfigInterface API

  • get(string $id): mixed

    The return value might be a string, array, or even object. Returns null if not found.

  • has(string $id): bool

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

  • with(string $id, mixed $value): Config

    Returns a new config object with $id set.

• ReferenceInterface API

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

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

Testing

$ composer test

Dependencies

• PHP >= 7.2.0

License

• Apache 2.0