Arrayzy

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

Contents

• Requirements
• Installation
• Creation
• Usage
  • Chaining
• Public method list
  • add
  • chunk
  • clear
  • combineTo
  • combineWith
  • contains
  • containsKey
  • count
  • create
  • createClone
  • createFromJson
  • createFromObject
  • createFromString
  • createWithRange
  • current
  • customSort
  • customSortKeys
  • debug
  • diffWith
  • each
  • exists
  • export
  • filter
  • find
  • first
  • flip
  • getIterator
  • getKeys
  • getRandom
  • getRandomKey
  • getRandomKeys
  • getRandomValues
  • getValues
  • indexOf
  • isAssoc
  • isEmpty
  • isNumeric
  • 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
• 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

Debugging

• debug
• export

Public method list

add

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

chunk

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

clear

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

combineTo

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

combineWith

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

contains

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

containsKey

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

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

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

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

Creates an array of a specified range:

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

current

Position of the iterator.

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

customSort

$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

$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

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

diffWith

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

each

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

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

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

filter

$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']

find

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

first

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

flip

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

getIterator

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

getKeys

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

getRandom

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

getRandomKey

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

getRandomKeys

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

getRandomValues

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

getValues

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

indexOf

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

isAssoc

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

isEmpty

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

isNumeric

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

key

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

last

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

map

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

mergeTo

// 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]

mergeWith

// 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]

next

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

offsetExists

$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

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

offsetSet

$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

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

pad

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

pop

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

previous

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

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

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

reindex

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

replaceIn

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

replaceWith

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

reverse

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

shift

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

shuffle

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

slice

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

sort

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

sortKeys

$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:

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

toJson

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

Converts instance array to a readable PHP string:

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

toString

Converts instance array to a simple PHP string:

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

unique

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

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

$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