README

The wrapper for all PHP built-in array functions and easy, object-oriented array manipulation library. In short: Arrays on steroids.

ArrayImitator

This is the main class of this library. Each method, which associated with the corresponding native PHP function, keep its behavior. In other words: methods could creates a new array (leaving the original array unchanged), operates on the same array (returns the array itself and DOES NOT create a new instance) or return some result.

NOTE: If method creates a new array but you don't need the first array you operate on, you can override it manually:

use Arrayzy\ArrayImitator as A;

$a = A::create(['a', 'b', 'c']);
$a = $a->reverse(); // override instance you operates on, because $a !== $a->reverse()

NOTE: If method operates on the same array but you need to keep the first array you operate on as unchanged, you can clone it manually first:

use Arrayzy\ArrayImitator as A;

$a = A::create(['a', 'b', 'c']);
$b = clone $a;
$b->shuffle(); // keeps $a unchanged, because $a !== $b

Requirements
Installation
Creation
Usage
- Chaining
Public method list
- add
- chunk
- clear
- combine
- contains
- containsKey
- count
- create
- createClone
- createFromJson
- createFromObject
- createFromString
- createWithRange
- current
- customSort
- customSortKeys
- debug
- diff
- each
- end
- except
- exists
- export
- filter
- find
- first
- flip
- getIterator
- getKeys
- getRandom
- getRandomKey
- getRandomKeys
- getRandomValues
- getValues
- indexOf
- intersect
- intersectAssoc
- intersectKey
- isAssoc
- isEmpty
- isNumeric
- key
- last
- map
- merge
- next
- offsetExists
- offsetGet
- offsetSet
- offsetUnset
- only
- pad
- pop
- previous
- push
- reduce
- reindex
- replace
- reset
- reverse
- search
- shift
- shuffle
- slice
- sort
- sortKeys
- toArray
- toJson
- toReadableString
- toString
- unique
- unshift
- walk
Contribution
Links

Requirements

PHP 5.4 or higher
PHP JSON extension

Installation

The preferred way to install this package is to use Composer:

$ composer require bocharsky-bw/arrayzy

If you don't use Composer - register this package in your autoloader manually or download this library and require the necessary files directly in your scripts:

require_once __DIR__ . '/path/to/library/src/ArrayImitator.php';

Creation

Create a new empty array with the new statement.

use Arrayzy\ArrayImitator;

$a = new ArrayImitator; // Creates a new instance with the "use" statement
// or
$a = new \Arrayzy\ArrayImitator; // Creates a new array by fully qualified namespace

NOTE: Don't forget about namespaces. You can use namespace aliases for simplicity if you want:

use Arrayzy\ArrayImitator as A;

$a = new A; // Creates a new instance using namespace alias

Create a new array with default values, passed it to the constructor as an array:

$a = new A([1, 2, 3]);
// or
$a = new A([1 => 'a', 2 => 'b', 3 => 'c']);

Also, new objects can be created with one of the public static methods prefixed with 'create':

create
createFromJson
createFromObject
createFromString
createWithRange

Usage

You can get access to the values like with the familiar PHP array syntax:

use Arrayzy\ArrayImitator as A;

$a = A::create(['a', 'b', 'c']);

$a[] = 'e';    // or use $a->offsetSet(null, 'e') method
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c', 3 => 'e']

$a[3] = 'd';   // or use $a->offsetSet(3, 'd') method
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c', 3 => 'd']

print $a[1]; // 'b'
// or use the corresponding method
print $a->offsetGet(1); // 'b'

NOTE: The following methods and principles apply to the ArrayImitator class. In the examples provided below the ArrayImitator aliased with A.

Chaining

Methods may be chained for ease of use:

$a = A::create(['a', 'b', 'c']);

$a
    ->offsetSet(null, 'e')
    ->offsetSet(3, 'd')
    ->offsetSet(null, 'e')
    ->shuffle() // or any other method that returns $this
;

