Helper carr

The carr helper class provides array utility methods with dot notation support.

carr::accessible

The carr::accessible method determines if the given value is array accessible:

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

// true

$isAccessible = carr::accessible(new CCollection);

// true

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

// false

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

carr::get

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

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

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

The carr::get method also accepts a default value as the third argument, which is returned if the key is not found:

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

// 0

carr::add

The carr::add method adds a key/value pair to the array if the key doesn't exist or is null:

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

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

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

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

carr::collapse

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

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

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

carr::crossJoin

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

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

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

$matrix = carr::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'],
    ]
*/

carr::divide

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

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

// $keys: ['name']

// $values: ['Desk']

/**
 * Use below statement when on the php 5.xx
 */
list($keys, $values) = carr::divide(['name' => 'Desk']);

carr::dot

The carr::dot method flattens a multi-dimensional array into a single-level array using dot notation to indicate depth:

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

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

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

carr::except

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

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

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

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

carr::exists

The carr::exists method checks if the given key exists in the provided array:

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

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

// true

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

// false

carr::first

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

$array = [100, 200, 300];

$first = carr::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 = carr::first($array, $callback, $default);

carr::flatten

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

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

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

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

carr::forget

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

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

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

// ['products' => []]

carr::has

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

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

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

// true

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

// false

carr::hasAny

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

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

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

// true

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

// true

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

// false

carr::isAssoc

The carr::isAssoc method 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:

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

// true

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

// false

carr::isList

The carr::isList method returns true if the given array's keys are sequential integers beginning from zero:

    $isList = Arr::isList(['foo', 'bar', 'baz']);

    // true

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

    // false

carr::join

The carr::join method joins array elements with a string. Using this method's second argument, you may also specify the joining string for the final element of the array:

    $array = ['Tailwind', 'Alpine', 'Laravel', 'Livewire'];

    $joined = carr::join($array, ', ');

    // Tailwind, Alpine, Laravel, Livewire

    $joined = carr::join($array, ', ', ' and ');

    // Tailwind, Alpine, Laravel and Livewire

carr::keyBy

The carr::keyBy method keys the array by the given key. If multiple items have the same key, only the last one will appear in the new array:

    $array = [
        ['product_id' => 'prod-100', 'name' => 'Desk'],
        ['product_id' => 'prod-200', 'name' => 'Chair'],
    ];

    $keyed = carr::keyBy($array, 'product_id');

    /*
        [
            'prod-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
            'prod-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
        ]
    */

carr::last

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

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

$last = carr::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 = carr::last($array, $callback, $default);

carr::map

The carr::map method iterates through the array and passes each value and key to the given callback. The array value is replaced by the value returned by the callback:

$array = ['first' => 'james', 'last' => 'kirk'];

$mapped = carr::map($array, function ($value, $key) {
    return ucfirst($value);
});

// ['first' => 'James', 'last' => 'Kirk']

carr::only

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

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

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

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

carr::pluck

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

    $array = [
        ['product' => ['id' => 1, 'name' => 'Desk']],
        ['product' => ['id' => 2, 'name' => 'Chair']],
    ];

    $names = carr::pluck($array, 'product.name');

    // ['Desk', 'Chair']

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

    $names = carr::pluck($array, 'product.name', 'product.id');

    // [1 => 'Desk', 2 => 'Chair']

carr::prepend

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

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

$array = carr::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 = carr::prepend($array, 'Desk', 'name');

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

carr::prependKeysWith

The carr::prependKeysWith prepends all key names of an associative array with the given prefix:

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

$keyed = Arr::prependKeysWith($array, 'product.');

/*
    [
        'product.name' => 'Desk',
        'product.price' => 100,
    ]
*/

carr::pull

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

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

$name = carr::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 = carr::pull($array, $key, $default);

carr::query

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

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

carr::query($array);

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

carr::random

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

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

$random = carr::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 = carr::random($array, 2);

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

carr::set

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

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

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

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

carr::shuffle

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

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

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

carr::sort

The carr::sort method sorts an array by its values:

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

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

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

You may also sort the array by the results of a given closure:

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

$sorted = array_values(carr::sort($array, function ($value) {
    return $value['name'];
}));

/*
    [
        ['name' => 'Chair'],
        ['name' => 'Desk'],
        ['name' => 'Table'],
    ]
*/

carr::sortRecursive

The carr::sortRecursive method recursively sorts an array using the sort function for numerically indexed sub-arrays and the ksort function for associative sub-arrays:

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

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

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

carr::toCssClasses

The carr::toCssClasses conditionally compiles a CSS class string. The method accepts an array of classes where the array key contains the class or classes you wish to add, while the value is a boolean expression. If the array element has a numeric key, it will always be included in the rendered class list:

$isActive = false;
$hasError = true;

$array = ['p-4', 'font-bold' => $isActive, 'bg-red' => $hasError];

$classes = carr::toCssClasses($array);

/*
    'p-4 bg-red'
*/

carr::undot()

The carr::undot method expands a single-dimensional array that uses "dot" notation into a multi-dimensional array:

$array = [
    'product.type' => 'Desk',
    'product.location' => 'Bed Room',
];

$array = carr::undot($array);

// ['product' => ['type' => 'Desk', 'location' => 'Bed Room']]

carr::where

The carr::where method filters an array using the given closure:

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

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

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

carr::whereNotNull

The carr::whereNotNull method removes all null values from the given array:

    $array = [0, null];

    $filtered = carr::whereNotNull($array);

    // [0 => 0]

carr::wrap

The carr::wrap method wraps the given value in an array. If the given value is already an array it will be returned without modification:

    $string = 'Cresenity';

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

    // ['Cresenity']

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

    $array = carr::wrap(null);

    // []