Oihana PHP

accessors

Table of Contents

Functions

assertDocumentKeyValid()  : bool
Validates the key, separator, and type of the provided document before performing key-based operations.
deleteKeyValue()  : array<string|int, mixed>|object
Deletes a value from an array or object using a dot-notated key path.
getKeyValue()  : mixed
Retrieves a value from an array or object using a dot-notated key path.
hasKeyValue()  : bool
Checks whether a given key or property exists in an array or object, including nested paths.
resolveReferencePath()  : mixed
Navigates to the parent container of the last key segment in a nested structure.
setKeyValue()  : array<string|int, mixed>|object
Sets a value in an array or object using a dot-notated key path.

Functions

assertDocumentKeyValid()

Validates the key, separator, and type of the provided document before performing key-based operations.

assertDocumentKeyValid(array<string|int, mixed>|object $document, string $key[, string $separator = '.' ][, bool|null &$isArray = null ]) : bool

This internal helper ensures that:

  • The key is not empty.
  • The separator is not empty.
  • The document matches the expected type (array or object), or infers the type if $isArray is null.

If a mismatch between the inferred or forced type and the actual document type occurs, an InvalidArgumentException is thrown.

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

The input document (either an array or an object).

$key : string

The key or property name/path to validate.

$separator : string = '.'

The separator for nested paths (default is '.').

$isArray : bool|null = null

Optional reference: true for array, false for object, null to infer automatically.

Tags
throws
InvalidArgumentException

If the key or separator is empty, or the document type does not match $isArray.

example

Returns true:

$doc = ['foo' => 'bar'];
assertDocumentKeyValid( $doc , 'foo' ) ;

Returns false, sets $isArray = false

$doc = (object)['foo' => 'bar'];
assertDocumentKeyValid( $doc , 'foo' , '.' , $isArray ) ;

Returns true, sets $isArray = true

$doc = ['foo' => 'bar'];
assertDocumentKeyValid( $doc , 'foo' , '.' , $isArray ) ;

Throws InvalidArgumentException: "Key cannot be empty."

$doc = ['foo' => 'bar'];
assertDocumentKeyValid( $doc , '' , '.' ) ;

Throws InvalidArgumentException: "Separator cannot be empty."

$doc = (object)['foo' => 'bar'] ;
assertDocumentKeyValid( $doc , 'foo' , '' ) ;

Throws InvalidArgumentException: "Type mismatch: expected object, got array."

$doc = ['foo' => 'bar'];
assertDocumentKeyValid( $doc , 'foo' , '.' , false ) ;

Throws InvalidArgumentException: "Type mismatch: expected array, got stdClass."

$doc = new stdClass;
assertDocumentKeyValid( $doc , 'foo' , '.' , true ) ;
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
bool —

Returns the resolved value of $isArray: true for array, false for object.

deleteKeyValue()

Deletes a value from an array or object using a dot-notated key path.

deleteKeyValue(array<string|int, mixed>|object $document, string $key[, string $separator = '.' ][, bool|null $isArray = null ]) : array<string|int, mixed>|object

This utility supports:

  • Flat keys (e.g., "name")
  • Nested keys (e.g., "user.profile.name")
  • Wildcard deletion for sub-containers (e.g., "user.*")
  • Global wildcard "*" to clear the entire document

The input can be an associative array or a stdClass-like object. Intermediate paths are ensured to exist before deletion.

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

The data source (array or object) to operate on.

$key : string

The key path to delete (e.g. "foo.bar" or "foo." or "").

$separator : string = '.'

The separator used to split the key path. Defaults to '.'.

$isArray : bool|null = null

Optional: force array (true) or object (false) mode; if null, auto-detects.

Tags
throws
InvalidArgumentException

If input is not array/object, if key is invalid, or if path traversal encounters a type mismatch.

author

Marc Alcaraz (ekameleon)

since
1.0.0
example

Delete an array key :