$a->toArray(); // [0 => 'c', 1 => 'a', 2 => 'e', 3 => 'd', 4 => 'b']

Converting

Easily convert instance array elements to a simple PHP array, string, readable string or JSON format:

toArray
toJson
toReadableString
toString

Public method list

add

Associated with $a[] = 'new item'.

$a = A::create(['a', 'b', 'c']);
$a->add('d');
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c', 3 => 'd']

chunk

Associated with array_chunk().

$a = A::create(['a', 'b', 'c']);
$a = $a->chunk(2);
$a->toArray(); // [0 => [0 => 'a', 1 => 'b'], 1 => [0 => 'c']]

clear

Associated with $a = [].

$a = A::create(['a', 'b', 'c']);
$a->clear();
$a->toArray(); // []

combine

Associated with array_combine().

$a = A::create([1, 2, 3]);
$a->combine(['a', 'b', 'c']);
$a->toArray(); // [1 => 'a', 2 => 'b', 3 => 'c']

contains

Associated with in_array().

$a = A::create(['a', 'b', 'c']);
$a->contains('c'); // true

containsKey

Associated with array_key_exists().

$a = A::create(['a', 'b', 'c']);
$a->containsKey(2); // true

count

Associated with count().

$a = A::create(['a', 'b', 'c']);
$a->count(); // 3

create

$a = A::create(['a', 'b', 'c']);
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c']

createClone

Creates a shallow copy of the array.

Keep in mind, that in PHP variables contain only references to the object, NOT the object itself:

$a = A::create(['a', 'b', 'c']);
$b = $a; // $a and $b are different variables referencing the same object ($a === $b)

So if you DO NOT want to modify the current array, you need to clone it manually first:

$a = A::create(['a', 'b', 'c']);
$b = clone $a; // $a and $b are different instances ($a !== $b)
// or do it with built-in method
$b = $a->createClone(); // $a !== $b

createFromJson

Associated with json_decode().

Creates an array by parsing a JSON string:

$a = A::createFromJson('{"a": 1, "b": 2, "c": 3}');
$a->toArray(); // ['a' => 1, 'b' => 2, 'c' => 3]

createFromObject

Creates an instance array from any object that implemented \ArrayAccess interface:

$a = A::create(['a', 'b', 'c']);
$b = A::createFromObject($a); // where $a could be any object that implemented \ArrayAccess interface
$b->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c']

createFromString

Associated with explode().

Creates an array from a simple PHP string with specified separator:

$a = A::createFromString('a;b;c', ';');
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c']

createWithRange

Associated with range().

Creates an array of a specified range:

$a = A::createWithRange(2, 6, 2);
$a->toArray(); // [0 => 2, 1 => 4, 2 => 6]

current

Associated with current().

Position of the iterator.

$a = A::create(['a', 'b', 'c']);
$a->current(); // 'a'

customSort

Associated with usort().

$a = A::create(['b', 'a', 'c']);
$a->customSort(function($a, $b) {
    if ($a === $b) {
        return 0;
    }

    return ($a < $b) ? -1 : 1;
});
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c']

customSortKeys

Associated with uksort().

$a = A::create([1 => 'b', 0 => 'a', 2 => 'c']);
$a->customSortKeys(function($a, $b) {
    if ($a === $b) {
        return 0;
    }

    return ($a < $b) ? -1 : 1;
});
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c']

debug

Associated with print_r().

$a = A::create(['a', 'b', 'c']);
$a->debug(); // Array ( [0] => a [1] => b [2] => c )

diff

Associated with array_diff().

$a = A::create(['a', 'b', 'c']);
$a = $a->diff(['c', 'd']);
$a->toArray(); // [0 => 'a', 1 => 'b']

each

Associated with each().

$a = A::create(['a', 'b', 'c']);
$a->each(); // [0 => 0, 'key' => 0, 1 => 'a', 'value' => 'a']

end

Associated with end().

