README

Proper object traversal

Belt.Matter is an utility library that makes working with JSON objects a bit (actually a lot) more pleasant. It converts JSON strings, objects or arrays to a proper tree structure that can be traversed without warnings or errors.

Installation

Via Composer.

$ composer require belt/matter

Usage

When we use JSON in PHP, we usually have to use the properties of the JSON object. This is really nice and all, but it doesn't work when a property does not exist.

$object = json_decode('{"foo":"bar","bar":[1, 2, 3, 4]","baz":"lorem ipsum"}');
$object->foo;       // "bar"
$object->something; // BOOM!

Well, that's not really nice, is it? We have to put guards around everytime we want to use a property.

This is where Matter comes in handy!

// Before
$object = json_decode('{"foo":"bar"}');
$object->foo;       // "bar"
$object->something; // BOOM!

// After
use Belt\Matter;

$object = Matter::fromJson('{"foo":"bar"}');
$object->get('foo')->get();         // "bar"
$object->get('something')->get();   // null

What Matter does for you, is convert a given JSON string or value into a tree structure. This allows you to request nodes from the tree without being afraid of errors/warnings that are thrown.

You can always access any value in the JSON object.

$object = Matter::fromJson('{"foo":[1, 2, 3, 4],"bar":"lorem"}');
$object->get('foo')->get(0)->get(); // 1
$object->get('foo')->get(4)->get(); // null
$object->get('bar')->get();         // "lorem"

$object = Matter::fromJson('[{"name":"Alice"},{"name":"Bob"}]');
$object->get(0)->get('name')->get(); // "Alice"
$object->get(1)->get('name')->get(); // "Bob"
$object->get(2)->get('name')->get(); // null

Each Matter node also implements ArrayAccess and Iterator, which allows you to work even faster!

$users = Matter::fromJson('[{"name":"Alice"},{"name":"Bob"}]');
$users[0]['name']->get(); // "Alice"
$users[1]['name']->get(); // "Bob"
$users[2]['name']->get(); // null

foreach ($users as $user) {
    $name = $user['name']->get();
}

Additionally, you can also safely access properties of the object without having to use get to retrieve the property node.

$object = Matter::fromJson('{"foo":{"bar":{"baz":42}}}');
$object->foo->bar->baz->get(); // 42
$object->baz->bar->foo->get(); // null

Contributing

Please see CONTRIBUTING.

License

Please see LICENSE.