kaiseki/config

Type-safe access to array configurations

2.1.0 2026-06-10 21:36 UTC

Requires

• php: ^8.2
• psr/container: ^1.1 || ^2.0
• thecodingmachine/safe: ^1.3 || ^2.0

Requires (Dev)

• bnf/phpstan-psr-container: ^1.1
• kaiseki/php-coding-standard: ^1.0
• maglnet/composer-require-checker: ^4.0
• phpstan/extension-installer: ^1.4
• phpstan/phpstan: ^2.0
• phpstan/phpstan-phpunit: ^2.0
• phpstan/phpstan-strict-rules: ^2.0
• phpunit/phpunit: ^11.0
• roave/security-advisories: dev-latest
• thecodingmachine/phpstan-safe-rule: ^1.4

MIT

• Kaiseki
• David Mondok
• Wolfgang Schaefer

README

Type-safe access to array configurations, with dot-notation paths.

Wrap a config array (or pull one from a PSR-11 container) and read values with typed accessors that throw on a missing key or a wrong type — so a typo or a misconfigured value fails loudly instead of silently returning null.

Installation

composer require kaiseki/config

Requires PHP 8.2 or newer.

Usage

use Kaiseki\Config\NestedArrayConfig;

$config = new NestedArrayConfig([
    'db' => [
        'host' => 'localhost',
        'port' => 3306,
    ],
]);

$config->string('db.host'); // "localhost"
$config->int('db.port');    // 3306
$config->has('db.user');    // false

Paths are dot-separated. Typed getters (string(), int(), float(), bool(), array()) throw UnknownKeyException if the path is missing and InvalidValueException if the value is not of the expected type.

Defaults and nullables

$config->string('db.user', 'root');      // default when the key is absent
$config->get('db.password', null, true); // allow null (nullable)

Typed lists

stringList(), intList(), and floatList() read the array at a key and narrow it to a list<string> / list<int> / list<float>, dropping any element of the wrong type and re-indexing the result:

$config = new NestedArrayConfig(['paths' => ['/a', 42, '/b']]);

$config->stringList('paths'); // ['/a', '/b']  — the 42 is dropped, keys re-indexed

They behave like array() for the key itself: a missing key throws UnknownKeyException and a non-array value throws InvalidValueException, unless a default list is supplied:

$config->stringList('paths', []); // [] when the key is absent

String-keyed maps

stringKeyedArray() narrows the array at a key to an array<string, mixed>, dropping any integer-keyed elements while keeping the string keys — handy for reading an options map where a stray list entry would otherwise leak in:

$config = new NestedArrayConfig(['opts' => ['public' => true, 0 => 'ignored', 'label' => 'X']]);

$config->stringKeyedArray('opts'); // ['public' => true, 'label' => 'X']

It follows the same missing-key / wrong-type rules as array().

From a PSR-11 container

Config::fromContainer() reads the config entry from a container:

use Kaiseki\Config\Config;

$config = Config::fromContainer($container); // expects $container->get('config')

Config::initClassMap() resolves a map of keys to class instances from the container:

$map = Config::initClassMap($container, ['logger' => LoggerInterface::class]);
// ['logger' => <instance from container>]

Development

composer install
composer check   # check-deps, cs-check, phpstan, phpunit

License

MIT — see LICENSE.