README

Provides an object that maps configuration keys to values.

Installation

You can install the package via composer:

composer require ghostwriter/config

Star ⭐️ this repo if you find it useful

You can also star (🌟) this repo to find it easier later.

Features

🔑 Dot Notation: Access nested configuration using dot, forward slash, or backslash separators
🔄 Flexible Merging: Merge arrays, files, or directories
🔧 Array Operations: Append and prepend values to configuration arrays
🎯 Scoped Configuration: Wrap nested configuration into isolated instances

API

/**
 * @template T of (array<non-empty-string,T>|bool|float|int|null|string)
 */
interface ConfigurationInterface
{
    /** @throws ConfigurationExceptionInterface */
    public function append(string $key, mixed $value): void;

    /** @throws ConfigurationExceptionInterface */
    public function get(string $key, mixed $default = null): mixed;

    /** @throws ConfigurationExceptionInterface */
    public function has(string $key): bool;

    /**
     * @param array<non-empty-string,T> $options
     * @throws ConfigurationExceptionInterface
     */
    public function merge(array $options): void;

    /** @throws ConfigurationExceptionInterface */
    public function mergeDirectory(string $directory): void;

    /** @throws ConfigurationExceptionInterface */
    public function mergeFile(string $file, ?string $key = null): void;

    /** @throws ConfigurationExceptionInterface */
    public function prepend(string $key, mixed $value): void;

    public function reset(): void;

    /** @throws ConfigurationExceptionInterface */
    public function set(string $key, mixed $value): void;

    /** @return array<non-empty-string,T> */
    public function toArray(): array;

    /** @throws ConfigurationExceptionInterface */
    public function unset(string $key): void;

    /**
     * @param array<non-empty-string,T> $default
     * @throws ConfigurationExceptionInterface
     */
    public function wrap(string $key, array $default = []): self;
}

Usage

Given the following configuration directory structure

path/to/config/directory/app.php
path/to/config/directory/database.php
path/to/config/directory/file.php

$directory = 'path/to/config/directory';
$file = 'path/to/config/directory/file.php';
$options = [
    'settings' => [
        'enable' => true,
    ],
];

$configuration = Configuration::new($options);
$configuration->has('settings.disabled'); // false
$configuration->get('settings.disabled'); // null
$configuration->get('settings.disabled', 'default'); // 'default'

$configuration->set('settings.disabled', false);

$configuration->has('settings.disabled'); // true
$configuration->get('settings.disabled'); // false

$configuration->toArray(); // ['settings' => ['enable'=>true,'disabled'=>false]]

$configuration->unset('settings.disabled');

$configuration->get('settings.disabled'); // null
$configuration->get('settings.disabled', 'default'); // 'default'

$configuration->toArray(); // ['settings' => ['enable'=>true]]

// from an array
$configuration = Configuration::new($options); 
$configuration->toArray(); // ['settings' => ['enable'=>true]]

// merge additional config options
$additionalOptions = [
    'settings' => [
        'disabled' => false,
    ],
];
$configuration = Configuration::new($options); 
$configuration->merge($additionalOptions);
$configuration->toArray(); // ['settings' => ['enable'=>true,'disabled'=>false]]

// from an array with dot notation
$configuration = Configuration::new($options); 
$configuration->toArray(); // ['settings' => ['enable'=>true]]

$configuration->has('settings'); // true
$configuration->has('settings.enable'); // true
$configuration->get('settings.enable'); // true

// from a directory
$configuration = Configuration::new();

$configuration->mergeDirectory($directory);

$configuration->toArray(); // output below
// [
//      'app' => ['name'=>'App','version'=>'1.0.0'],
//      'database' => ['host'=>'localhost','port'=>3306],
//      'file' => ['path'=>'/path/to/file']
// ]

// from a file
$configuration = Configuration::new();
$configuration->mergeFile($file);
$configuration->toArray(); // ['path'=>'/path/to/file']

// from a file with a namespace key
$configuration = Configuration::new();
$configuration->mergeFile($file, 'custom');
$configuration->toArray(); // ['custom' => ['path'=>'/path/to/file']]

// append values
$configuration = Configuration::new($options); 
$configuration->append('settings', ['key' => 'value']);
$configuration->toArray(); // ['settings' => ['enable'=>true,'key'=>'value']]

// prepend values
$configuration = Configuration::new($options); 
$configuration->prepend('settings', ['key' => 'value']);
$configuration->toArray(); // ['settings' => ['key'=>'value','enable'=>true]]

// wrap configuration into a new scoped instance
$configuration = Configuration::new([
    'database' => [
        'host' => 'localhost',
        'port' => 3306,
    ],
]);

$dbConfig = $configuration->wrap('database');
$dbConfig->get('host'); // 'localhost'
$dbConfig->toArray(); // ['host' => 'localhost', 'port' => 3306]

// wrap with default values when key doesn't exist
$cacheConfig = $configuration->wrap('cache', ['driver' => 'redis']);
$cacheConfig->toArray(); // ['driver' => 'redis']

// reset configuration
$configuration = Configuration::new(['key' => 'value']);
$configuration->toArray(); // ['key' => 'value']

$configuration->reset();
$configuration->toArray(); // []

// mixed separators support (dot, forward slash, backslash)
$configuration = Configuration::new();
$configuration->set('app.name', 'MyApp');
$configuration->get('app.name'); // 'MyApp'
$configuration->get('app/name'); // 'MyApp' (forward slash)
$configuration->get('app\name'); // 'MyApp' (backslash)

$configuration->has('app.name'); // true
$configuration->has('app/name'); // true
$configuration->has('app\name'); // true

// append/prepend to nested keys
$configuration = Configuration::new();
$configuration->append('list.items', 'first');
$configuration->append('list.items', 'second');
$configuration->toArray(); // ['list' => ['items' => ['first', 'second']]]

$configuration->prepend('list.items', 'zero');
$configuration->toArray(); // ['list' => ['items' => ['zero', 'first', 'second']]]

// automatic array promotion
$configuration = Configuration::new();
$configuration->set('parent', 'scalar');
$configuration->set('parent.child', 'value'); // 'parent' is promoted to array
$configuration->toArray(); // ['parent' => ['child' => 'value']]

Changelog

Please see CHANGELOG.md for more information on what has changed recently.

Credits

License

Please see LICENSE for more information on the license that applies to this project.

Security

Please see SECURITY.md for more information on security disclosure process.

ghostwriter / config

Maintainers

Details