Search by

nolikein / array-mapping

Nolikein

Read, write and build nested arrays with a path such as "user.address.city".

4.0.0 2026-11-09 23:41 UTC

This package is auto-updated.

Last update: 2026-11-11 21:33:25 UTC


README

PHP Packagist version Downloads License Pipeline Coverage

Logo

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

ExceptionThrown byWhen
Nolikein\ArrayMapping\Exceptions\EmptyPathget(), has(), set(), forget(), make()The path is an empty string
Nolikein\ArrayMapping\Exceptions\EmptySeparatorget(), has(), set(), forget(), make()The separator is an empty string
Nolikein\ArrayMapping\Exceptions\PathTooDeepget(), has(), set(), forget(), make(), with a maximum depthThe path has more keys than the maximum depth
Nolikein\ArrayMapping\Exceptions\InvalidMaxDepthnew MagicArray(), and the five methods of MagicArrayFacadeThe 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: …) or MagicArrayFacade::$maxDepth refuses a deeper path with PathTooDeep, 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.