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.