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

useInitPHP\ParameterBag\ParameterBag;
$bag = newParameterBag($_GET);
// GET /?user=aliceecho$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 = newParameterBag([
'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 = newParameterBag($data, ['separator' => '|']);
$bag->get('database|username');

Native PHP idioms

$bag = newParameterBag(['a' => 1, 'b' => 2]);
count($bag); // 2$bag['c'] = 3; // ArrayAccess writeisset($bag['c']); // trueforeach ($bagas$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.