Download the PHP package locomotivemtl/charcoal-config without Composer
On this page you can find all versions of the php package locomotivemtl/charcoal-config. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download locomotivemtl/charcoal-config
More information about locomotivemtl/charcoal-config
Files in locomotivemtl/charcoal-config
Package charcoal-config
Short Description Charcoal component for configuration data and object modeling
License MIT
Homepage https://locomotivemtl.github.io/charcoal-config/
Informations about the package charcoal-config
Charcoal Config
A Charcoal component for organizing configuration data and designing object data models.
This component is the glue for much of the Charcoal framework.
Table of Contents
- Installation
- Requirements
- Entity & Config
- Entity
- Config
- Features
- File Loader
- Key Separator Lookup
- Delegated Data Lookup
- Array Access
- Interoperability
- Configurable objects
- Development
- API Documentation
- Development Dependencies
- Coding Style
- Credits
- License
Installation
The preferred (and only supported) method is with Composer:
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.
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.
- 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.
- 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.
A configuration file can be imported into a Config object via the addFile($path)
method, or by direct instantiation:
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.
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.
Check out the examples for more information.
Key Separator Lookup
It is possible to lookup, retrieve, assign, or merge values in multi-dimensional arrays using key separators.
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.
Check out the documentation for more information.
Delegates Lookup
Delegates allow several objects to share values and act as fallbacks when the current object cannot resolve a given data key.
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
.
Check out the documentation for more information.
Array Access
The Entity object implements the ArrayAccess
interface and therefore can be used with array style:
👉 A data key MUST be a string otherwise
InvalidArgumentException
is thrown.
Interoperability
The Config object implements PSR-11: Psr\Container\ContainerInterface
.
This interface exposes two methods: get()
and has()
. These methods are implemented by the Entity object as aliases of ArrayAccess::offsetGet()
and ArrayAccess::offsetExists()
.
👉 A call to the
get()
method with a non-existing key DOES NOT throw an exception.
Configurable Objects
Also provided in this package is a Configurable mixin:
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.
The Config object can be assigned with setConfig()
and retrieved with config()
.
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.
Check out the documentation for examples and more information.
Development
To install the development environment:
To run the scripts (phplint, phpcs, and phpunit):
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:
- PSR-1
- PSR-2
- PSR-4, autoloading is therefore provided by Composer.
- phpDocumentor comments.
- .editorconfig for coding standards.
Coding style validation / enforcement can be performed with
composer phpcs
. An auto-fixer is also available withcomposer phpcbf
.This module should also throw no error when running
phpstan analyse -l7 src/
👍.
Credits
License
Charcoal is licensed under the MIT license. See LICENSE for details.
All versions of charcoal-config with dependencies
ext-json Version *
ext-spl Version *
psr/container Version ^1.0