README

This package provides useful helpers for working with arrays in PHP.

Based on ...

Laravel's array helper work (https://github.com/laravel/framework)

Install

You can install this package via composer:

composer require chr15k/array

Usage

accessible
add
collapse
crossJoin
divide
dot
except
exists
first
flatten
forget
get
has
hasAny
isAssoc
isMultiDimensional
last
only
pluck
prepend
pull
query
random
set
shuffle
sort
sortRecursive
where
wrap

Arr::accessible()

The Arr::accessible method checks that the given value is array accessible:

<?php

use Chr15k\Arr\Arr;

$isAccessible = Arr::accessible(['a' => 1, 'b' => 2]);

// true

$isAccessible = Arr::accessible('abc');

// false

$isAccessible = Arr::accessible(new stdClass);

// false

Arr::add()

The Arr::add method adds a given key / value pair to an array if the given key doesn't already exist in the array or is set to null:

<?php

use Chr15k\Arr\Arr;

$array = Arr::add(['name' => 'Desk'], 'price', 100);

// ['name' => 'Desk', 'price' => 100]

$array = Arr::add(['name' => 'Desk', 'price' => null], 'price', 100);

// ['name' => 'Desk', 'price' => 100]

Arr::collapse()

The Arr::collapse method collapses an array of arrays into a single array:

<?php

use Chr15k\Arr\Arr;

$array = Arr::collapse([[1, 2, 3], [4, 5, 6], [7, 8, 9]]);

// [1, 2, 3, 4, 5, 6, 7, 8, 9]

Arr::crossJoin()

The Arr::crossJoin method cross joins the given arrays, returning a Cartesian product with all possible permutations:

<?php

use Chr15k\Arr\Arr;

$matrix = Arr::crossJoin([1, 2], ['a', 'b']);

/*
    [
        [1, 'a'],
        [1, 'b'],
        [2, 'a'],
        [2, 'b'],
    ]
*/

$matrix = Arr::crossJoin([1, 2], ['a', 'b'], ['I', 'II']);

/*
    [
        [1, 'a', 'I'],
        [1, 'a', 'II'],
        [1, 'b', 'I'],
        [1, 'b', 'II'],
        [2, 'a', 'I'],
        [2, 'a', 'II'],
        [2, 'b', 'I'],
        [2, 'b', 'II'],
    ]
*/

Arr::divide()

The Arr::divide method returns two arrays, one containing the keys, and the other containing the values of the given array:

<?php

use Chr15k\Arr\Arr;

[$keys, $values] = Arr::divide(['name' => 'Desk']);

// $keys: ['name']

// $values: ['Desk']

Arr::dot()

The Arr::dot method flattens a multi-dimensional array into a single level array that uses "dot" notation to indicate depth:

<?php

use Chr15k\Arr\Arr;

$array = ['products' => ['desk' => ['price' => 100]]];

$flattened = Arr::dot($array);

// ['products.desk.price' => 100]

Arr::except()

The Arr::except method removes the given key / value pairs from an array:

<?php

use Chr15k\Arr\Arr;

$array = ['name' => 'Desk', 'price' => 100];

$filtered = Arr::except($array, ['price']);

// ['name' => 'Desk']

Arr::exists()

The Arr::exists method checks that the given key exists in the provided array:

<?php

use Chr15k\Arr\Arr;

$array = ['name' => 'John Doe', 'age' => 17];

$exists = Arr::exists($array, 'name');

// true

$exists = Arr::exists($array, 'salary');

// false

Arr::first()

The Arr::first method returns the first element of an array passing a given truth test:

<?php

use Chr15k\Arr\Arr;

$array = [100, 200, 300];

$first = Arr::first($array, function ($value, $key) {
    return $value >= 150;
});

// 200


// A default value may also be passed as the third parameter to the method. This value will be returned if no value passes the truth test:

$first = Arr::first($array, $callback, $default);

Arr::flatten()

The Arr::flatten method flattens a multi-dimensional array into a single level array:

<?php

use Chr15k\Arr\Arr;

$array = ['name' => 'Joe', 'languages' => ['PHP', 'Ruby']];

