README

This is a collection of array wrappers.

Composite Key Array
XPath Key Array
Dotted Key Array
One-off Array
Write-once Array

Composite Key Array

Sometimes it is useful to have ability to access nested value with one, array like, key (some questions were asked about this: on quora, on stackoverflow).

CompositeKeyArray class gives you the ability to do all basic array operations using array-like (nested) key. It implemets ArrayAccess interface:

1. offsetExists:

You can check nested keys for existance.

    $array = new CompositeKeyArray([
        'foo' => [
            'bar' => 'baz'
        ]
    ]);

    var_dump(isset($array[['foo', 'bar']])); // => bool(true)
    var_dump(isset($array[['foo', 'quux']])); // => bool(false)

2. offsetGet:

You can get value by nested key. If nested key is not set the UndefinedOffsetException will be thrown.

    $array = new CompositeKeyArray([
        'foo' => [
            'bar' => 'baz'
        ]
    ]);

    var_dump($array[['foo', 'bar']]); // => string(3) "baz"
    var_dump($array[['foo', 'quux']]); // => PHP Fatal error:  Uncaught UndefinedOffsetException: Undefined offset quux.

3. offsetSet:

You can set value for nested key.

    $array = new CompositeKeyArray();

    $array[['foo', 'bar']] = 'baz';

    var_dump($array[['foo', 'bar']]); // => string(3) "baz"

There is one pitfall. When you try to do $array['foo']['bar'] = 'baz' you get Indirect modification of overloaded element of CompositeKeyArray has no effect. The reason was explained here. So in order to achive the desired result you have to do the following:

    $array = new CompositeKeyArray([
        'foo' => []
    ]);

    $array['foo']['bar'] = 'baz'; // => PHP Notice:  Indirect modification of overloaded element of CompositeKeyArray has no effect

    var_dump($array['foo']); // => array(0) {}

    $array[['foo', 'bar']] = 'baz';

    var_dump($array['foo']); // => array(1) {["bar"] => string(3) "baz"}

But there is another edge case left: when you need to append element at the end of an array.

    $array = new CompositeKeyArray([
        'foo' => []
    ]);

    $array[[[]]] = 'bar';
    $array[['foo', []]] = 'baz';
    $array[['foo', []]] = 'qux';

    var_dump($array->toArray());

    // => array(2) {
    //    ["foo"]=>
    //        array(2) {
    //            [0]=>
    //                string(3) "baz"
    //            [1]=>
    //                string(3) "qux"
    //        }
    //    [0]=>
    //        string(3) "bar"
    // }

4. offsetUnset:

You can unset nested key.

    $array = new CompositeKeyArray([
        'foo' => [
            'bar' => 'baz'
        ]
    ]);

    unset($array[['foo', 'bar']]);

    var_dump($array['foo']); // => array(0) {}

After nested manipulations you might want to get back the real array. This can be done by calling $array->toArray().

XPath Key Array

This is not a real xpath! This class instead of array-like key users string of keys delimited with /.

    $array = new XPathKeyArray([
        'foo' => [
            'bar' => 'baz'
        ]
    ]);

    var_dump($array['foo/bar']); // => string(3) "baz"

This one was inspired by an old article.

Compared to CompositeKeyArray, XPathKeyArray has some limitations:

You cannot use keys with / in them.
You cannot use null as key.

Dotted Key Array

This class instead of array-like key users string of keys delimited with ..

    $array = new DottedKeyArray([
        'foo' => [
            'bar' => 'baz'
        ]
    ]);

    var_dump($array['foo.bar']); // => string(3) "baz"

Compared to CompositeKeyArray, DottedKeyArray has some limitations:

You cannot use keys with . in them.
You cannot use null as key.

One-off Array

Sometimes you want to get value from an array by key and unset this key after that. The OneOffArray class helps you with this.

Again this class can be used in combination with CompositeKeyArray or its descendents: XPathKeyArray or DottedKeyArray. Actually, it can be used in combination with any object that implemets ArrayAccess.

Write-once Array

If you want to be sure that each offset in your array would be written only once you can use WriteOnceArray. If you try to set one particular offset more than one time IllegalOffsetException will be thrown:

$array = new WriteOnceArray();

$array['foo'] = 'bar'; // => OK
$array['foo'] = 'baz'; // => throws `IllegalOffsetException`

Because offsetExists method is used in order to ensure write-once behaviour, offsetUnset method call is illegal:

$array = new WriteOnceArray([
    'foo' => 'bar',
]);

unset($array['foo']); // => throws `IllegalOffsetUnsetMethodCallException`

thorough-php / arrays

Maintainers

Details