PHPackages                             charcoal/config - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Parsing & Serialization](/categories/parsing)
4. /
5. charcoal/config

ActiveLibrary[Parsing & Serialization](/categories/parsing)

charcoal/config
===============

Charcoal component for configuration data and object modeling

v5.0.0(2y ago)012012MITPHPPHP ^7.4 || ^8.0

Since Aug 25Pushed 2y ago2 watchersCompare

[ Source](https://github.com/charcoalphp/config)[ Packagist](https://packagist.org/packages/charcoal/config)[ Docs](https://locomotivemtl.github.io/charcoal-config/)[ RSS](/packages/charcoal-config/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (5)Versions (41)Used By (12)

Charcoal Config
===============

[](#charcoal-config)

The Config package provides abstract tools for organizing configuration data and designing object data models.

Installation
------------

[](#installation)

```
composer require charcoal/config
```

Overview
--------

[](#overview)

### Entity & Config

[](#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

[](#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`](src/Charcoal/Config/AbstractEntity.php)
- **Methods**: `keys`, `data`, `setData`, `has`, `get`, `set`
- **Interface**: [`Charcoal\Config\EntityInterface`](src/Charcoal/Config/EntityInterface.php)
    - `ArrayAccess`
    - `JsonSerializable`
    - `Serializable`

#### Config

[](#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`](src/Charcoal/Config/AbstractConfig.php)
    - `IteratorAggregate`
    - `Psr\Container\ContainerInterface`
- **Methods**: `defaults`, `merge`, `addFile`
- **Interface**: [`Charcoal\Config\ConfigInterface`](src/Charcoal/Config/ConfigInterface.php)
    - `Charcoal\Config\EntityInterface`
    - `Charcoal\Config\FileAwareInterface`
    - `Charcoal\Config\SeparatorAwareInterface`
    - `Charcoal\Config\DelegatesAwareInterface`

### Features

[](#features)

- [Read data from INI, JSON, PHP, and YAML files](#file-loader)
- [Customizable separator for nested lookup](#key-separator-lookup)
- [Share configuration entries](#delegates-lookup)
- [Array accessible entities](#array-access)
- [Interoperable datasets](#interoperability)
- [Configurable objects](#configurable-objects)

#### File Loader

[](#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:

```
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.

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.

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

Check out the [documentation](docs/file-loader.md) and [examples](tests/Charcoal/Config/Fixture/pass) for more information.

#### Key Separator Lookup

[](#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.

```
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](docs/separator-lookup.md) for more information.

#### Delegates Lookup

[](#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`.

```
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](docs/delegates-lookup.md) for more information.

#### Array Access

[](#array-access)

The Entity object implements the `ArrayAccess` interface and therefore can be used with array style:

```
$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.

#### Interoperability

[](#interoperability)

The Config object implements [PSR-11](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()`.

```
$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.

#### Configurable Objects

[](#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](docs/configurable-objects.md) for examples and more information.

Resources
---------

[](#resources)

- [Contributing](https://github.com/charcoalphp/.github/blob/main/CONTRIBUTING.md)
- [Report issues](https://github.com/charcoalphp/charcoal/issues) and [send pull requests](https://github.com/charcoalphp/charcoal/pulls)in the [main Charcoal repository](https://github.com/charcoalphp/charcoal)

###  Health Score

36

—

LowBetter than 82% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity10

Limited adoption so far

Community24

Small or concentrated contributor base

Maturity80

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 51.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~82 days

Recently: every ~21 days

Total

39

Last Release

795d ago

Major Versions

0.10.1 → v2.1.22022-06-21

v2.2.3 → v3.1.02022-08-08

v3.1.8 → v4.0.02022-09-21

v4.1.0 → v5.0.02024-03-13

PHP version history (4 changes)v0.1.0PHP >=5.5.0

0.7PHP >=5.6.0

0.9.0PHP >=5.6.0 || >=7.0

v2.1.2PHP ^7.4 || ^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/cfb071c0ff7ce9500c528a003a2c53124248debc3e5bf367c17f89f5e6136125?d=identicon)[mducharme](/maintainers/mducharme)

![](https://www.gravatar.com/avatar/0a4f39523b4b2837562ba0848a0327b8d340118d1ba87cb0f5d59b1d5cb6beba?d=identicon)[mcaskill](/maintainers/mcaskill)

![](https://www.gravatar.com/avatar/f3f29e38395113e2400bdd7e51bea982b17f120d4d5a53d4473b53118ee46f8d?d=identicon)[JoelAlphonso](/maintainers/JoelAlphonso)

![](https://www.gravatar.com/avatar/4229f19eecd12c2b651b6502dcc5adfba48c5770db3d2dbea55fc92c7a246b2b?d=identicon)[BeneRoch](/maintainers/BeneRoch)

---

Top Contributors

[![mducharme](https://avatars.githubusercontent.com/u/12157?v=4)](https://github.com/mducharme "mducharme (67 commits)")[![mcaskill](https://avatars.githubusercontent.com/u/29353?v=4)](https://github.com/mcaskill "mcaskill (52 commits)")[![actions-user](https://avatars.githubusercontent.com/u/65916846?v=4)](https://github.com/actions-user "actions-user (11 commits)")[![BeneRoch](https://avatars.githubusercontent.com/u/3017380?v=4)](https://github.com/BeneRoch "BeneRoch (1 commits)")

---

Tags

charcoalconfigconfigurationphpread-only-repositoryjsonconfigurationxmlyamlymlcharcoalini

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/charcoal-config/health.svg)

```
[![Health](https://phpackages.com/badges/charcoal-config/health.svg)](https://phpackages.com/packages/charcoal-config)
```

###  Alternatives

[hassankhan/config

Lightweight configuration file loader that supports PHP, INI, XML, JSON, and YAML files

97513.5M170](/packages/hassankhan-config)[m1/vars

Vars is a simple to use and easily extendable configuration loader with in built loaders for ini, json, PHP, toml, XML and yaml/yml file types. It also comes with in built support for Silex and more frameworks to come soon.

69124.2k1](/packages/m1-vars)[thewunder/conphigure

Framework Agnostic Configuration Library

3115.9k](/packages/thewunder-conphigure)[davidepastore/slim-config

A slim middleware to read configuration from different files based on hassankhan/config

338.9k1](/packages/davidepastore-slim-config)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)