README

A small, dependency-free parameter container for PHP that handles both flat and nested (dotted-path) data with the same API.

Features

• Single API for flat and nested data; nesting is auto-detected from the constructor payload or toggled explicitly.
• Dotted-path access ($bag->get('database.user')) with a configurable separator.
• Optional, opt-in case-insensitive key handling.
• Implements PHP's standard collection contracts: ArrayAccess, Countable, IteratorAggregate.
• Strict validation of constructor options (typos throw instead of being silently ignored).
• Zero runtime dependencies; PHPStan level 8 clean.

Requirements

• PHP 7.4 or later (including 8.0–8.4)

Installation

composer require initphp/parameterbag

Quick start

use InitPHP\ParameterBag\ParameterBag;

$bag = new ParameterBag($_GET);

// GET /?user=alice
echo $bag->get('user', 'guest'); // 'alice'

$bag->set('locale', 'en_US')->set('debug', true);
$bag->has('debug');              // true
$bag->remove('debug');

Nested data (multi mode)

Pass a nested array (or set isMulti => true explicitly) and the bag will treat the separator (. by default) as a path delimiter:

$config = new ParameterBag([
    'database' => [
        'dsn'      => 'mysql:host=localhost',
        'username' => 'root',
        'password' => 'secret',
    ],
]);

$config->get('database.username');   // 'root'
$config->has('database.charset');    // false
$config->set('database.charset', 'utf8mb4');
$config->remove('database.password');

Use a custom separator if dots are part of your keys:

$bag = new ParameterBag($data, ['separator' => '|']);
$bag->get('database|username');

Native PHP idioms

$bag = new ParameterBag(['a' => 1, 'b' => 2]);

count($bag);          // 2
$bag['c'] = 3;        // ArrayAccess write
isset($bag['c']);     // true
foreach ($bag as $key => $value) { /* ... */ }

Public API

Configuration options

The constructor accepts a second array of options. Unknown keys raise ParameterBagInvalidArgumentException.

See docs/configuration.md and docs/usage/case-sensitivity.md.

Exceptions

See docs/exceptions.md.

Development

composer install
composer test         # PHPUnit
composer analyse      # PHPStan (level 8)
composer cs:check     # PHP-CS-Fixer dry-run
composer cs:fix       # PHP-CS-Fixer apply

CI runs the matrix across PHP 7.4, 8.0, 8.1, 8.2, 8.3, and 8.4.

Upgrading from v1

v2 introduces a small set of intentional behaviour changes (cache removed, isMulti auto-detect inverted, value-trim bug fixed, case-sensitive by default, strict option validation, new methods). A full migration guide lives at docs/upgrading-from-v1.md.

Contributing & Security

• Contributing guidelines
• Code of Conduct
• Security policy

Credits

• Muhammet ŞAFAK <info@muhammetsafak.com.tr>

License

Released under the MIT License.