PHP arrays and collections made easy

Easy and elegant handling of PHP arrays by using an array-like collection object as offered by jQuery and Laravel Collections.

composer req aimeos/map

Supported PHP versions:

• PHP 8+ (4.x)
• PHP 7.1+ (3.x)

Table of contents

• Why PHP Map
• List of methods
  • Create
  • Access
  • Add
  • Aggregate
  • Debug
  • Order
  • Shorten
  • Test
  • Mutate
  • Misc
• Documentation
• Custom methods
• Performance
• Upgrade guide

Why PHP Map

Instead of:

$list = [['id' => 'one', 'value' => 'value1'], ['id' => 'two', 'value' => 'value2'], null];
$list[] = ['id' => 'three', 'value' => 'value3'];    // add element
unset( $list[0] );                                   // remove element
$list = array_filter( $list );                       // remove empty values
sort( $list );                                       // sort elements
$pairs = array_column( $list, 'value', 'id' );       // create ['three' => 'value3']
$value = reset( $pairs ) ?: null;                    // return first value

Only use:

$list = [['id' => 'one', 'value' => 'value1'], ['id' => 'two', 'value' => 'value2'], null];
$value = map( $list )                                // create Map
    ->push( ['id' => 'three', 'value' => 'value3'] ) // add element
    ->remove( 0 )                                    // remove element
    ->filter()                                       // remove empty values
    ->sort()                                         // sort elements
    ->col( 'value', 'id' )                           // create ['three' => 'value3']
    ->first();                                       // return first value

You can still use:

$map[] = ['id' => 'three', 'value' => 'value3'];
$value = $map[0];
count( $map );
foreach( $map as $key => value );

Use callbacks:

Also, the map object allows you to pass anonymous functions to a lot of methods, e.g.:

$map->each( function( $val, $key ) {
    echo $key . ': ' . $val;
} );

jQuery style:

If your map elements are objects, you can call their methods for each object and get the result as new map just like in jQuery:

// MyClass implements setStatus() (returning $this) and getCode() (initialized by constructor)

$map = Map::from( ['a' => new MyClass( 'x' ), 'b' => new MyClass( 'y' )] );
$map->setStatus( 1 )->getCode()->toArray();

This will call setStatus( 1 ) on both objects. If setStatus() implementation returns $this, the new map will also contain:

['a' => MyClass(), 'b' => MyClass()]

On those new map elements, getCode() will be called which returns x for the first object and y for the second. The map created from the results of getCode() will return:

['a' => 'x', 'b' => 'y']

Methods

function is_map function map construct <a href="#call">call <a href="#callstatic">__callStatic after all any arsort arsorted asort asorted at avg before bool call cast chunk clear clone col collapse combine concat contains copy count countBy dd delimiter diff diffAssoc diffKeys dump duplicates each empty equals every except explode fill filter find findKey first firstKey flat flatten flip float from fromJson get getIterator grep groupBy has if ifAny ifEmpty implements in includes index insertAfter insertAt insertBefore int intersect intersectAssoc intersectKeys is isEmpty isList isObject isNumeric isScalar isSole isString join jsonSerialize keys krsort krsorted ksort ksorted last lastKey ltrim map max merge method min none nth offsetExists offsetGet offsetSet offsetUnset only order pad partition percentage pipe pluck pop pos prefix prepend pull push put random reduce reject rekey remove replace restrict reverse reversed rsort rsorted rtrim search sep set shift shuffle shuffled skip slice sliding sole some sort sorted splice strAfter strBefore strCompare strContains strContainsAll strEnds strEndsAll string strLower strReplace strStarts strStartsAll strUpper suffix sum take tap times to toArray toJson toReversed toSorted toUrl transform transpose traverse tree trim uasort uasorted uksort uksorted unflatten union unique unshift usort usorted values walk where with zip

Create

• function map() : Creates a new map from passed elements
• __construct() : Creates a new map
• clone() : Clones the map and all objects within
• copy() : Creates a new copy
• explode() : Splits a string into a map of elements
• fill() : Creates a new map filled with given value
• from() : Creates a new map from passed elements
• fromJson() : Creates a new map from a JSON string
• times() : Creates a new map by invoking the closure a number of times
• tree() : Creates a tree structure from the list items

Access

• __call() : Calls a custom method
• __callStatic() : Calls a custom method statically
• all() : Returns the plain array
• any() : Tests if at least one element satisfies the callback function
• at() : Returns the value at the given position
• bool() : Returns an element by key and casts it to boolean
• call() : Calls the given method on all items
• find() : Returns the first/last element where the callback returns TRUE
• findKey() : Returns the first/last key where the callback returns TRUE
• first() : Returns the first element
• firstKey() : Returns the first key
• get() : Returns an element by key
• index() : Returns the numerical index of the given key
• int() : Returns an element by key and casts it to integer
• float() : Returns an element by key and casts it to float
• keys() : Returns all keys
• last() : Returns the last element
• lastKey() : Returns the last key
• pop() : Returns and removes the last element
• pos() : Returns the numerical index of the value
• pull() : Returns and removes an element by key
• random() : Returns random elements preserving keys
• search() : Find the key of an element
• shift() : Returns and removes the first element
• sole() : Returns the matching item if it's the only one
• string() : Returns an element by key and casts it to string
• to() : Returns the plain array
• toArray() : Returns the plain array
• values() : Returns all elements with new keys

Add

• concat() : Adds all elements with new keys
• insertAfter() : Inserts the value after the given element
• insertAt() : Inserts the element at the given position in the map
• insertBefore() : Inserts the value before the given element
• merge() : Combines elements overwriting existing ones
• pad() : Fill up to the specified length with the given value
• prepend() : Adds an element at the beginning (alias)
• push() : Adds an element to the end
• put() : Sets the given key and value in the map (alias)
• set() : Overwrites or adds an element
• union() : Adds the elements without overwriting existing ones
• unshift() : Adds an element at the beginning
• with() : Returns a copy and sets an element

Aggregate

• avg() : Returns the average of all values
• count() : Returns the total number of elements
• countBy() : Counts how often the same values are in the map
• max() : Returns the maximum value of all elements
• min() : Returns the minium value of all elements
• percentage() : Returns the percentage of all elements passing the test
• sum() : Returns the sum of all values in the map

Debug

• dd() : Prints the map content and terminates the script
• dump() : Prints the map content
• tap() : Passes a clone of the map to the given callback

Order By

• arsort() : Reverse sort elements preserving keys
• arsorted() : Reverse sort elements preserving keys in a copy of the map
• asort() : Sort elements preserving keys
• asorted() : Sort elements preserving keys in a copy of the map
• krsort() : Reverse sort elements by keys
• krsorted() : Reverse sort elements by keys in a copy of the map
• ksort() : Sort elements by keys
• ksorted() : Sorts a copy of the elements by their keys
• order() : Orders elements by the passed keys
• reverse() : Reverses the array order preserving keys
• reversed() : Reverses the element order in a copy of the map
• toReversed() : Reverses the element order in a copy of the map (alias)
• rsort() : Reverse sort elements using new keys
• rsorted() : Reverse sort elements using new keys in a copy of the map
• shuffle() : Randomizes the element order
• shuffled() : Randomizes the element order in a copy of the map
• sort() : Sorts the elements in-place assigning new keys
• sorted() : Sorts the elements in a copy of the map using new keys
• toSorted() : Sorts the elements in a copy of the map using new keys (alias)
• uasort() : Sorts elements preserving keys using callback
• uasorted() : Sorts elements preserving keys using callback in a copy of the map
• uksort() : Sorts elements by keys using callback
• [uksorte