Skip to content
/ Arrayzy Public

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

License

MIT license
392 stars 38 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

bocharsky-bw/Arrayzy

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

181 Commits
src
src
 
 
tests
tests
 
 
.gitignore
.gitignore
 
 
.scrutinizer.yml
.scrutinizer.yml
 
 
.travis.yml
.travis.yml
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
composer.json
composer.json
 
 
phpunit.xml.dist
phpunit.xml.dist
 
 

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.

Travis Status HHVM Status Scrutinizer Code Quality Code Coverage Software License Latest Version

SensioLabsInsight

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

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

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:

Debugging

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

Creates an array of a specified range:

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

current

Associated with current().

Position of the iterator.

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

customSort

Associated with usort().

$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

Associated with uksort().

$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

Associated with print_r().

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

diff

Associated with array_diff().

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

each

Associated with each().

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

end

Associated with end().

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

except

Based on array_diff_key().

Chunk of an array without given keys.

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

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

Associated with var_export().

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

filter

Associated with array_filter().

$a = A::create(['a', 'z', 'b', 'z']);
$a = $a->filter(function($value) {
    return 'z' !== $value; // exclude 'z' value from array
});
$a->toArray(); // [0 => 'a', 2 => 'b']

find

A custom find method where you can supply your own custom logic in any callable function.

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

first

Alias of reset.

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

flip

Associated with array_flip().

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

getIterator

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

getKeys

Associated with array_keys().

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

getRandom

Associated with array_rand().

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

getRandomKey

Associated with array_rand().

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

getRandomKeys

Associated with array_rand().

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

getRandomValues

Associated with array_rand().

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

getValues

Associated with array_values().

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

indexOf

Alias of search.

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

intersect

Associated with array_intersect().

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

intersectAssoc

Associated with array_intersect_assoc().

$a = A::create(['one' => 'a', 'two' => 'b', 'three' => 'c']);
$a = $a->intersectAssoc(['two' => 'b', 'four' => 'c']);
$a->toArray(); // ['two' => 'b']

intersectKey

Associated with array_intersect_key().

$a = A::create(['one' => 'a', 'two' => 'b', 'three' => 'c']);
$a = $a->intersectKey(['two' => 'd', 'three' => 'e']);
$a->toArray(); // ['two' => 'b', 'three' => 'c']

isAssoc

Check whether all array keys are associative.

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

isEmpty

Check whether array is empty.

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

isNumeric

Check whether all array keys are numeric.

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

key

Associated with key().

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

last

Alias of end.

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

map

Associated with array_map().

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

merge

Associated with array_merge() / array_merge_recursive().

// indexed array behavior
$a = A::create(['a', 'b', 'c']); // create indexed array
$a = $a->merge(['c', 'd']);
$a->toArray(); // [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 = $b->merge(['c' => 3, 'd' => 4]);
$b->toArray(); // ['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4]

next

Associated with next().

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

offsetExists

Implemented for ArrayAccess interface.

$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

Implemented for ArrayAccess interface.

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

offsetSet

Implemented for ArrayAccess interface.

$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

Implemented for ArrayAccess interface.

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

only

Based on array_intersect_key().

Chunk of an array with only given keys.

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

pad

Associated with array_pad().

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

pop

Associated with array_pop().

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

previous

Associated with prev().

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

push

Associated with array_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

Associated with array_reduce().

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

reindex

Based on array_values().

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

replace

Associated with array_replace() / array_replace_recursive().

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

reset

Associated with reset().

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

reverse

Associated with array_reverse().

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

search

Associated with array_search().

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

shift

Associated with array_shift().

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

shuffle

Associated with shuffle().

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

slice

Associated with array_slice().

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

sort

Associated with arsort() / sort() / asort() / rsort().

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

sortKeys

Associated with ksort() / krsort().

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

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

toJson

Associated with json_encode().

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

Based on implode().

Converts instance array to a readable PHP string:

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

toString

Associated with implode().

Converts instance array to a simple PHP string:

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

unique

Associated with array_unique().

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

unshift

Associated with array_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

Associated with array_walk() / array_walk_recursive().

$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

About

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

Resources

Readme

License

MIT license
Activity

Stars

392 stars

Watchers

20 watching

Forks

38 forks
Report repository

Releases 1

v0.6.0 Latest
May 19, 2016

Packages

No packages published

Contributors 10

Languages