$flattened = Arr::flatten($array);

// ['Joe', 'PHP', 'Ruby']

Arr::forget()

The Arr::forget method removes a given key / value pair from a deeply nested array using "dot" notation:

<?php

use Chr15k\Arr\Arr;

$array = ['products' => ['desk' => ['price' => 100]]];

Arr::forget($array, 'products.desk');

// ['products' => []]

Arr::get()

The Arr::get method retrieves a value from a deeply nested array using "dot" notation:

<?php

use Chr15k\Arr\Arr;

$array = ['products' => ['desk' => ['price' => 100]]];

$price = Arr::get($array, 'products.desk.price');

// 100


// The Arr::get method also accepts a default value, which will be returned if the specific key is not found:

$discount = Arr::get($array, 'products.desk.discount', 0);

// 0

Arr::has()

The Arr::has method checks whether a given item or items exists in an array using "dot" notation:

<?php

use Chr15k\Arr\Arr;

$array = ['product' => ['name' => 'Desk', 'price' => 100]];

$contains = Arr::has($array, 'product.name');

// true

$contains = Arr::has($array, ['product.price', 'product.discount']);

// false

Arr::hasAny()

The Arr::hasAny method checks whether any item in a given set exists in an array using "dot" notation:

<?php

use Chr15k\Arr\Arr;

$array = ['product' => ['name' => 'Desk', 'price' => 100]];

$contains = Arr::hasAny($array, 'product.name');

// true

$contains = Arr::hasAny($array, ['product.name', 'product.discount']);

// true

$contains = Arr::hasAny($array, ['category', 'product.discount']);

// false

Arr::isAssoc()

The Arr::isAssoc returns true if the given array is an associative array. An array is considered "associative" if it doesn't have sequential numerical keys beginning with zero:

<?php

use Chr15k\Arr\Arr;

$isAssoc = Arr::isAssoc(['product' => ['name' => 'Desk', 'price' => 100]]);

// true

$isAssoc = Arr::isAssoc([1, 2, 3]);

// false

Arr::isMultiDimensional()

The Arr::isMultiDimensional method returns true if the given array is multi-dimensional

<?php

use Chr15k\Arr\Arr;

$isMultiDimensional = Arr::isMultiDimensional(['product' => ['name' => 'Desk', 'price' => 100]]);

// true

$isMultiDimensional = Arr::isMultiDimensional([2, 3, [4]]);

// true

$isMultiDimensional = Arr::isMultiDimensional([2, 3, 4]);

// false

$isMultiDimensional = Arr::isMultiDimensional(['name' => 'Desk', 'price' => 100]);

// false


// Accounts for empty arrays

$isMultiDimensional = Arr::isMultiDimensional(['name' => 'Desk', 'price' => 100, []]);

// true

Arr::last()

The Arr::last method returns the last element of an array passing a given truth test:

<?php

use Chr15k\Arr\Arr;

$array = [100, 200, 300, 110];

$last = Arr::last($array, function ($value, $key) {
    return $value >= 150;
});

// 300

// A default value may be passed as the third argument to the method. This value will be returned if no value passes the truth test:

$last = Arr::last($array, $callback, $default);

Arr::only()

The Arr::only method returns only the specified key / value pairs from the given array:

<?php

use Chr15k\Arr\Arr;

$array = ['name' => 'Desk', 'price' => 100, 'orders' => 10];

$slice = Arr::only($array, ['name', 'price']);

// ['name' => 'Desk', 'price' => 100]

Arr::pluck()

The Arr::pluck method retrieves all of the values for a given key from an array:

<?php

use Chr15k\Arr\Arr;

$array = [
    ['developer' => ['id' => 1, 'name' => 'Taylor']],
    ['developer' => ['id' => 2, 'name' => 'Abigail']],
];

$names = Arr::pluck($array, 'developer.name');

// ['Taylor', 'Abigail']

// You may also specify how you wish the resulting list to be keyed:

$names = Arr::pluck($array, 'developer.name', 'developer.id');

// [1 => 'Taylor', 2 => 'Abigail']

