Arrayzy
The wrapper for all PHP built-in array functions and easy, object-oriented array
manipulation library. In short: Arrays on steroids., (*1)
, (*2)
, (*3)
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., (*4)
NOTE: If method creates a new array but you don't need the first array
you operate on, you can override it manually:, (*5)
``` php
use Arrayzy\ArrayImitator as A;, (*6)
$a = A::create(['a', 'b', 'c']);
$a = $a->reverse(); // override instance you operates on, because $a !== $a->reverse(), (*7)
> **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:
``` php
use Arrayzy\ArrayImitator as A;
$a = A::create(['a', 'b', 'c']);
$b = clone $a;
$b->shuffle(); // keeps $a unchanged, because $a !== $b
Contents
Requirements
- PHP
5.4 or higher
- PHP
JSON extension
Installation
The preferred way to install this package is to use Composer:, (*8)
``` bash
$ composer require bocharsky-bw/arrayzy, (*9)
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:
``` php
require_once __DIR__ . '/path/to/library/src/ArrayImitator.php';
Creation
Create a new empty array with the new statement., (*10)
``` php
use Arrayzy\ArrayImitator;, (*11)
$a = new ArrayImitator; // Creates a new instance with the "use" statement
// or
$a = new \Arrayzy\ArrayImitator; // Creates a new array by fully qualified namespace, (*12)
> **NOTE:** Don't forget about namespaces. You can use [namespace aliases][2]
for simplicity if you want:
```php
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:, (*13)
``` php
$a = new A([1, 2, 3]);
// or
$a = new A([1 => 'a', 2 => 'b', 3 => 'c']);, (*14)
Also, new objects can be created with one of the public static methods
prefixed with 'create':
* [create](#create)
* [createFromJson](#createfromjson)
* [createFromObject](#createfromobject)
* [createFromString](#createfromstring)
* [createWithRange](#createwithrange)
## Usage
You can get access to the values like with the familiar PHP array syntax:
``` php
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., (*15)
Chaining
Methods may be chained for ease of use:, (*16)
``` php
$a = A::create(['a', 'b', 'c']);, (*17)
$a
->offsetSet(null, 'e')
->offsetSet(3, 'd')
->offsetSet(null, 'e')
->shuffle() // or any other method that returns $this
;, (*18)
$a->toArray(); // [0 => 'c', 1 => 'a', 2 => 'e', 3 => 'd', 4 => 'b'], (*19)
### Converting
Easily convert instance array elements to a simple PHP `array`, `string`,
readable `string` or JSON format:
* [toArray](#toarray)
* [toJson](#tojson)
* [toReadableString](#toreadablestring)
* [toString](#tostring)
### Debugging
* [debug](#debug)
* [export](#export)
## Public method list
### add
> Associated with `$a[] = 'new item'`.
``` php
$a = A::create(['a', 'b', 'c']);
$a->add('d');
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c', 3 => 'd']
chunk
Associated with array_chunk()., (*20)
``` php
$a = A::create(['a', 'b', 'c']);
$a = $a->chunk(2);
$a->toArray(); // [0 => [0 => 'a', 1 => 'b'], 1 => [0 => 'c']], (*21)
### clear
> Associated with `$a = []`.
``` php
$a = A::create(['a', 'b', 'c']);
$a->clear();
$a->toArray(); // []
combine
Associated with array_combine()., (*22)
``` php
$a = A::create([1, 2, 3]);
$a->combine(['a', 'b', 'c']);
$a->toArray(); // [1 => 'a', 2 => 'b', 3 => 'c'], (*23)
### contains
> Associated with [in_array()](https://secure.php.net/manual/en/function.in-array.php).
``` php
$a = A::create(['a', 'b', 'c']);
$a->contains('c'); // true
containsKey
Associated with array_key_exists()., (*24)
``` php
$a = A::create(['a', 'b', 'c']);
$a->containsKey(2); // true, (*25)
### count
> Associated with [count()](https://secure.php.net/manual/en/function.count.php).
``` php
$a = A::create(['a', 'b', 'c']);
$a->count(); // 3
create
``` php
$a = A::create(['a', 'b', 'c']);
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c'], (*26)
### 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:
``` php
$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:, (*27)
``` php
$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, (*28)
### createFromJson
> Associated with [json_decode()](https://secure.php.net/manual/en/function.json-decode.php).
Creates an array by parsing a JSON string:
``` php
$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:, (*29)
``` php
$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'], (*30)
### createFromString
> Associated with [explode()](https://secure.php.net/manual/en/function.explode.php).
Creates an array from a simple PHP `string` with specified separator:
``` php
$a = A::createFromString('a;b;c', ';');
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c']
createWithRange
Associated with range()., (*31)
Creates an array of a specified range:, (*32)
``` php
$a = A::createWithRange(2, 6, 2);
$a->toArray(); // [0 => 2, 1 => 4, 2 => 6], (*33)
### current
> Associated with [current()](https://secure.php.net/manual/en/function.current.php).
Position of the iterator.
``` php
$a = A::create(['a', 'b', 'c']);
$a->current(); // 'a'
customSort
Associated with usort()., (*34)
``` php
$a = A::create(['b', 'a', 'c']);
$a->customSort(function($a, $b) {
if ($a === $b) {
return 0;
}, (*35)
return ($a < $b) ? -1 : 1;
});
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c'], (*36)
### customSortKeys
> Associated with [uksort()](https://secure.php.net/manual/en/function.uksort.php).
``` php
$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()., (*37)
``` php
$a = A::create(['a', 'b', 'c']);
$a->debug(); // Array ( 0 => a 1 => b 2 => c ), (*38)
### diff
> Associated with [array_diff()](https://secure.php.net/manual/en/function.array-diff.php).
``` php
$a = A::create(['a', 'b', 'c']);
$a = $a->diff(['c', 'd']);
$a->toArray(); // [0 => 'a', 1 => 'b']
each
Associated with each()., (*39)
``` php
$a = A::create(['a', 'b', 'c']);
$a->each(); // [0 => 0, 'key' => 0, 1 => 'a', 'value' => 'a'], (*40)
### end
> Associated with [end()](https://secure.php.net/manual/en/function.end.php).
``` php
$a = A::create(['a', 'b', 'c']);
$a->end(); // 'c'
except
Based on array_diff_key()., (*41)
Chunk of an array without given keys., (*42)
``` php
$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], (*43)
### exists
A custom contains method where you can supply your own custom logic in any callable function.
``` php
$a = A::create(['a', 'b', 'c']);
$a->exists(function($key, $value) {
return 1 === $key and 'b' === $value;
}); // true
export
Associated with var_export()., (*44)
``` php
$a = A::create(['a', 'b', 'c']);
$a->export(); // array ( 0 => 'a', 1 => 'b', 2 => 'c', ), (*45)
### filter
> Associated with [array_filter()](https://secure.php.net/manual/en/function.array-filter.php).
``` php
$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., (*46)
``` php
$a = A::create(['a', 'b', 'c']);
$a->find(function($value, $key) {
return 'b' == $value && 0 < $key;
}); // 'b', (*47)
### first
> Alias of [reset](#reset).
``` php
$a = A::create(['a', 'b', 'c']);
$a->first(); // 'a'
flip
Associated with array_flip()., (*48)
``` php
$a = A::create(['a', 'b', 'c']);
$a = $a->flip();
$a->toArray(); // ['a' => 0, 'b' => 1, 'c' => 2], (*49)
### getIterator
Creates an external Iterator. Check the [iteratorAggregate][6] documentation for more information.
### getKeys
> Associated with [array_keys()](https://secure.php.net/manual/en/function.array-keys.php).
``` php
$a = A::create(['a' => 1, 'b' => 2, 'c' => 3]);
$a->getKeys(); // [0 => 'a', 1 => 'b', 2 => 'c']
getRandom
Associated with array_rand()., (*50)
``` php
$a = A::create(['a', 'b', 'c', 'd']);
$a->getRandom(); // 'c', (*51)
### getRandomKey
> Associated with [array_rand()](https://secure.php.net/manual/en/function.array-rand.php).
``` php
$a = A::create(['a', 'b', 'c', 'd']);
$a->getRandomKey(); // 2
getRandomKeys
Associated with array_rand()., (*52)
``` php
$a = A::create(['a', 'b', 'c', 'd']);
$a->getRandomKeys(2); // [0, 2], (*53)
### getRandomValues
> Associated with [array_rand()](https://secure.php.net/manual/en/function.array-rand.php).
``` php
$a = A::create(['a', 'b', 'c', 'd']);
$a->getRandomValues(2); // ['b', 'd']
getValues
Associated with array_values()., (*54)
``` php
$a = A::create([1 => 'a', 2 => 'b', 3 => 'c']);
$a->getValues(); // [0 => 'a', 1 => 'b', 2 => 'c'], (*55)
### indexOf
> Alias of [search](#search).
``` php
$a = A::create(['a', 'b', 'c']);
$a->indexOf('b'); // 1
intersect
Associated with array_intersect()., (*56)
``` php
$a = A::create(['a', 'b', 'c']);
$a = $a->intersect(['b', 'c']);
$a->toArray(); // [1 => 'b', 2 => 'c'], (*57)
### intersectAssoc
> Associated with [array_intersect_assoc()](https://secure.php.net/manual/en/function.array-intersect-assoc.php).
``` php
$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()., (*58)
``` php
$a = A::create(['one' => 'a', 'two' => 'b', 'three' => 'c']);
$a = $a->intersectKey(['two' => 'd', 'three' => 'e']);
$a->toArray(); // ['two' => 'b', 'three' => 'c'], (*59)
### isAssoc
Check whether all array keys are *associative*.
``` php
$a = A::create(['key' => 'value']);
$a->isAssoc(); // true
isEmpty
Check whether array is empty., (*60)
``` php
$a = A::create([]);
$a->isEmpty(); // true, (*61)
### isNumeric
Check whether all array keys are *numeric*.
``` php
$a = A::create(['a', 'b', 'c']);
$a->isNumeric(); // true
key
Associated with key()., (*62)
``` php
$a = A::create(['a', 'b', 'c']);
$a->current(); // 'a'
$a->key(); // 0
$a->next(); // 'b'
$a->key(); // 1, (*63)
### last
> Alias of [end](#end).
``` php
$a = A::create(['a', 'b', 'c']);
$a->last(); // 'c'
map
Associated with array_map()., (*64)
``` php
$a = A::create(['a', 'b', 'c']);
$a = $a->map(function($value) {
return $value . $value;
});
$a->toArray(); // [0 => 'aa', 1 => 'bb', 2 => 'cc'], (*65)
### merge
> Associated with [array_merge()](https://secure.php.net/manual/en/function.array-merge.php) /
[array_merge_recursive()](https://secure.php.net/manual/en/function.array-merge-recursive.php).
``` php
// 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]
next
Associated with next()., (*66)
``` php
$a = A::create(['a', 'b', 'c']);
$a->next(); // 'b'
$a->next(); // 'c', (*67)
### offsetExists
> Implemented for [ArrayAccess](https://secure.php.net/manual/en/arrayaccess.offsetexists.php) interface.
``` php
$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., (*68)
``` php
$a = A::create(['a', 'b', 'c']);
$a->offsetGet(1); // 'b' (or use $a1), (*69)
### offsetSet
> Implemented for [ArrayAccess](https://secure.php.net/manual/en/arrayaccess.offsetset.php) interface.
``` php
$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., (*70)
``` php
$a = A::create(['a', 'b', 'c']);
$a->offsetUnset(1); // or use unset($a1);
$a->toArray(); // [0 => 'a', 2 => 'c'], (*71)
### only
> Based on [array_intersect_key()](https://secure.php.net/manual/en/function.array-intersect-key.php).
Chunk of an array with only given keys.
``` php
$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()., (*72)
``` php
$a = A::create(['a', 'b', 'c']);
$a = $a->pad(5, 'z');
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c', 3 => 'z', 4 => 'z'], (*73)
### pop
> Associated with [array_pop()](https://secure.php.net/manual/en/function.array-pop.php).
``` php
$a = A::create(['a', 'b', 'c']);
$a->pop(); // 'c'
$a->toArray(); // [0 => 'a', 1 => 'b']
previous
Associated with prev()., (*74)
``` php
$a = A::create(['a', 'b', 'c']);
$a->next(); // 'b'
$a->next(); // 'c'
$a->previous(); // 'b', (*75)
### push
> Associated with [array_push()](https://secure.php.net/manual/en/function.array-push.php).
``` php
$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., (*76)
reduce
Associated with array_reduce()., (*77)
``` php
$a = A::create(['a', 'b', 'c']);
$a = $a->reduce(function($result, $item) {
return $result . $item;
}); // 'abc', (*78)
### reindex
> Based on [array_values()](https://secure.php.net/manual/en/function.array-values.php).
``` php
$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()., (*79)
``` php
$a = A::create(['a', 'd', 'e']);
$a = $a->replace([1 => 'b', 2 => 'c']);
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c'], (*80)
### reset
> Associated with [reset()](https://secure.php.net/manual/en/function.reset.php).
``` php
$a = A::create(['a', 'b', 'c']);
$a->reset(); // 'a'
reverse
Associated with array_reverse()., (*81)
``` php
$a = A::create(['a', 'b', 'c']);
$a = $a->reverse();
$a->toArray(); // [0 => 'c', 1 => 'b', 2 => 'a'], (*82)
### search
> Associated with [array_search()](https://secure.php.net/manual/en/function.array-search.php).
``` php
$a = A::create(['a', 'b', 'c']);
$a->search('b'); // 1
shift
Associated with array_shift()., (*83)
``` php
$a = A::create(['a', 'b', 'c']);
$a->shift();
$a->toArray(); // [0 => 'b', 1 => 'c'], (*84)
### shuffle
> Associated with [shuffle()](https://secure.php.net/manual/en/function.shuffle.php).
``` php
$a = A::create(['a', 'b', 'c']);
$a->shuffle();
$a->toArray(); // [0 => 'c', 1 => 'a', 2 => 'b']
slice
Associated with array_slice()., (*85)
``` php
$a = A::create(['a', 'b', 'c', 'd']);
$a = $a->slice(1, 2);
$a->toArray(); // [0 => 'b', 1 => 'c'], (*86)
### sort
> Associated with [arsort()](https://secure.php.net/manual/en/function.arsort.php) /
[sort()](https://secure.php.net/manual/en/function.sort.php) /
[asort()](https://secure.php.net/manual/en/function.asort.php) /
[rsort()](https://secure.php.net/manual/en/function.rsort.php).
``` php
$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()., (*87)
``` php
$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'], (*88)
### toArray
Convert the array to a simple PHP `array` type:
``` php
$a = A::create(['a', 'b', 'c']);
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c']
toJson
Associated with json_encode()., (*89)
Creates a JSON string from the array:, (*90)
``` php
$a = A::create(['a' => 1, 'b' => 2, 'c' => 3]);
$a->toJson(); // { "a": 1, "b": 2, "c": 3 }, (*91)
### toReadableString
> Based on [implode()](https://secure.php.net/manual/en/function.implode.php).
Converts instance array to a readable PHP `string`:
``` php
$a = A::create(['a', 'b', 'c']);
$a->toReadableString(', ', ' and '); // 'a, b and c'
toString
Associated with implode()., (*92)
Converts instance array to a simple PHP string:, (*93)
``` php
$a = A::create(['a', 'b', 'c']);
$a->toString(', '); // 'a, b, c', (*94)
### unique
> Associated with [array_unique()](https://secure.php.net/manual/en/function.array-unique.php).
``` php
$a = A::create(['a', 'b', 'b', 'c']);
$a = $a->unique();
$a->toArray(); // [0 => 'a', 1 => 'b', 3 => 'c']
unshift
Associated with array_unshift()., (*95)
``` php
$a = A::create(['a', 'b']);
$a->unshift('y', 'z');
$a->toArray(); // [0 => 'y', 1 => 'z', 2 => 'a', 3 => 'b'], (*96)
> Method `unshift()` allow multiple arguments.
### walk
> Associated with [array_walk()](https://secure.php.net/manual/en/function.array-walk.php) /
[array_walk_recursive()](https://secure.php.net/manual/en/function.array-walk-recursive.php).
``` php
$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., (*97)
In order to propose a new feature the best way is to submit an Issue and discuss it first., (*98)
Links
Arrayzy was inspired by Doctrine [ArrayCollection][7] class and Stringy library., (*99)
Look at the Stringy if you are looking for a PHP string manipulation library in an OOP way., (*100)
Move UP, (*101)
Wallogit.com
