InitPHP ParameterBag

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

Method	Purpose	Docs
get(string $key, mixed $default = null): mixed	Look up a value (dotted paths in multi mode).	usage/basic-usage
has(string $key): bool	Existence check (null values count as present).	usage/basic-usage
set(string $key, mixed $value): self	Assign or replace a value.	usage/basic-usage
remove(string ...$keys): self	Delete one or more keys.	usage/basic-usage
merge(array|ParameterBagInterface ...$payloads): self	Shallow merge (flat) or recursive replace (multi).	usage/merging
replace(array $data): self	Swap the entire stack.	api-reference
all(): array	Return the current stack as a plain array.	api-reference
keys(): array / values(): array	Top-level keys / values in insertion order.	api-reference
count(): int	Top-level entry count (also via count($bag)).	usage/iteration-and-counting
getIterator(): ArrayIterator	Iterates top-level entries.	usage/iteration-and-counting
isEmpty(): bool	True when the stack has no entries.	api-reference
clear(): void	Empty the stack, keep options.	api-reference
close(): void	Empty the stack and reset options to defaults.	api-reference

Configuration options

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

Key	Type	Default	Description
isMulti	bool	auto-detected from $data	Enables dotted-path semantics.
separator	non-empty-string	'.'	Delimiter for dotted paths. Ignored in flat mode.
caseInsensitive	bool	false	When true, every key (constructor payload, set/get/has/remove arguments, merge input) is folded to lower-case. Matches the legacy v1 behaviour.

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

Exceptions

Exception	Raised when
InitPHP\ParameterBag\Exception\ParameterBagInvalidArgumentException	Unknown option key, non-array/non-ParameterBag argument to merge(), or $bag[] = $v ArrayAccess append. Extends \InvalidArgumentException.

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.