Arr::prepend()

The Arr::prepend method will push an item onto the beginning of an array:

<?php

use Chr15k\Arr\Arr;

$array = ['one', 'two', 'three', 'four'];

$array = Arr::prepend($array, 'zero');

// ['zero', 'one', 'two', 'three', 'four']


// If needed, you may specify the key that should be used for the value:

$array = ['price' => 100];

$array = Arr::prepend($array, 'Desk', 'name');

// ['name' => 'Desk', 'price' => 100]

Arr::pull()

The Arr::pull method returns and removes a key / value pair from an array:

<?php

use Chr15k\Arr\Arr;

$array = ['name' => 'Desk', 'price' => 100];

$name = Arr::pull($array, 'name');

// $name: Desk

// $array: ['price' => 100]


// A default value may be passed as the third argument to the method. This value will be returned if the key doesn't exist:

$value = Arr::pull($array, $key, $default);

Arr::query()

The Arr::query method converts the array into a query string:

<?php

use Chr15k\Arr\Arr;

$array = ['name' => 'Taylor', 'order' => ['column' => 'created_at', 'direction' => 'desc']];

Arr::query($array);

// name=Taylor&order[column]=created_at&order[direction]=desc

Arr::random()

The Arr::random method returns a random value from an array:

<?php

use Chr15k\Arr\Arr;

$array = [1, 2, 3, 4, 5];

$random = Arr::random($array);

// 4 - (retrieved randomly)


// You may also specify the number of items to return as an optional second argument.
// Note that providing this argument will return an array, even if only one item is desired:

$items = Arr::random($array, 2);

// [2, 5] - (retrieved randomly)

Arr::set()

The Arr::set method sets a value within a deeply nested array using "dot" notation:

<?php

use Chr15k\Arr\Arr;

$array = ['products' => ['desk' => ['price' => 100]]];

Arr::set($array, 'products.desk.price', 200);

// ['products' => ['desk' => ['price' => 200]]]

Arr::shuffle()

The Arr::shuffle method randomly shuffles the items in the array:

<?php

use Chr15k\Arr\Arr;

$array = Arr::shuffle([1, 2, 3, 4, 5]);

// [3, 2, 5, 1, 4] - (generated randomly)

Arr::sort()

The Arr::sort method sorts an array by its values.

<?php

use Chr15k\Arr\Arr;

$array = ['Desk', 'Table', 'Chair'];

$sorted = Arr::sort($array);

// ['Chair', 'Desk', 'Table']


// Reverse the order by passing true to the second argument

$sorted = Arr::sort($array, true);

// ['Table', 'Desk', 'Chair']

Arr::sortRecursive()

The Arr::sortRecursive method recursively sorts an array using the sort function for numeric sub=arrays and ksort for associative subarrays:

<?php

use Chr15k\Arr\Arr;

$array = [
    ['Roman', 'Taylor', 'Li'],
    ['PHP', 'Ruby', 'JavaScript'],
    ['one' => 1, 'two' => 2, 'three' => 3],
];

$sorted = Arr::sortRecursive($array);

/*
    [
        ['JavaScript', 'PHP', 'Ruby'],
        ['one' => 1, 'three' => 3, 'two' => 2],
        ['Li', 'Roman', 'Taylor'],
    ]
*/

Arr::where()

The Arr::where method filters an array using the given Closure:

<?php

use Chr15k\Arr\Arr;

$array = [100, '200', 300, '400', 500];

$filtered = Arr::where($array, function ($value, $key) {
    return is_string($value);
});

// [1 => '200', 3 => '400']

Arr::wrap()

The Arr::wrap method wraps the given value in an array. If the given value is already an array it will not be changed:

<?php

use Chr15k\Arr\Arr;

$string = 'Laravel';

$array = Arr::wrap($string);

// ['Laravel']

// If the given value is null, an empty array will be returned:

$nothing = null;

$array = Arr::wrap($nothing);

// []

Testing

You can run the tests with:

vendor/bin/phpunit

License

The MIT License (MIT). Please see License File for more information.

chr15k / array

Maintainers

Details