northwoods / config
Simple configuration loader
Installs: 15 454
Dependents: 0
Suggesters: 0
Security: 0
Stars: 16
Watchers: 3
Forks: 0
Open Issues: 0
Requires
- php: >=7.0
Requires (Dev)
- eloquent/phony-phpunit: ^3.0
- squizlabs/php_codesniffer: ^3.0
- symfony/yaml: ^2.8 || ^3.0
Suggests
- josegonzalez/dotenv: Adds support for loading .env files
- symfony/yaml: Adds support for loading .yaml files
README
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 containersConfigDirectory
- container that reads a single directoryConfigCollection
- container that reads from an collection of containersDecorator\VariableDecorator
- decorator to support variable replacement in configuration valuesLoader\LoaderFactory
- factory for configuration readersLoader\PhpLoader
- reader for.php
configuration filesLoader\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).