$a = A::create(['a', 'b', 'c']);
$a->end(); // 'c'

except

Based on array_diff_key().

Chunk of an array without given keys.

$a = A::create(['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4, 'e' => 5]);
$a = $a->except(['b', 'e']);
$a->toArray(); // ['a' => 1, 'c' => 3, 'd' => 4]

exists

A custom contains method where you can supply your own custom logic in any callable function.

$a = A::create(['a', 'b', 'c']);

$a->exists(function($key, $value) {
   return 1 === $key and 'b' === $value;
}); // true

export

Associated with var_export().

$a = A::create(['a', 'b', 'c']);
$a->export(); // array ( 0 => 'a', 1 => 'b', 2 => 'c', )

filter

Associated with array_filter().

$a = A::create(['a', 'z', 'b', 'z']);
$a = $a->filter(function($value) {
    return 'z' !== $value; // exclude 'z' value from array
});
$a->toArray(); // [0 => 'a', 2 => 'b']

find

A custom find method where you can supply your own custom logic in any callable function.

$a = A::create(['a', 'b', 'c']);
$a->find(function($value, $key) {
    return 'b' == $value && 0 < $key;
}); // 'b'

first

Alias of reset.

$a = A::create(['a', 'b', 'c']);
$a->first(); // 'a'

flip

Associated with array_flip().

$a = A::create(['a', 'b', 'c']);
$a = $a->flip();
$a->toArray(); // ['a' => 0, 'b' => 1, 'c' => 2]

getIterator

Creates an external Iterator. Check the iteratorAggregate documentation for more information.

getKeys

Associated with array_keys().

$a = A::create(['a' => 1, 'b' => 2, 'c' => 3]);
$a->getKeys(); // [0 => 'a', 1 => 'b', 2 => 'c']

getRandom

Associated with array_rand().

$a = A::create(['a', 'b', 'c', 'd']);
$a->getRandom(); // 'c'

getRandomKey

Associated with array_rand().

$a = A::create(['a', 'b', 'c', 'd']);
$a->getRandomKey(); // 2

getRandomKeys

Associated with array_rand().

$a = A::create(['a', 'b', 'c', 'd']);
$a->getRandomKeys(2); // [0, 2]

getRandomValues

Associated with array_rand().

$a = A::create(['a', 'b', 'c', 'd']);
$a->getRandomValues(2); // ['b', 'd']

getValues

Associated with array_values().

$a = A::create([1 => 'a', 2 => 'b', 3 => 'c']);
$a->getValues(); // [0 => 'a', 1 => 'b', 2 => 'c']

indexOf

Alias of search.

$a = A::create(['a', 'b', 'c']);
$a->indexOf('b'); // 1

intersect

Associated with array_intersect().

$a = A::create(['a', 'b', 'c']);
$a = $a->intersect(['b', 'c']);
$a->toArray(); // [1 => 'b', 2 => 'c']

intersectAssoc

Associated with array_intersect_assoc().

$a = A::create(['one' => 'a', 'two' => 'b', 'three' => 'c']);
$a = $a->intersectAssoc(['two' => 'b', 'four' => 'c']);
$a->toArray(); // ['two' => 'b']

intersectKey

Associated with array_intersect_key().

$a = A::create(['one' => 'a', 'two' => 'b', 'three' => 'c']);
$a = $a->intersectKey(['two' => 'd', 'three' => 'e']);
$a->toArray(); // ['two' => 'b', 'three' => 'c']

isAssoc

Check whether all array keys are associative.

$a = A::create(['key' => 'value']);
$a->isAssoc(); // true

isEmpty

Check whether array is empty.

$a = A::create([]);
$a->isEmpty(); // true

isNumeric

Check whether all array keys are numeric.

$a = A::create(['a', 'b', 'c']);
$a->isNumeric(); // true

key

Associated with key().

$a = A::create(['a', 'b', 'c']);
$a->current(); // 'a'
$a->key();     // 0
$a->next();    // 'b'
$a->key();     // 1

last

Alias of end.

$a = A::create(['a', 'b', 'c']);
$a->last(); // 'c'

map

Associated with array_map().

$a = A::create(['a', 'b', 'c']);
$a = $a->map(function($value) {
    return $value . $value;
});
$a->toArray(); // [0 => 'aa', 1 => 'bb', 2 => 'cc']

merge

Associated with array_merge() / array_merge_recursive().

// indexed array behavior
$a = A::create(['a', 'b', 'c']); // create indexed array
$a = $a->merge(['c', 'd']);
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c', 3 => 'c', 4 => 'd']

// assoc array behavior
$b = A::create(['a' => 1, 'b' => 2, 'c' => 99]); // create assoc array
$b = $b->merge(['c' => 3, 'd' => 4]);
$b->toArray(); // ['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4]

Associated with next().

$a = A::create(['a', 'b', 'c']);
$a->next(); // 'b'
$a->next(); // 'c'

offsetExists

Implemented for ArrayAccess interface.

$a = A::create(['a', 'b', 'c']);
$a->offsetExists(2); // true (or use isset($a[2]))
$a->offsetExists(3); // false (or use isset($a[3]))

offsetGet

Implemented for ArrayAccess interface.

$a = A::create(['a', 'b', 'c']);
$a->offsetGet(1); // 'b' (or use $a[1])

offsetSet

Implemented for ArrayAccess interface.

$a = A::create(['a', 'b', 'd']);
// add a new value
$a->offsetSet(null, 'd'); // or use $a[] = 'd';
$a->toArray();            // [0 => 'a', 1 => 'b', 2 => 'd', 3=> 'd']
// replace an existing value by key
$a->offsetSet(2, 'c');    // or use $a[2] = 'c';
$a->toArray();            // [0 => 'a', 1 => 'b', 2 => 'c', 3=> 'd']

offsetUnset

Implemented for ArrayAccess interface.

$a = A::create(['a', 'b', 'c']);
$a->offsetUnset(1); // or use unset($a[1]);
$a->toArray();      // [0 => 'a', 2 => 'c']

only

Based on array_intersect_key().

Chunk of an array with only given keys.

$a = A::create(['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4, 'e' => 5]);
$a = $a->only(['b', 'e']);
$a->toArray(); // ['b' => 2, 'e' => 5]

pad

Associated with array_pad().

$a = A::create(['a', 'b', 'c']);
$a = $a->pad(5, 'z');
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c', 3 => 'z', 4 => 'z']

pop

Associated with array_pop().

$a = A::create(['a', 'b', 'c']);
$a->pop();     // 'c'
$a->toArray(); // [0 => 'a', 1 => 'b']

Associated with prev().

$a = A::create(['a', 'b', 'c']);
$a->next();     // 'b'
$a->next();     // 'c'
$a->previous(); // 'b'

push

Associated with array_push().

$a = A::create(['a', 'b']);
$a->push('c', 'd');
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c', 3 => 'd']

The push() method allows multiple arguments.

reduce

Associated with array_reduce().

$a = A::create(['a', 'b', 'c']);
$a = $a->reduce(function($result, $item) {
    return $result . $item;
}); // 'abc'

reindex

Based on array_values().

$a = A::create([2 => 'a', 1 => 'b', 3 => 'c']);
$a = $a->reindex();
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c']

replace

Associated with array_replace() / array_replace_recursive().

$a = A::create(['a', 'd', 'e']);
$a = $a->replace([1 => 'b', 2 => 'c']);
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c']

reset

Associated with reset().

$a = A::create(['a', 'b', 'c']);
$a->reset(); // 'a'

reverse

Associated with array_reverse().

$a = A::create(['a', 'b', 'c']);
$a = $a->reverse();
$a->toArray(); // [0 => 'c', 1 => 'b', 2 => 'a']

search

Associated with array_search().

$a = A::create(['a', 'b', 'c']);
$a->search('b'); // 1

shift

Associated with array_shift().

$a = A::create(['a', 'b', 'c']);
$a->shift();
$a->toArray(); // [0 => 'b', 1 => 'c']

shuffle

Associated with shuffle().

$a = A::create(['a', 'b', 'c']);
$a->shuffle();
$a->toArray(); // [0 => 'c', 1 => 'a', 2 => 'b']

slice

Associated with array_slice().

$a = A::create(['a', 'b', 'c', 'd']);
$a = $a->slice(1, 2);
$a->toArray(); // [0 => 'b', 1 => 'c']

sort

Associated with arsort() / sort() / asort() / rsort().

$a = A::create(['b', 'a', 'd', 'c']);
$a->sort(SORT_DESC);
$a->toArray(); // [0 => 'd', 1 => 'c', 2 => 'b', 3 => 'a']

sortKeys

Associated with ksort() / krsort().

$a = A::create([3 => 'a', 1 => 'b', 2 => 'c', 0 => 'd']);
$a->sortKeys(SORT_ASC);
$a->toArray(); // [0 => 'd', 1 => 'b', 2 => 'c', 3 => 'a']

toArray

Convert the array to a simple PHP array type:

$a = A::create(['a', 'b', 'c']);
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c']

toJson

Associated with json_encode().

Creates a JSON string from the array:

$a = A::create(['a' => 1, 'b' => 2, 'c' => 3]);
$a->toJson(); // { "a": 1, "b": 2, "c": 3 }

toReadableString

Based on implode().

Converts instance array to a readable PHP string:

$a = A::create(['a', 'b', 'c']);
$a->toReadableString(', ', ' and '); // 'a, b and c'

toString

Associated with implode().

Converts instance array to a simple PHP string:

$a = A::create(['a', 'b', 'c']);
$a->toString(', '); // 'a, b, c'

unique

Associated with array_unique().

$a = A::create(['a', 'b', 'b', 'c']);
$a = $a->unique();
$a->toArray(); // [0 => 'a', 1 => 'b', 3 => 'c']

unshift

Associated with array_unshift().

$a = A::create(['a', 'b']);
$a->unshift('y', 'z');
$a->toArray(); // [0 => 'y', 1 => 'z', 2 => 'a', 3 => 'b']

Method unshift() allow multiple arguments.

walk

Associated with array_walk() / array_walk_recursive().

$a = A::create(['a', 'b', 'c']);
$a->walk(function(&$value, $key) {
    $key++; // the $key variable passed by value, (original value will not modified)
    $value = $value . $key; // the $value variable passed by reference (modifies original value)
});
$a->toArray(); // [0 => 'a1', 1 => 'b2', 2 => 'c3']

Contribution

Feel free to submit an Issue or create a Pull Request if you find a bug or just want to propose an improvement suggestion.

In order to propose a new feature the best way is to submit an Issue and discuss it first.

Links

Arrayzy was inspired by Doctrine ArrayCollection class and Stringy library.

Look at the Stringy if you are looking for a PHP string manipulation library in an OOP way.

Move UP

bocharsky-bw / arrayzy

Maintainers

Details

README

ArrayImitator

Contents

Requirements

Installation

Creation

Usage

Chaining

Converting

Debugging

Public method list

add

chunk

clear

combine

contains

containsKey

count

create

createClone

createFromJson

createFromObject

createFromString

createWithRange

current

customSort

customSortKeys

debug

diff

each

end

except

exists

export

filter

find

first

flip

getIterator

getKeys

getRandom

getRandomKey

getRandomKeys

getRandomValues

getValues

indexOf

intersect

intersectAssoc

intersectKey

isAssoc

isEmpty

isNumeric

key

last

map

merge

next

offsetExists

offsetGet

offsetSet

offsetUnset

only

pad

pop

previous

push

reduce

reindex

replace

reset

reverse

search

shift

shuffle

slice

sort

sortKeys