locomotivemtl/charcoal-config

Charcoal component for configuration data and object modeling

Tuesday, June 5, 2018
by mducharme
Repository
10 Watchers
0 Stars
14,126 Installations

PHP
13 Dependents
0 Suggesters
0 Forks
0 Open issues
19 Versions
7 % Grown

The README.md

Charcoal Config

![License][badge-license] ![Code Quality][badge-scrutinizer] ![SensioLabs Insight][badge-sensiolabs] , _(*1)

A Charcoal component for organizing configuration data and designing object data models., _(*2)

This component is the glue for much of the Charcoal framework., _(*3)

Installation
- Requirements
Entity & Config
- Entity
- Config
Features
Development
Credits
License

Installation

The preferred (and only supported) method is with Composer:, _(*4)

$ composer require locomotivemtl/charcoal-config

Requirements

PHP 5.6+: PHP 7 is recommended.

PSR

PSR-11: Common interface for dependency containers. For interoperable configsets.

Entity & Config

The Config component simplifies access to object data. It provides a property-based user interface for retrieving and storing arbitrary data within application code. Data is organized into two primary object types: Entity and Config., _(*5)

Entity

Entities represent simple data-object containers designed as a flexible foundation for domain model objects.
Examples: a single result from a repository or serve as the basis for each component of an MVC system., _(*6)

Class: Charcoal\Config\AbstractEntity
Methods: keys, data, setData, has, get, set
Interface: Charcoal\Config\EntityInterface
- ArrayAccess
- JsonSerializable
- Serializable

Config

Configs are advanced Entities designed for runtime configuration values with support for loading files and storing hierarchical data.
Examples: application preferences, service options, and factory settings., _(*7)

Class: Charcoal\Config\AbstractConfig
- IteratorAggregate
- Psr\Container\ContainerInterface
Methods: defaults, merge, addFile
Interface: Charcoal\Config\ConfigInterface
- Charcoal\Config\EntityInterface
- Charcoal\Config\FileAwareInterface
- Charcoal\Config\SeparatorAwareInterface
- Charcoal\Config\DelegatesAwareInterface

Features

Read data from INI, JSON, PHP, and YAML files
Customizable separator for nested lookup
Share configuration entries
Array accessible entities
Interoperable datasets
Configurable objects

File Loader

The Config container currently supports four file formats: INI, JSON, PHP, and YAML., _(*8)

A configuration file can be imported into a Config object via the addFile($path) method, or by direct instantiation:, _(*9)

use Charcoal\Config\GenericConfig as Config;

$cfg = new Config('config.json');
$cfg->addFile('config.yml');

The file's extension will be used to determine how to import the file. The file will be parsed and, if its an array, will be merged into the container., _(*10)

If you want to load a configuration file without adding its content to the Config, use loadFile($path) instead. The file will be parsed and returned regardless if its an array., _(*11)

$data = $cfg->loadFile('config.php');

Check out the documentation and examples for more information., _(*12)

Key Separator Lookup

It is possible to lookup, retrieve, assign, or merge values in multi-dimensional arrays using key separators., _(*13)

In Config objects, the default separator is the period character (.). The token can be retrieved with the separator() method and customized using the setSeparator() method., _(*14)

use Charcoal\Config\GenericConfig as Config;

$cfg = new Config();
$cfg->setSeparator('/');
$cfg->setData([
    'database' => [
        'params' => [
            'name' => 'mydb',
            'user' => 'myname',
            'pass' => 'secret',
        ]
    ]
]);

echo $cfg['database/params/name']; // "mydb"

Check out the documentation for more information., _(*15)

Delegates Lookup

Delegates allow several objects to share values and act as fallbacks when the current object cannot resolve a given data key., _(*16)

In Config objects, delegate objects are regsitered to an internal stack. If a data key cannot be resolved, the Config iterates over each delegate in the stack and stops on the first match containing a value that is not NULL., _(*17)

use Charcoal\Config\GenericConfig as Config;

