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
  • 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][1]:

$ 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][2] 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

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().