gnugat/traversal

Service for for hash map (assoc array) traversal (fork of igorw/get-in).

Traversal

A service for hash map (assoc array) traversal., _(*1)

When dealing with nested associative structures, traversing them can become quite a pain. Mostly because of the amount of isset checking that is necessary., _(*2)

For example, to access a nested key ['foo']['bar']['baz'], you must do something like this:, _(*3)

$baz = (isset($data['foo']['bar']['baz'])) ? $data['foo']['bar']['baz'] : null;

Enough already! Traversal provides a better way:, _(*4)

$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., _(*5)

, _(*6)

Installation

Use Composer to install Traversal in your projects:, _(*7)

composer require gnugat/traversal:~2.0

Usage

Make the functions available by requiring Composer's autoloader:, _(*8)

<?php

require __DIR__.'/vendor/autoload.php';

Get in

Retrieve value from a nested structure using a list of keys:, _(*9)

$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:, _(*10)

$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:, _(*11)

$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:, _(*12)

$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:, _(*13)

$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:, _(*14)

$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:, _(*15)

$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., _(*16)