nolikein / array-mapping
Read, write and build nested arrays with a path such as "user.address.city".
Requires
- php: ^8.4
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.95
- pestphp/pest: ^4.0
- phpstan/phpstan: ^2.3
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-11 21:33:25 UTC
README

Overview
Read, write and build nested arrays with a path such as "user.address.city". The separator is a dot by default and can be any non-empty string.
Requirements
PHP 8.4 or later.
Installation
composer require nolikein/array-mapping
Usage
MagicArrayFacade exposes static methods; MagicArray has the same methods on an instance.
use Nolikein\ArrayMapping\MagicArrayFacade;
$array = [
'data1' => 'value1',
'data2' => [
'data3' => 'value2',
'data4' => 'value3',
],
12 => 42,
];
// Read a value: 'value3'. A path that leads nowhere gives null.
$value = MagicArrayFacade::get($array, 'data2.data4');
// Check a path: true. Unlike get(), it tells a missing key from a stored null.
$exists = MagicArrayFacade::has($array, 'data2.data4');
// Write a value: a copy of $array where $array['data2']['data5'] is 'value42'.
// The missing levels are created.
$array = MagicArrayFacade::set($array, 'data2.data5', 'value42');
// Remove a value: a copy of $array without $array['data2']['data5'].
// A path that leads nowhere gives the array unchanged.
$array = MagicArrayFacade::forget($array, 'data2.data5');
// Build a new array: ['data2' => ['data5' => 'value42']]
$new = MagicArrayFacade::make('data2.data5', 'value42');
// Another separator
$value = MagicArrayFacade::get($array, 'data2/data4', '/');
Both can refuse paths with more keys than a maximum depth. There is no limit by default (MagicArray::DEFAULT_MAX_DEPTH, null):
use Nolikein\ArrayMapping\MagicArray;
use Nolikein\ArrayMapping\MagicArrayFacade;
$magic = new MagicArray(maxDepth: 32);
// Throws PathTooDeep: the path has 33 keys
$magic->set([], str_repeat('a.', 32) . 'a', 'value');
// The facade reads its limit from a static property, shared by every caller:
// set it once, when the application starts. null removes the limit.
MagicArrayFacade::$maxDepth = 32;
Exceptions
| Exception | Thrown by | When |
|---|---|---|
Nolikein\ArrayMapping\Exceptions\EmptyPath | get(), has(), set(), forget(), make() | The path is an empty string |
Nolikein\ArrayMapping\Exceptions\EmptySeparator | get(), has(), set(), forget(), make() | The separator is an empty string |
Nolikein\ArrayMapping\Exceptions\PathTooDeep | get(), has(), set(), forget(), make(), with a maximum depth | The path has more keys than the maximum depth |
Nolikein\ArrayMapping\Exceptions\InvalidMaxDepth | new MagicArray(), and the five methods of MagicArrayFacade | The maximum depth is lower than 1 |
All extend ArrayMappingInvalidArgumentException, itself an \InvalidArgumentException.
Every exception of the library implements Nolikein\ArrayMapping\Exceptions\ArrayMappingExceptionInterface, so one catch handles any error of the library.
use Nolikein\ArrayMapping\Exceptions\ArrayMappingExceptionInterface;
use Nolikein\ArrayMapping\MagicArrayFacade;
try {
$array = MagicArrayFacade::set($array, $path, $value);
} catch (ArrayMappingExceptionInterface $exception) {
// any error of the library
}
Security
A path decides which key is read or written. When a path or a separator comes from outside your code (a request, a file, a database), validate it first:
- Check it against the keys you expect:
set()writes any key the path names, including keys the array already uses for something else ('user.is_admin'). - Limit its depth: every separator adds a level, and PHP itself may crash (segmentation fault) when it frees an array nested about a million levels deep.
new MagicArray(maxDepth: …)orMagicArrayFacade::$maxDepthrefuses a deeper path withPathTooDeep, before splitting it.
To report a vulnerability, follow the security policy.
Development
Every command runs in the Docker container, never on the host. The default PHP version is 8.4; set PHP_VERSION=8.5 to use another one.
The container runs as the user 1000:1000. If your host user has other ids, write them once in the git-ignored .env (bash does not export UID and GID, so docker compose cannot read them from the shell):
printf 'UID=%s\nGID=%s\n' "$(id -u)" "$(id -g)" > .env
docker compose build
docker compose run --rm php composer install
docker compose run --rm php composer qa
composer qa runs the format check, PHPStan and the Pest tests. Coverage report:
docker compose run --rm -e XDEBUG_MODE=coverage php vendor/bin/pest --coverage
Links
Licence
MIT, see LICENCE.