Configuration

Configuration#

ArrayKit configuration objects provide dot-notation access to nested settings.

Classes:

Infocyph\ArrayKit\Config\Config
Infocyph\ArrayKit\Config\LazyFileConfig

Config supports optional hooks via explicit getWithHooks(), setWithHooks(), and fillWithHooks() methods. LazyFileConfig loads namespace files only on first keyed access.

Loading Configuration#

You can load config from an array or a PHP file that returns an array.

<?php
use Infocyph\ArrayKit\Config\Config;

$config = new Config();

$ok = $config->loadArray([
    'app' => ['name' => 'ArrayKit', 'env' => 'local'],
    'db' => ['host' => 'localhost', 'port' => 3306],
]);

// Or from file:
// $ok = $config->loadFile(__DIR__.'/config.php');

Important behavior:

loadArray() and loadFile() only load when config is currently empty.
If already loaded, they return false and do not overwrite existing items.
replace() always replaces in-memory config items.
reload() replaces from array or readable file path.
Facade-based config creation is documented in Facade.

Reading Values#

<?php
use Infocyph\ArrayKit\Config\Config;

$config = new Config();
$config->loadArray([
    'app' => ['name' => 'ArrayKit', 'env' => 'local'],
    'queue' => ['driver' => 'sync'],
]);

$all = $config->all();
$name = $config->get('app.name');                         // ArrayKit
$fallback = $config->get('app.debug', false);             // false
$many = $config->get(['app.name', 'queue.driver']);

$has = $config->has('app.name');                          // true
$hasAny = $config->hasAny(['missing.path', 'queue.driver']); // true
$required = $config->getOrFail('app.name');               // throws if missing

Typed Getters#

Use nullable/default-friendly typed getters when you want soft type access:

<?php
$name = $config->getString('app.name');
$port = $config->getInt('db.port', 3306);
$ratio = $config->getFloat('metrics.sample_ratio', 0.5);
$debug = $config->getBool('app.debug', false);
$hosts = $config->getList('cluster.hosts', []);
$cache = $config->getArray('cache', []);
$mode = $config->getEnum('app.mode', AppMode::class, AppMode::Prod);

Writing Values#

Single key:

<?php
$config->set('cache.driver', 'file');
$config->set('db.port', 5432);

Bulk set:

<?php
$config->set([
    'app.env' => 'production',
    'cache.prefix' => 'arraykit_',
]);

Overwrite control:

<?php
// Do not overwrite existing value
$config->set('app.env', 'local', overwrite: false);

Fill Missing Values#

fill() writes only if target key does not already exist.

<?php
$config->fill('mail.driver', 'smtp');
$config->fill([
    'mail.host' => 'localhost',
    'mail.port' => 1025,
]);

// Existing keys are preserved
$config->fill('app.env', 'staging');

Removing Values#

<?php
$config->forget('cache.prefix');
$config->forget(['mail.host', 'mail.port']);

Merging, Snapshots, and Read-Only Mode#

<?php
$config->snapshot('before-runtime');

$config->merge(['app' => ['env' => 'production']]);   // deep merge
$config->overlay(['features' => ['beta' => true]]);   // top-level overlay

$changed = $config->changed('before-runtime');         // true/false
$config->restore('before-runtime');                    // rollback

$config->readonly();                                   // lock writes
$locked = $config->isReadonly();                       // true
$config->readonly(false);                              // unlock

Array-Value Helpers#

prepend() and append() are useful for list-type config nodes.

<?php
$config->set('middleware', ['auth']);
$config->append('middleware', 'throttle');
$config->prepend('middleware', 'cors');

// ['cors', 'auth', 'throttle']
$middleware = $config->get('middleware');

Config Hooks (Explicit)#

Config allows per-key transformation on read/write, while keeping get()/set()/fill() hook-free for maximum base-path performance.

<?php
use Infocyph\ArrayKit\Config\Config;

$config = new Config();

$config->onSet('user.name', fn ($v) => strtoupper((string) $v));
$config->onGet('user.name', fn ($v) => strtolower((string) $v));

$config->setWithHooks('user.name', 'Alice');
echo $config->getWithHooks('user.name'); // alice

Bulk operations with hooks:

<?php
$config->onSet('user.email', fn ($v) => trim((string) $v));

$config->setWithHooks([
    'user.name' => 'JOHN',
    'user.email' => ' [email protected] ',
]);

$vals = $config->getWithHooks(['user.name', 'user.email']);

Practical Pattern#

Use config as a mutable runtime container for app setup:

<?php
$config = new Config();
$config->loadFile(__DIR__.'/config.php');

// Normalize selected runtime values
$config->onSet('app.timezone', fn ($v) => trim((string) $v));
$config->onGet('app.timezone', fn ($v) => strtoupper((string) $v));

$config->setWithHooks('app.timezone', ' utc ');
$tz = $config->getWithHooks('app.timezone'); // UTC

LazyFileConfig#

Use LazyFileConfig when configuration is split into top-level namespace files like db.php, cache.php, queue.php.

Rules:

Key format is namespace.path.to.key.
On first access, only {directory}/{namespace}.php is loaded.
Remaining key segments are resolved using dot notation.

<?php
use Infocyph\ArrayKit\Config\LazyFileConfig;

$config = new LazyFileConfig(__DIR__.'/config');

// Loads only config/db.php:
$host = $config->get('db.host', '127.0.0.1');

// Optional warm-up:
$config->preload(['db', 'cache']);

$loaded = $config->loadedNamespaces(); // ['db', 'cache']
$isLoaded = $config->loaded('db');     // alias of isLoaded()