README

Ar makes working with PHP arrays easy

• Consistent: All functions accept the array as first parameter.
• Immutable: the input array is never modified. Fluent style returns a new object for every call.
• Tested: unit-tested with 100% code coverage.
• Familiar: function names follow PHP whereever possible.

Fluent style:

use FriendlyPixel\Ar\Ar;

$ints = Ar::wrap([1, 6, 8])
    ->map(fn ($num) => $num * $num)
    ->filter(fn ($value, $key) => $value % 2 == 0);

Functional style:

use FriendlyPixel\Ar\Ar;

$ints = [1, 5, 8];
$ints = Ar::map($ints, fn($num) => $num * $num);
$ints = Ar::filter($ints, fn($value, $key) => $value % 2 == 0)

Install

Install the latest version using Composer:

$ composer require friendly-pixel/ar

Methods

• count()
• filter()
• first()
• flat()
• forEach()
• implode()
• keys()
• last()
• map()
• mapKeys()
• merge()
• push()
• reduce()
• search()
• slice()
• sort()
• splice()
• unique()
• unshift()
• values()

Fluent style only:

• wrap()
• unwrap()

count

Count how many items there are in the array.

use FriendlyPixel\Ar\Ar;

$count = Ar::count([1, 2, 3]); 
$count = Ar::wrap([1, 2, 3])
    ->count()
;
// Result: 3

filter

Pass every value, key into a user-supplied callable, and only put the item into the result array if the returned value is true. Keys are preserved only when array_is_list($array) returns false;

use FriendlyPixel\Ar\Ar;

$even = Ar::filter([1, 2, 3, 12], function($value, $key) { return $value % 2 == 0; }); 
$even = Ar::wrap([1, 2, 3, 12])
    ->filter(function($value, $key) { return $value % 2 == 0; })
    ->unwrap();
// Result: [1 => 2, 3 => 12]

@template A

@param A[] $array

@param callable(A $value, mixed $key): bool $callable

@return A[]

first

Returns the first value of the array or false when it's empty.

use FriendlyPixel\Ar\Ar;

Ar::first([2, 3, 4]);
Ar::wrap([2, 3, 4])->first();

// Result: 2

@template A

@param A[] $array

@return A

flat

The flat() method creates a new array with all sub-array elements concatenated into it recursively up to the specified depth.

@param int $depth To what level to flatten the array. Default: 1

@return mixed[]

forEach

Walk over every value, key. Pass every value, key into a user-supplied callable.

@template A

@param A[] $array

@param callable(A $value, mixed $key): void $callable

@return A[] Original array, unmodified

implode

Join all values into a big string, using $glue as separator. $glue is optional.

use FriendlyPixel\Ar\Ar;

$result = Ar::implode(['a', 'b', 'c'], ','); 
$result = Ar::wrap(['a', 'b', 'c'])
    ->implode(',')
;
// result: "a,b,c"

keys

Return the keys of an array as a sequential array.

use FriendlyPixel\Ar\Ar;

$result = Ar::keys([3 => 'a', 'foo' => 'b', 1 => 'c']); 
$result = Ar::wrap([3 => 'a', 'foo' => 'b', 1 => 'c'])->keys()->unwrap();
// result: [3, 'foo', 1]

@return mixed[]

last

Returns the last value of the array or false when it's empty.

use FriendlyPixel\Ar\Ar;

Ar::last([2, 3, 4]);
Ar::wrap([2, 3, 4])->last();

// Result: 4

@template A

@param A[] $array

@return A

map

Transform values. Pass every value, key into a user-supplied callable, and put the returned value into the result array. Keys are preserved.

use FriendlyPixel\Ar\Ar;

$numbers = Ar::map([1, 2, 3], function($value, $key) { return $value * 2; }); 
$numbers = Ar::wrap([1, 2, 3])
    ->map(function($value, $key) { return $value * 2; })
    ->unwrap();
// Result: [2, 4, 6]

@template A

@template B

@param A[] $array

@param callable(A $value, mixed $key): B $callable

@return B[]

mapKeys

Transform keys. Pass every value, key and key into a user-supplied callable, and use the returned value as key in the result array.

use FriendlyPixel\Ar\Ar;

$numbers = Ar::mapKeys([1, 2, 3], function($value, $key) { return $key * 2; }); 
$numbers = Ar::wrap([1, 2, 3])
    ->mapKeys(function($value, $key) { return $key * 2; })
    ->unwrap();
// Result: [0 => 2, 2 => 2, 4 => 3]

@template A

@template K

@param A[] $array

@param callable(A $value, mixed $key): K $callable

@return array<K, A>

merge

Merges the elements of one or more arrays together so that the values of one are appended to the end of the previous one. If the input arrays have the same string keys, then the later value for that key will overwrite the previous one. If, however, the arrays contain numeric keys, the later value will not overwrite the original value, but will be appended. Values in the input arrays with numeric keys will be renumbered with incrementing keys starting from zero in the result array.

use FriendlyPixel\Ar\Ar;

$numbers = Ar::merge(['a', 'b'], ['c', 'd'])); 
$numbers = Ar::wrap(['a', 'b'])
    ->merge(['b', 'c'])
    ->unwrap();
// Result:['a', 'b', 'c', 'd']

@template A

@var A[][] $arrays

@return A[]

push

Append one or more items to the end of array.

use FriendlyPixel\Ar\Ar;

$result = Ar::push([1, 2], 3, 4); 
$result = Ar::wrap([1, 2])->push(3, 4)->unwrap();

// result: [1, 2, 3, 4]

@template A

@param A[] $array

@param A[] $values

@return A[]

reduce

Iteratively reduce the array to a single value using a callback function.

@template A

@template B

@param A[] $array

@param callable(B|null $carry, A $value, mixed $key): B $callable

