A light-weight interface for working fluently with array's.

ArrayObject provides a wrapper around PHP's built-in arrays which includes methods for filtering, and retrieving items, and conveniently treats individual items and collections as the same object.

This is especially useful for working with JSON responses from API requests.

composer require rexsoftware/array-object

• PHP 7.0 (or greater)
• bkvfoundry/utility-belt

<?php // Initialise from an Array $obj = ArrayObject::fromArray([...]); // Initialise from a JSON encoded string $obj = ArrayObject::fromJson($str); 

The examples below are based on the follow input data.

{ "books": [ { "id": 1, "title": "1984", "author": "George Orwell" }, { "id": 2, "title": "Pride and Prejudice", "author": "Jane Austen" } ] }

$obj->books; // Instance of ArrayObject $obj->books->pluck('author'); // array [ 'George Orwell', 'Jane Austen' ] $obj->books->count(); // 2 $obj->books->isCollection(); // true $obj->books[0]; // Instance of ArrayObject $obj->books[0]->isCollection(); // false $obj->books[0]->id; // 1

Note: All of the methods gracefully handle treating an individual item as an array.

The get() method allows you to fetch the value of a property, and receive a default if the value does not exist. It also supports depth which is indicated with a .:

$obj->get('books.0.title'); // "1984" $obj->get('books.1.title'); // "Pride and Prejudice" $obj->get('books.0.missing', 'Defult value'); // "Default value"

You can also fetch the properties using object property syntax (we overload __get() to achieve this):

$obj->books[0]->title; // "1984" $obj->books[1]->title; // "Pride and Prejudice" $obj->books[0]->missing; // throws InvalidPropertyException

The set() method allows you to set a property using dot notation. It will automatically create the underlying array structure:

$obj->set('some.deep.key', $value); // Set nested property $obj->set('some_key', $anotherArrayObject); // Pass an ArrayObjectInterface as value

Similar to get() but will throw a InvalidPropertyException when the key is not found.

To test for the existence of an element, use the has() method:

$obj->has('books'); // true $obj->has('books.0.id'); // true $obj->has('books.1.name'); // false $obj->has('books.5'); // false

Looping over a collection can be acheived by passing a callback to each():

$obj->books->each(function($obj) { echo "ID: {$obj->id}, title: {$obj->title}\n"; }); foreach ($obj->books as $obj) { echo "ID: {$obj->id}, title: {$obj->title}\n"; }

If you have a single item, it still works.

Since ArrayObject implements an Iterator interface, you can simply foreach() over the object. This works for single items or collections.

foreach ($obj->books as $obj) { echo "ID: {$obj->id}, title: {$obj->title}\n"; }

You can call count off any node:

$obj->count(); // 1 $obj->books->count(); // 2 $obj->books[0]->count();

$obj->hasItems(); // boolean indicating if count() > 0

Apply either a callback, or an array of where conditions, and only return items that match.

Using a callback, each item is an instance of ArrayObject:

// Only return items with a title $filteredBooksWithTitle = $obj->books->filter(function($item) { return $item->has('title'); });

You can also specify a list of conditions using an array:

// Only return items with a title $filteredBooksWithTitle = $obj->books->filter(["title" => '1984']);

Getting the original array is available via the toArray() method:

$obj->books[0]->toArray(); // [ 'id' => 1, 'title' => '1984', 'author' => 'George Orwell' ] $obj->get(1)->toArray(); // [ 'id' => 2, 'title' => 'Pride and Prejudice', 'author' => 'Jane Austen' ] $obj->books->toArray(); // [ [ 'id' => 1, 'title' => '1984', 'author' => 'George Orwell' ], [ 'id' => 2, 'title' => 'Pride and Prejudice', 'author' => 'Jane Austen' ] ] $obj->toArray(); // [ 'books' => [ [ 'id' => 1, 'title' => '1984', 'author' => 'George Orwell' ], [ 'id' => 2, 'title' => 'Pride and Prejudice', 'author' => 'Jane Austen' ] ] ]

Returns a json encoded string of the underlying array:

$json = $obj->toJson(); // '{ "some_prop": [ "val1", "val2" ] }`

Determines if the underlying array is a collection.

$obj->books->isCollection(); // true $obj->get('books.0')->isCollection(); // false $obj->isCollection(); // false

Adds one or more items to the start of the collection. If the array is not currently a collection it will be converted to a collection with one element.

$obj->unshift('value') ->unshift('value1', 'value2', 'value3'); 

Note: you can pass ArrayObject's as values.

Pulls the first item off the collection.
If the array is not currently a collection it will be converted to a collection with one element.

$item = $obj->shift(); // ArrayObject

Adds one or more items to the end of the collection. If the array is not currently a collection it will be converted to a collection with one element.

$obj->push('value') ->push('value1', 'value2', 'value3'); 

Note: you can pass ArrayObject's as values.

Pulls the last item off the collection.
If the array is not currently a collection it will be converted to a collection with one element.

$item = $obj->pop(); // ArrayObject