README

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,

use Phoole\Config\Config;
use Phoole\Env\Environment;

// load server environment from '.env' file
(new Environment())->load(__DIR__ . '/.env');

// create config instance with the config file loader
$config = new Config(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.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 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 file
return [
    // 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

phoole / config

Maintainers

Details