@param B|null $initial If the optional initial is available, it will be used at the beginning of the process, or as a final result in case the array is empty.

@return B

search

Return the first value for which the callable returns true. Returns null otherwise.

use FriendlyPixel\Ar\Ar;

$found = Ar::search([ ['a' => 1], ['a' => 8], ['a' => 3] ], function($value, $key) { return $value['a'] == 3; }); 
$found = Ar::wrap([ ['a' => 1], [], ['a' => 3] ])
    ->search(function($value, $key) { return $value['a'] == 3; })
;
// Result: ['a' => 3]

@template A

@param A[] $array

@param callable(A $value, mixed $key): bool $callable

@return A|null

slice

Extract a slice of the array, include $length items, and starting from $offset.

use FriendlyPixel\Ar\Ar;

$even = Ar::slice(['a', 'b', 'c', 'd'], 1, 2); 
$even = Ar::wrap(['a', 'b', 'c', 'd'])
    ->slice(1, 2)
    ->unwrap();
// Result: ['b', 'c']

@template A

@param A[] $array

@param int $offset If offset is non-negative, the sequence will start at that offset in the array. If offset is negative, the sequence will start that far from the end of the array.

@param ?int $length If length is given and is positive, then the sequence will have up to that many elements in it. If the array is shorter than the length, then only the available array elements will be present. If length is given and is negative then the sequence will stop that many elements from the end of the array. If it is omitted, then the sequence will have everything from offset up until the end of the array.

@return A[]

sort

Sort an array by values using a user-defined comparison function.

This function assigns new keys to the elements in array. It will remove any existing keys that may have been assigned.

@template A

@param A[] $array

@param callable(A $valueA, A $valueB): int $callable
Return an integer smaller then, equal to, or larger than 0 to indicate that $valueA is less then, equal to, or larger than $valueB.

@return A[]

splice

Remove a portion of the array and replace it with something else. Other than the default php function, this returns the changed array, not the extracted elements.

use FriendlyPixel\Ar\Ar;

$even = Ar::splice(['a', 'b', 'c', 'd'], 1, 1, ['q', 'x']); 
$even = Ar::wrap(['a', 'b', 'c', 'd'])
    ->splice(1, 1, ['q', 'x'])
    ->unwrap();
// Result: ['a', 'q', 'x', 'c', 'd']

@template A

@param A[] $array

@param int $offset If offset is positive then the start of the removed portion is at that offset from the beginning of the array.

 If offset is negative then the start of the removed portion is at that offset from 
 the end of the array. 

@param ?int $length If length is omitted, removes everything from offset to the end of the array. * If length is specified and is positive, then that many elements will be removed.

 If length is specified and is negative, then the end of the removed portion will be 
 that many elements from the end of the array.
  
 If length is specified and is zero, no elements will be removed. 

@param A[] $replacement If replacement array is specified, then the removed elements are replaced with elements from this array.

 If offset and length are such that nothing is removed, then the elements from the 
 replacement array are inserted in the place specified by the offset. 
 *
 If replacement is just one element it is not necessary to put array() or square brackets 
 around it, unless the element is an array itself, an object or null. 
 
 Note: Keys in the replacement array are not preserved.

@return A[] Other than the default php function, this returns the changed array, not the extracted elements.

unique

Remove duplicate values from array. Keys are preserved only when array_is_list($array) returns false;

use FriendlyPixel\Ar\Ar;

$result = Ar::unique(['a', 'a', 'b']); 
$result = Ar::wrap(['b', 4])->unique(['a', 'a', 'b'])->unwrap();

// result: [0 => 'a', 2 => 'b']

@template A

@param A[] $array

@param int $flags The optional second parameter flags may be used to modify the sorting behavior using these values: Sorting type flags:

SORT_REGULAR - compare items normally (don't change types)
SORT_NUMERIC - compare items numerically
SORT_STRING - compare items as strings
SORT_LOCALE_STRING - compare items as strings, based on the current locale.

@return A[]

unshift

Prepend one or more items to the beginning of array.

use FriendlyPixel\Ar\Ar;

$result = Ar::unshift([3, 4], 1, 2); 
$result = Ar::wrap([3, 4])->unshift(1, 2)->unwrap();

// result: [1, 2, 3, 4]

@template A

@param A[] $array

@param A[] $values

@return A[]

values

Return the values of an array as a sequential array.

use FriendlyPixel\Ar\Ar;

$result = Ar::values([3 => 'a', 'foo' => 'b', 1 => 'c']); 
$result = Ar::wrap([3 => 'a', 'foo' => 'b', 1 => 'c'])->values()->unwrap();
// result: [0 => 'a', 1 => 'b', 2 => 'c']

@template A

@param array<mixed, A> $array

@return array<int, A>

Fluent style only methods

wrap

Wrap an array, so you can use fluent syntax to call multiple methods on it. Use ->unwrap() at the end if you need a pure array again.

use FriendlyPixel\Ar\Ar;
$numbers = Ar::wrap([1, 2, 3])
    ->map(function ($value, $key) { return $value * 2; })
    ->filter(function ($value) { return $value != 6; })
    ->unwrap()
;

// If you don't like the Ar::wrap syntax, you can also use ArFluent directly:
use FriendlyPixel\Ar\ArFluent;

$numbers = (new ArFluent([1, 2, 3]))
    ->map(function ($value, $key) { return $value * 2; })
    ->filter(function ($value) { return $value != 6; })
    ->unwrap()
;

unwrap

Return the underlying array.

use FriendlyPixel\Ar\Ar;
$numbers = Ar::wrap([1, 2, 3])
    ->map(function ($value, $key) { return $value * 2; })
    ->unwrap()
;
// Result: [2, 4, 6]

toArray

Alias for unwrap()

License

MIT license