$doc = ['name' => 'Alice', 'age' => 30];
$doc = deleteKeyValue( $doc , 'age' ) ;
// Result: ['name' => 'Alice']

Delete an array complex key expression 'user.name" :

$doc = ['user' => ['name' => 'Alice', 'email' => 'a@b.c']];
$doc = deleteKeyValue($doc, 'user.name');
// Result: ['user' => ['email' => 'a@b.c']]

Deletes all object properties :

$doc = (object)['x' => 1, 'y' => 2];
$doc = deleteKeyValue($doc, '*');
// Result: (object)[]

Delete all properties with a wildcard key expression.

$doc = ['meta' => ['a' => 1, 'b' => 2]];
$doc = deleteKeyValue($doc, 'meta.*');
// Result: ['meta' => []]
example 
$doc = (object)['user' => (object)['name' => 'Alice', 'email' => 'a@b.c']];
$doc = deleteKeyValue($doc, 'user.*');
// Result: (object)['user' => (object)[]]
Return values
array<string|int, mixed>|object —

The updated document after deletion.

getKeyValue()

Retrieves a value from an array or object using a dot-notated key path.

getKeyValue(array<string|int, mixed>|object $document, string $key[, mixed $default = null ][, string $separator = '.' ][, bool|null $isArray = null ]) : mixed

This function returns the value associated with a flat or nested key from the given array or object. It supports nested keys using a separator (default: '.'). If the path does not exist or a type mismatch occurs, the $default value is returned.

The structure type can be explicitly specified using $isArray, or it will be inferred automatically.

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

The source structure (array or object).

$key : string

The key or property to retrieve, supports nesting (e.g. 'user.name').

$default : mixed = null

The fallback value if the key does not exist. 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 for auto-detection.

Tags
throws
InvalidArgumentException

If the structure type is invalid or mismatched.

author

Marc Alcaraz (ekameleon)

since
1.0.0
example

Use a basic array key expression :

$doc = ['name' => 'Alice', 'age' => 30];
echo getKeyValue($doc, 'name'); // 'Alice'

Use a complex array key expression :

$doc = ['user' => ['name' => 'Alice']];
echo getKeyValue($doc, 'user.name'); // 'Alice'

Use with an object :

$doc = (object)['user' => (object)['email' => 'a@b.c']];
echo getKeyValue($doc, 'user.email'); // 'a@b.c'

Use a default value if the key not exist :

$doc = ['meta' => ['a' => 1]];
echo getKeyValue($doc, 'meta.b', 'default'); // 'default'

$doc = (object)['a' => 1];
echo getKeyValue($doc, 'b', 42); // 42
Return values
mixed —

The value found, or the default if the key path is not valid or not found.

hasKeyValue()

Checks whether a given key or property exists in an array or object, including nested paths.

hasKeyValue(array<string|int, mixed>|object $document, string $key[, string $separator = '.' ][, bool|null $isArray = null ]) : bool

This helper determines if the specified key exists in the given document (array or object). It supports nested access via a separator (default is '.') and can optionally force the document type (array or object).

If any part of the path does not exist, false is returned. This function does not rely on __get() or __isset() magic methods for objects.

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

The document (array or object) to inspect.

$key : string

The key or property path to check. Supports nesting with separator.

$separator : string = '.'

Separator used for nested paths. Default is '.'.

$isArray : bool|null = null

Optional: true if document is an array, false if object, null to auto-detect.

Tags
throws
InvalidArgumentException

If the document or key is invalid.

author

Marc Alcaraz (ekameleon)

since
1.0.0
example 
$doc = ['name' => 'Alice'];
hasKeyValue($doc, 'name'); // true
hasKeyValue($doc, 'age');  // false

$doc = ['user' => ['name' => 'Alice']];
hasKeyValue($doc, 'user.name'); // true
hasKeyValue($doc, 'user.age');  // false