$cfg = new Config([
    'driver' => null,
    'host'   => 'localhost',
]);
$delegate = new Config([
    'driver' => 'pdo_mysql',
    'host'   => 'example.com',
    'port'   => 11211,
]);

$cfg->addDelegate($delegate);

echo $cfg['driver']; // "pdo_mysql"
echo $cfg['host']; // "localhost"
echo $cfg['port']; // 11211

Check out the documentation for more information., _(*18)

Array Access

The Entity object implements the ArrayAccess interface and therefore can be used with array style:, _(*19)

$cfg = new \Charcoal\Config\GenericConfig();

// Assigns a value to "foobar"
$cfg['foobar'] = 42;

// Returns 42
echo $cfg['foobar'];

// Returns TRUE
isset($cfg['foobar']);

// Returns FALSE
isset($cfg['xyzzy']);

// Invalidates the "foobar" key
unset($cfg['foobar']);

👉 A data key MUST be a string otherwise InvalidArgumentException is thrown., _(*20)

Interoperability

The Config object implements PSR-11: Psr\Container\ContainerInterface., _(*21)

This interface exposes two methods: get() and has(). These methods are implemented by the Entity object as aliases of ArrayAccess::offsetGet() and ArrayAccess::offsetExists()., _(*22)

$config = new \Charcoal\Config\GenericConfig([
    'foobar' => 42
]);

// Returns 42
$config->get('foobar');

// Returns TRUE
$config->has('foobar');

// Returns FALSE
$config->has('xyzzy');

👉 A call to the get() method with a non-existing key DOES NOT throw an exception., _(*23)

Configurable Objects

Also provided in this package is a Configurable mixin:, _(*24)

Charcoal\Config\ConfigrableInterface
Charcoal\Config\ConfigurableTrait

Configurable objects (which could have been called "Config Aware") can have an associated Config object that can help define various properties, states, or other., _(*25)

The Config object can be assigned with setConfig() and retrieved with config()., _(*26)

An added benefit of ConfigurableTrait is the createConfig($data) method which is used to create a Config object if one is not assigned. This method can be overridden in sub-classes to customize the instance returned and whatever initial state might be needed., _(*27)

Check out the documentation for examples and more information., _(*28)

Development

To install the development environment:, _(*29)

$ composer install

To run the scripts (phplint, phpcs, and phpunit):, _(*30)

$ composer test

API Documentation

The auto-generated phpDocumentor API documentation is available at:
https://locomotivemtl.github.io/charcoal-config/docs/master/
The auto-generated apigen API documentation is available at:
https://codedoc.pub/locomotivemtl/charcoal-config/master/

Development Dependencies

Coding Style

The charcoal-config module follows the Charcoal coding-style:, _(*31)

PSR-1
PSR-2
PSR-4, autoloading is therefore provided by Composer.
phpDocumentor comments.
phpcs.xml.dist and .editorconfig for coding standards.

Coding style validation / enforcement can be performed with composer phpcs. An auto-fixer is also available with composer phpcbf., _(*32)

This module should also throw no error when running phpstan analyse -l7 src/ 👍., _(*33)

Credits

License

Charcoal is licensed under the MIT license. See LICENSE for details., _(*34)

The Versions

05/06 2018

dev-master

9999999-dev https://locomotivemtl.github.io/charcoal-config/

Charcoal component for configuration data and object modeling

library charcoal-config

Charcoal component for configuration data and object modeling

locomotivemtl/charcoal-config

The README.md

Charcoal Config

Table of Contents

Installation

Requirements

PSR

Entity & Config

Entity

Config

Features

File Loader

Key Separator Lookup

Delegates Lookup

Array Access

Interoperability

Configurable Objects

Development

API Documentation

Development Dependencies

Coding Style

Credits

License

The Versions

dev-master

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

dev-mcaskill-patch-xml

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

0.9.0

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

dev-mcaskill-patch-cleanup

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

dev-mcaskill-patch-fileawareness

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

0.8

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

dev-mcaskill-patch-1

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

dev-mcaskill-develop

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

0.7

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

0.6.1

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

0.6

The Requires

The Development Requires

by Mathieu Ducharme