ensureKeyValue()

Ensures that one or more keys or properties exist in an array or object.

Parameters

$document : array<string|int, mixed>|object

The target document (array or object).

$keys : string|array<string|int, mixed>

A single key, a list of keys ['a', 'b'], or an associative map ['key' => 'default'].

$default : mixed = null

Global default value (or Closure) for keys without a specific default. Default is null.

$separator : string = '.'

Separator used to split nested keys. Default is '.'.

$isArray : bool|null = null

Optional: true for array mode, false for object mode, null to auto-detect.

$enforce : bool = false

Force initialization of non-initialized typed properties. Default: false.

Tags

throws

InvalidArgumentException

If the document or key definition is invalid.

example

Ensure simple keys with a global default :

$doc = [];
$doc = ensureKeyValue($doc, ['name', 'age'], null);
// Result: ['name' => null, 'age' => null]

Ensure keys with specific default values :

$doc = [];
$doc = ensureKeyValue($doc, [
'role' => 'guest',   // Specific default
'active'             // Uses global default (true)
], true);
// Result: ['role' => 'guest', 'active' => true]

Use a Closure for lazy evaluation (heavy calculation) :

$doc = [];
$doc = ensureKeyValue($doc, 'created_at', fn() => new DateTimeImmutable());
// Result: ['created_at' => object(DateTimeImmutable)]

Enforce initialization of typed properties (PHP 7.4+) :

class User { public string $name; } // Uninitialized
$doc = new User();

// Without enforce: Property exists, so it's skipped (remains uninitialized).
// With enforce: Detects uninitialized state and sets default.
$doc = ensureKeyValue($doc, 'name', 'Anonymous', '.', null, true);

// Result: User object with $name = 'Anonymous'

Use with named arguments (PHP 8+) to skip optional parameters:

$doc = new User();
// We skip separator and isArray to target 'enforce' directly
ensureKeyValue($doc, 'name', default: 'John', enforce: true);

author

Marc Alcaraz (ekameleon)

since

1.0.8