$doc = (object)['user' => (object)['name' => 'Alice']];
hasKeyValue($doc, 'user.name'); // true
hasKeyValue($doc, 'user.age');  // false

$doc = [];
hasKeyValue($doc, 'config.debug.enabled'); // false

$doc = (object)[];
hasKeyValue($doc, 'meta.version.major'); // false
Return values
bool —

True if the full key path exists, false otherwise.

resolveReferencePath()

Navigates to the parent container of the last key segment in a nested structure.

& resolveReferencePath(array<string|int, mixed>|object &$document, array<string|int, mixed> $keys, bool $isArray) : mixed

This function traverses through nested arrays or objects based on the provided key path, ensuring that each intermediate level exists. It returns a reference to the parent container that should contain the final key segment.

It is typically used to prepare for read/write operations on nested values.

Requires external helpers:

  • ensureArrayPath() (creates intermediate arrays)
  • ensureObjectPath() (creates intermediate objects)
Parameters
$document : array<string|int, mixed>|object

The root document to navigate through (passed by reference).

$keys : array<string|int, mixed>

The exploded path as array segments (e.g. ['user', 'profile', 'name']).

$isArray : bool

If true, treat the structure as arrays; if false, as objects.

Tags
example 
$doc = [];
$keys = ['user', 'name'];
$ref = &resolveReferencePath($doc, $keys, true);
$ref['name'] = 'John';
// $doc is now: ['user' => ['name' => 'John']]

$doc = new stdClass();
$keys = ['config', 'theme'];
$ref = &resolveReferencePath($doc, $keys, false);
$ref->theme = 'dark';
// $doc is now: (object)['config' => (object)['theme' => 'dark']]

$doc = ['settings' => ['ui' => []]];
$keys = ['settings', 'ui', 'color'];
$ref = &resolveReferencePath($doc, $keys, true);
$ref['color'] = 'blue';
// $doc is now: ['settings' => ['ui' => ['color' => 'blue']]]
see
ensureArrayPath()
see
ensureObjectPath()
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
mixed —

Reference to the container (array or object) that should hold the final key.

setKeyValue()

Sets a value in an array or object using a dot-notated key path.

setKeyValue(array<string|int, mixed>|object $document, string $key, mixed $value[, string $separator = '.' ][, bool|null $isArray = null ]) : array<string|int, mixed>|object

This function assigns a value to a key or property in the given array or object. It supports nested assignment using a separator (default: '.'). If any intermediate path segment does not exist, it is created automatically.

The type of the structure can be explicitly forced with $isArray, or inferred automatically.

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

The target array or object to modify.

$key : string

The key or property name to set. Supports nesting (e.g., "user.name").

$value : mixed

The value to assign.

$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.

Tags
throws
InvalidArgumentException

If the provided type does not match the structure type.

author

Marc Alcaraz (ekameleon)

since
1.0.0
example 
$doc = ['name' => 'Alice'];
$doc = setKeyValue($doc, 'age', 30);
// Result: ['name' => 'Alice', 'age' => 30]

$doc = ['user' => ['name' => 'Alice']];
$doc = setKeyValue($doc, 'user.age', 30);
// Result: ['user' => ['name' => 'Alice', 'age' => 30]]

$doc = (object)['user' => (object)['name' => 'Alice']];
$doc = setKeyValue($doc, 'user.age', 30);
// Result: (object)['user' => (object)['name' => 'Alice', 'age' => 30]]

$doc = [];
$doc = setKeyValue($doc, 'config.debug.enabled', true);
// Result: ['config' => ['debug' => ['enabled' => true]]]

$doc = (object)[];
$doc = setKeyValue($doc, 'meta.version.major', 1);
// Result: (object)['meta' => (object)['version' => (object)['major' => 1]]]
Return values
array<string|int, mixed>|object —

The updated document after the value has been set.


        

        
    




    

    

                                

                

                            
    

        On this page

        
    


                

                            

            

    

        

            
Search results