ecfectus/dotable

A simple dot notation accessible array class and trait.

dev-master 2016-10-08 00:26 UTC

This package is not auto-updated.

Last update: 2024-10-30 20:10:32 UTC


README

Build Status

A simple dot notation accessible array class and trait, implementing DotableInterface, ArrayAccess, IteratorAggregate, Countable, JsonSerializable.

This class can turn normal arrays into super arrays with dot notation, you can use the helper methods set, get, has, forget, prepend, append, merge, and count to modify the underlying array. Or You can access it just like any other array using foreach, isset, ``unset, count`, and `$array['dot.notation.key']`.

Usage

$d = new Dotable([]);

//these are both the same.
$d['one'] = ['two' => ['three' => 1], 'four' => ['val']];
===
$d->set('one', ['two' => ['three' => 1], 'four' => ['val']);

//and these
$var = $d['one.two.three'];
===
$var = $d->get('one.two.three', 1);//optional default value

//and these
$d['one.two.three'] = 2;
===
$d->set('one.two.three', 2);

//existence is the same
isset($d['one.two.three']);//true
isset($d['one.two.five']);//false
===
$d->has('one.two.three');//true
$d->has('one.two.five');//false

//and removal
unset($d['one.two.three']);
===
$d->forget('one.two.three');

//prepend
$v = $d['one.four'];
array_unshift($v, 'val2');
$d['one.four'] = $v
===
$d->prepend('one.four', 'val2');

//append
$v = $d['one.four'];
$v[] = 'val2';
$d['one.four'] = $v
===
$d->append('one.four', 'val2');

//merge
// merging is a little different, array_merge_recursive has some weird side effects for multi dimensional arrays with different value types,
// by default we use the dotable merge stratergy which overcomes this with distinct values,
// but if your expecting exactly what array_merge_recursive does, simply pass false as the third argument.

$res = array_merge_recursive($d['one'], ['two' => ['three' => 2]);
===
$d->merge('one', ['two' => ['three' => 2], true|false);

//count
count($d);
===
$d->count();

//get a plain array
$d->toArray();

//loop over the array
foreach($d as $key => $value){}
===
foreach($d->toArray() as $key => $value){}

Using the trait

The dotable class simply uses the trait provided and implements all the interfaces: DotableInterface, ArrayAccess, IteratorAggregate, Countable, JsonSerializable.

The full functionality can be used in a different class not extended from the Dotable class.

class MyClass extends Dotable implements DotableInterface, ArrayAccess, IteratorAggregate, Countable, JsonSerializable
{}

//or

class MyClass implements DotableInterface, ArrayAccess, IteratorAggregate, Countable, JsonSerializable
{
    use DotableTrait;

    public function __construct(array $items = [])
    {
        $this->set('', $items);//set the items using the traits method on the root index.
    }
}

Now MyClass has all the features of dotable without having to extends it. Bear in mind if you provide the same methods in your class that overwrite the trait methods (including the implemented interface methods) you will loose functionality. To ensure its maintained you will need to rewrite the method signatures when using the trait as explained in the php docs: http://php.net/manual/en/language.oop5.traits.php #example 6.