Skip to content

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

License

Notifications You must be signed in to change notification settings

th3l0g4n/Arrayzy

Repository files navigation

Arrayzy

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

SensioLabsInsight Build Status Scrutinizer Code Quality Code Coverage

There are two classes available with different behavior:

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

  • 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 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':

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:

Debugging

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

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 instance 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

$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

isEmpty

$a = A::create([]);
$a->isEmpty(); // 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

About

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

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • PHP 100.0%