Array Dot

Description

Array Dot is a set of functions that allows to manipulate PHP arrays using custom dot notation known from JavaScript. This implementation brings some custom syntax which will be explained bellow.

Available Functions

<?php 

array_dot_get(array $array, string $path) : mixed;
array_dot_set(array $array, string $path, mixed $value) : mixed;
array_dot_rename(array $array, string $path, string $newName) : mixed;
array_dot_exists(array $array, string $path) : bool;
array_dot_steps(string $path) : array;

Dot Notation - Basic Syntax

<?php 

$array = [
    'foo' => [
        'bar' => [
            'baz' => 1000
        ]
    ]
];

$value = array_dot_get('foo.bar.baz'); // 1000

$array = array_dot_set([], 'foo.bar.baz', 1000); // ['foo' => ['bar' => ['baz' => 1000]]];

In above example foo.bar.baz is path which also supports integer keys. For exmaple foo.0.baz.

foo, bar, baz represents single steps (keys) of path.

Dot Notation - Custom Operators

• ? - nullsafe
• * - wildcard
• ?* - nullsafe wildcar

Dot Notation - Custom Syntax

• {} - multipath

Nullsafe Operator - ?

Supported in functions:

• array_dot_get

Dot notation is strict by default, which means that if any step of path is not present, function will throw exception.

This behavior can be changed by ? nullsafe operator.

<?php 

$array = [
    'foo' => [
        'bar' => [
            'baz' => 1000
        ]
    ]
];

$value = array_dot_get('foo.bar.nothing'); // InvalidPathException
$value = array_dot_get('foo.bar.?nothing'); // null

Nullsafe does not need to be used with the last step of path.

<?php 

$array = [
    'foo' => [
        'fii' => [
            'oop' => 1000
        ]
    ]
];

$value = array_dot_get('foo.?bar.nothing'); // null

Wildcard Operator - *

Supported in functions:

• array_dot_get
• array_dot_set
• array_dot_rename

Wildcard operator allows to access all paths in nested arrays.

<?php 

$array = [
    'users' => [
        [
            'id' => 1
        ],
        [
            'id' => 2
        ],
    ]
];

$value = array_dot_get('foo.*.id'); // [1, 2]

Nullsafe Wildcard Operator - ?*

Supported in functions:

• array_dot_get

Nullsafe Wildcard operator allows to access all paths in nested arrays for non symetric collections.

<?php 

$array = [
    'users' => [
        [
            'id' => 1,
            'name' => 'John'
        ],
        [
            'id' => 2
        ],
    ]
];

$value = array_dot_get('foo.*.name'); // ['John']

Multipath Syntax - {}

Supported in functions:

• array_dot_get

Get only selected keys from nested array

<?php 

$array = [
    'users' => [
        [
            'id' => 1,
            'name' => 'John',
            'status' => 'active',
        ],
        [
            'id' => 2,
            'name' => 'Mikel',
            'status' => 'active',
            'role' => 'ADMIN'
        ],
    ]
];

$value = array_dot_get('foo.*.{id,?role}'); // [[1, null], [2, 'ADMIN']]

Development

In order to install dependencies please, launch following commands:

composer install
composer install --working-dir ./tools

Run Tests

In order to execute full test suite, please launch following command:

composer build

It's recommended to use pcov for code coverage however you can also use xdebug by setting XDEBUG_MODE=coverage env variable.