gnugat / traversal
Service for for hash map (assoc array) traversal (fork of igorw/get-in).
Requires
- php: >=5.3
Requires (Dev)
- phpunit/phpunit: >=3.7,<5.0
This package is auto-updated.
Last update: 2022-02-01 12:41:36 UTC
README
A service for hash map (assoc array) traversal.
When dealing with nested associative structures, traversing them can become
quite a pain. Mostly because of the amount of isset
checking that is
necessary.
For example, to access a nested key ['foo']['bar']['baz']
, you must do
something like this:
$baz = (isset($data['foo']['bar']['baz'])) ? $data['foo']['bar']['baz'] : null;
Enough already! Traversal
provides a better way:
$baz = Gnugat\Traversal\get_in($data, array('foo', 'bar', 'baz'));
Note:
Traversal
is a fork of Igor's get-in. which provides support for PHP 5.3.
Installation
Use Composer to install Traversal in your projects:
composer require gnugat/traversal:~2.0
Usage
Make the functions available by requiring Composer's autoloader:
<?php require __DIR__.'/vendor/autoload.php';
Get in
Retrieve value from a nested structure using a list of keys:
$users = array( array('name' => 'Igor Wiedler'), array('name' => 'Jane Doe'), array('name' => 'Acme Inc'), ); $name = Gnugat\Traversal\get_in($users, array(1, 'name')); //= 'Jane Doe'
Non existent keys return null:
$data = array('foo' => 'bar']; $baz = Gnugat\Traversal\get_in($data, array('baz')); //= null
You can provide a default value that will be used instead of null:
$data = array('foo' => 'bar'); $baz = Gnugat\Traversal\get_in($data, array('baz'), 'qux'); //= 'qux'
Update in
Apply a function to the value at a particular location in a nested structure:
$data = array('foo' => array('answer' => 42)); $inc = function ($x) { return $x + 1; }; $new = Gnugat\Traversal\update_in($data, array('foo', 'answer'), $inc); //= array('foo' => array('answer' => 43))
You can variadically provide additional arguments for the function:
$data = array('foo' => 'bar'); $concat = function (/* $args... */) { return implode('', func_get_args()); }; $new = Gnugat\Traversal\update_in($data, array('foo'), $concat, ' is the ', 'best'); //= array('foo' => 'bar is the best')
Assoc in
Set a value at a particular location:
$data = array('foo' => 'bar'); $new = Gnugat\Traversal\assoc_in($data, array('foo'), 'baz'); //= array('foo' => 'baz')
It will also set the value if it does not exist yet:
$data = []; $new = Gnugat\Traversal\assoc_in($data, array('foo', 'bar'), 'baz'); //= array('foo' => array('bar' => 'baz'))
Inspiration
The naming and implementation is inspired by the get-in
, update-in
and
assoc-in
functions from clojure.