northwoods / config

Simple configuration management for PHP

Northwoods Config

PHP configuration loading library. It is made to enable your application to have different configurations depending on the environment it is running in. For example, your application can have different configurations for testing, development, staging, and production.

It is not recommended to include your staging or production configuration in version control! To support system specific configuration, you may install josegonzalez/dotenv.

Installation

The best way to install and use this package is through composer:

composer require northwoods/config

Usage

There are several different ways to use this package. The most simple is to use the static factory:

use Northwoods\Config\ConfigFactory;

$config = ConfigFactory::make([
    'directory' => __DIR__ . '/config',
]);

Configuration can now be read using a "dot path":

$token = $config->get('app.timezone');

This will load config/app.php and return the timezone key, if it exists.

Optionally, an environment can be set that will add an additional search path:

$config = ConfigFactory::make([
    'directory' => __DIR__ . '/config',
    'environment' => 'dev',
]);

Now when app.timezone is requested, both config/dev/app.php and config/app.php will be searched for the timezone key and the first result will be returned.

Best Practice

It is not recommended to add your staging or production secrets to configuration files that are checked into source control. A better solution is to use an env loader such as josegonzalez/dotenv or vlucas/phpdotenv. This will allow writing PHP configuration files that read from getenv:

return [
    'database' => [
        'password' => getenv('DATABASE_PASSWORD')
    ],
];

Refer the package documentation for how to populate env values from a .env file.

YAML Files

YAML configuration files are supported when the symfony/yaml package is installed:

$config = ConfigFactory::make([
    'directory' => __DIR__ . '/config',
    'environment' => 'dev',
    'type' => 'yaml'
]);

Note: This assumes that all configuration files have a .yaml extension! If you wish to combine PHP and YAML files, create a custom ConfigCollection with ConfigFactory.

Decorators

It is also possible to replace variables in configuration by using the VariableDecorator. This allows you to define variables at runtime without changing configuration:

use Northwoods\Config\Decorator\VariableDecorator;

// Wrap any existing configuration with the decorator
$config = new VariableDecorator($config);
$config->setVariables(['%cacheDir%' => '/tmp']);

Now any configuration value that contains %cacheDir% will have it replaced with /tmp:

return [
    'emails' => '%cacheDir%/emails',
];

Would resolve to /tmp/emails when decorated.

ConfigInterface

All configuration containers must implement ConfigInterface.

get()

Configuration values are accessed using the get($path, $default) method.

The first parameter is a "dot path" to search for in the form file.key.extra. An unlimited depth is supported.

The second parameter is a default value that will be returned if the path cannot be resolved. If the default is not provided null will be used.

// If not defined, $timezone will be null
$timezone = $config->get('app.timezone');

// If not defined, $timezone will be "UTC"
$timezone = $config->get('app.timezone', 'UTC');

set()

Configuration values can also be set at runtime using the set($path, $value) method.

The first parameter is a "dot path" to set in the form file.key.extra. An unlimited depth is supported.

The second parameter is the value to set for the path.

$config->set('app.timezone', 'Europe/Berlin');

Classes

The following classes are part of this package:

• ConfigFactory - factory for configuration containers
• ConfigDirectory - container that reads a single directory
• ConfigCollection - container that reads from an collection of containers
• Decorator\VariableDecorator - decorator to support variable replacement in configuration values
• Loader\LoaderFactory - factory for configuration readers
• Loader\PhpLoader - reader for .php configuration files
• Loader\YamlLoader - reader for .yaml configuration files

Functions

Getting and setting functionality is implemented by array_path and array_path_set:

use function Northwoods\Config\array_path;
use function Northwoods\Config\array_path_set;

$config = [
    'service' => [
        'uri' => 'http://api.example.com/'
    ],
];

// get a value from an array
$uri = array_path($config, 'service.uri');

// set a value in an array
$config = array_path_set($config, 'service.uri', 'https://api.example.com/v2/')

Examples

See more examples in the examples folder.

PHP Configuration File

Example of a PHP configuration file:

return [
    'timezone' => "America/New_York"
];

YAML Configuration File

Example of a YAML configuration file:

timezone: America/New_York

Original Ownership

This library is a fork of sinergi/config, starting in July 2017, and has changed significantly. Thank you to Gabriel Bull for creating the original package!

License

Config is licensed under The MIT License (MIT).

config's Issues

Feature request

Hi there,

I would like to be able to assign variables on the initialisation of Config and later be able to write values with %variableName%. I could create a parser outside but I think this could be a nice feature to have, what do you think?

Cheers