m1/arrayzy

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

Arrayzy

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:

• Arrayzy\MutableArray
• Arrayzy\ImmutableArray

MutableArray

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.

ImmutableArray

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

Contents

• Requirements
• Installation
• Creation
• Usage
  • Chaining
• 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
  • 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
• 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: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;

Creation

Create a new empty array with the new statement.

$a = new MutableArray; // Create new instance of MutableArray
// or
$a = new ImmutableArray; // 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 ImmutableArray([1, 2, 3]);

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\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.

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()
    ->reindex() // or any other method that returns the current instance
;

$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

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

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

Links

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.

Move UP