The wrapper for all PHP built-in array functions and easy, object-oriented array manipulation library. In short: Arrays on steroids.
There are two classes available with different behavior:
Each method operates on the same array and returns the array itself
(it DOES NOT create a new instance), except methods starting with the
create
prefix. This way has slightly better performance and is more
convenient to use in an OOP way.
NOTE: Check the CreateClone section if you want to operate on a new instance to preserve the current one.
Each method creates a new array, leaving the original array unchanged. This way has slightly worse performance but give you a behavior similar to most of the built-in PHP functions that return a new array.
NOTE: If you don't need the first array you operate on, you can override it manually:
$a = ImmutableArray::create(['a', 'b', 'c']);
$a = $a->shuffle(); // override instance you operates on, because $a !== $a->shuffle()
- Requirements
- Installation
- Creation
- Usage
- Public method list
- chunk
- clear
- combineTo
- combineWith
- contains
- containsKey
- count
- create
- createClone
- createFromJson
- createFromObject
- createFromString
- createWithRange
- current
- customSort
- customSortKeys
- debug
- diffWith
- each
- export
- filter
- find
- first
- flip
- getIterator
- getKeys
- getRandom
- getRandomKey
- getRandomKeys
- getRandomValues
- getValues
- indexOf
- isEmpty
- key
- last
- map
- mergeTo
- mergeWith
- next
- offsetExists
- offsetGet
- offsetSet
- offsetUnset
- pad
- pop
- previous
- push
- reduce
- reindex
- replaceIn
- replaceWith
- reverse
- shift
- shuffle
- slice
- sort
- sortKeys
- toArray
- toJson
- toReadableString
- toString
- unique
- unshift
- walk
- Links
- PHP
5.4
or higher - PHP
JSON
extension
The preferred way to install this package is to use Composer:
$ composer require bocharsky-bw/arrayzy:dev-master
If you don't use Composer
- register this package in your autoloader manually
or download the library manually and require
the necessary files directly in your scripts:
require_once __DIR__ . '/path/to/library/src/MutableArray.php';
Don't forget namespaces. Use namespace aliases for simplicity if you want:
use Arrayzy\MutableArray as MuArr;
use Arrayzy\ImmutableArray as ImArr;
Create a new empty array with the new
statement.
$a = new MutableArray; // Create new instance of MutableArray
// or
$a = new ImmutabelArray; // Create new instance of ImmutableArray
// or
$a = new MuArr; // using namespace aliases
or with default values, passed to the constructor in an array:
$a = new MutableArray([1, 2, 3]);
// or
$a = new ImmutabelArray([1, 2, 3]);
Also, new objects can be created with one of the public static methods prefixed with 'create':
You can get access to the values like with the familiar PHP array syntax:
use Arrayzy\MutableArray 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 ImmutableArray
and
MutableArray
alike. In the examples provided they are are interchangeable and
aliased with A
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()
->reindex() // or any other method that returns the current instance
;
$a->toArray(); // [0 => 'c', 1 => 'a', 2 => 'e', 3 => 'd', 4 => 'b']
Easily convert instance array elements to a simple PHP array
, string
,
readable string
or JSON format:
$a = A::create(['a', 'b', 'c']);
$a->chunk(2);
$a->toArray(); // [0 => [0 => 'a', 1 => 'b'], 1 => [0 => 'c']]
$a = A::create(['a', 'b', 'c']);
$a->clear();
$a->toArray(); // []
$a = A::create(['a', 'b', 'c']);
$a->combineTo([1, 2, 3]);
$a->toArray(); // [1 => 'a', 2 => 'b', 3 => 'c']
$a = A::create([1, 2, 3]);
$a->combineWith(['a', 'b', 'c']);
$a->toArray(); // [1 => 'a', 2 => 'b', 3 => 'c']
$a = A::create(['a', 'b', 'c']);
$a->contains('c'); // true
$a = A::create(['a', 'b', 'c']);
$a->containsKey(2); // true
$a = A::create(['a', 'b', 'c']);
$a->count(); // 3
$a = A::create(['a', 'b', 'c']);
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c']
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
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]
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']
Creates an instance array from a simple PHP string
with specified separator:
$a = A::createFromString('a;b;c', ';');
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c']
Creates an array of a specified range:
$a = A::createWithRange(2, 6, 2);
$a->toArray(); // [0 => 2, 1 => 4, 2 => 6]
$a = A::create(['a', 'b', 'c']);
$a->current(); // 'a'
$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']
$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']
$a = A::create(['a', 'b', 'c']);
$a->debug(); // Array ( [0] => a [1] => b [2] => c )
$a = A::create(['a', 'b', 'c']);
$a->diffWith(['c', 'd']);
$a->toArray(); // [0 => 'a', 1 => 'b']
$a = A::create(['a', 'b', 'c']);
$a->each(); // [0 => 0, 'key' => 0, 1 => 'a', 'value' => 'a']
$a = A::create(['a', 'b', 'c']);
$a->export(); // array ( 0 => 'a', 1 => 'b', 2 => 'c', )
$a = A::create(['a', 'z', 'b', 'z']);
$a->filter(function($value) {
return 'z' !== $value; // exclude 'z' value from array
});
$a->toArray(); // [0 => 'a', 2 => 'b']
$a = A::create(['a', 'b', 'c']);
$a->find(function($value, $key) {
return 'b' == $value && 0 < $key;
}); // 'b'
$a = A::create(['a', 'b', 'c']);
$a->first(); // 'a'
$a = A::create(['a', 'b', 'c']);
$a->flip();
$a->toArray(); // ['a' => 0, 'b' => 1, 'c' => 2]
Creates an external Iterator. Check the iteratorAggregate documentation for more information.
$a = A::create(['a' => 1, 'b' => 2, 'c' => 3]);
$a->getKeys(); // [0 => 'a', 1 => 'b', 2 => 'c']
$a = A::create(['a', 'b', 'c', 'd']);
$a->getRandom(); // 'c'
$a = A::create(['a', 'b', 'c', 'd']);
$a->getRandomKey(); // 2
$a = A::create(['a', 'b', 'c', 'd']);
$a->getRandomKeys(2); // [0, 2]
$a = A::create(['a', 'b', 'c', 'd']);
$a->getRandomValues(2); // ['b', 'd']
$a = A::create([1 => 'a', 2 => 'b', 3 => 'c']);
$a->getValues(); // [0 => 'a', 1 => 'b', 2 => 'c']
$a = A::create(['a', 'b', 'c']);
$a->indexOf('b'); // 1
$a = A::create([]);
$a->isEmpty(); // true
$a = A::create(['a', 'b', 'c']);
$a->current(); // 'a'
$a->key(); // 0
$a->next(); // 'b'
$a->key(); // 1
$a = A::create(['a', 'b', 'c']);
$a->last(); // 'c'
$a = A::create(['a', 'b', 'c']);
$a->map(function($value) {
return $value . $value;
});
$a->toArray(); // [0 => 'aa', 1 => 'bb', 2 => 'cc']
// indexed array behavior
$a = A::create(['a', 'b', 'c']); // create indexed array
$a->mergeTo(['c', 'd']); // [0 => 'c', 1 => 'd', 2 => 'a', 3 => 'b', 4 => 'c']
// assoc array behavior
$b = A::create(['a' => 1, 'b' => 2, 'c' => 99]); // create assoc array
$b->mergeTo(['c' => 3, 'd' => 4]); // ['c' => 99, 'd' => 4, 'a' => 1, 'b' => 2]
// indexed array behavior
$a = A::create(['a', 'b', 'c']); // create indexed array
$a->mergeWith(['c', 'd']); // [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->mergeWith(['c' => 3, 'd' => 4]); // ['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4]
$a = A::create(['a', 'b', 'c']);
$a->next(); // 'b'
$a->next(); // 'c'
$a = A::create(['a', 'b', 'c']);
$a->offsetExists(2); // true (or use isset($a[2]))
$a->offsetExists(3); // false (or use isset($a[3]))
$a = A::create(['a', 'b', 'c']);
$a->offsetGet(1); // 'b' (or use $a[1])
$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']
$a = A::create(['a', 'b', 'c']);
$a->offsetUnset(1); // or use unset($a[1]);
$a->toArray(); // [0 => 'a', 2 => 'c']
$a = A::create(['a', 'b', 'c']);
$a->pad(5, 'z');
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c', 3 => 'z', 4 => 'z']
$a = A::create(['a', 'b', 'c']);
$a->pop(); // 'c'
$a->toArray(); // [0 => 'a', 1 => 'b']
$a = A::create(['a', 'b', 'c']);
$a->next(); // 'b'
$a->next(); // 'c'
$a->previous(); // 'b'
$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.
$a = A::create(['a', 'b', 'c']);
$a->reduce(function($result, $item) {
return $result . $item;
}); // 'abc'
$a = A::create([2 => 'a', 1 => 'b', 3 => 'c']);
$a->reindex();
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c']
$a = A::create([1 => 'b', 2 => 'c']);
$a->replaceIn(['a', 'd', 'e']);
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c']
$a = A::create(['a', 'd', 'e']);
$a->replaceWith([1 => 'b', 2 => 'c']);
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c']
$a = A::create(['a', 'b', 'c']);
$a->reverse();
$a->toArray(); // [0 => 'c', 1 => 'b', 2 => 'a']
$a = A::create(['a', 'b', 'c']);
$a->shift();
$a->toArray(); // [0 => 'b', 1 => 'c']
$a = A::create(['a', 'b', 'c']);
$a->shuffle();
$a->toArray(); // [0 => 'c', 1 => 'a', 2 => 'b']
$a = A::create(['a', 'b', 'c', 'd']);
$a->slice(1, 2);
$a->toArray(); // [0 => 'b', 1 => 'c']
$a = A::create(['b', 'a', 'd', 'c']);
$a->sort(SORT_DESC);
$a->toArray(); // [0 => 'd', 1 => 'c', 2 => 'b', 3 => 'a']
$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']
Convert the array to a simple PHP array
:
$a = A::create(['a', 'b', 'c']);
$a->toArray(); // [0 => 'a', 1 => 'b', 2 => 'c']
Creates a JSON string from the array:
$a = A::create(['a' => 1, 'b' => 2, 'c' => 3]);
$a->toJson(); // { "a": 1, "b": 2, "c": 3 }
Converts instance array to a readable PHP string
:
$a = A::create(['a', 'b', 'c']);
$a->toReadableString(', ', ' and '); // 'a, b and c'
Converts instance array to a simple PHP string
:
$a = A::create(['a', 'b', 'c']);
$a->toString(', '); // 'a, b, c'
$a = A::create(['a', 'b', 'b', 'c']);
$a->unique();
$a->toArray(); // [0 => 'a', 1 => 'b', 3 => 'c']
$a = A::create(['a', 'b']);
$a->unshift('y', 'z');
$a->toArray(); // [0 => 'y', 1 => 'z', 2 => 'a', 3 => 'b']
Method
unshift()
allow multiple arguments.
$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']
Feel free to create an Issue or Pull Request if you find a bug or just want to propose an improvement suggestion.
Look at the Stringy if you are looking for a PHP string manipulation library in an OOP way.