The new 2.0 major release of the PHP map package is available which includes new methods and support for working with multi-dimensional arrays in an easy way. Additionally, it comes with the best documentation ever so you find everything you need quickly!

Instead of applying independent PHP functions on arrays, use the PHP Map object to stream array data through several methods to transform, order and shorten its elements until the result exactly conforms to your requirements, for example:

$data = [
    ['name' => 'Tom', 'dep' => 'Dev', 'qty' => 30],
    ['name' => 'Bob', 'dep' => 'Sales', 'qty' => 50],
    ['name' => 'Joe', 'dep' => 'Dev', 'qty' => 10]
];
 
// get the person with the highest quantity in "Dev" department
$name = map( $data )
    ->groupBy( 'dep' )->only( 'Dev' )
    ->flat( 1 )->col( 'name', 'qty' )
    ->ksort()->last();

To get the result in one statement is easier and much more elegant than the traditional way in PHP. The PHP Map object is perfectly suited to work on result sets returned by relational databases. You can transform them until you get a collection that exactly fits for your template generating the HTML for the frontend.

The PHP Map package combines the best from Laravel and CakePHP collections, jQuery, Backbone.js, and Lodash in an easy to use PHP package for every PHP application.

What’s new in PHP Map 2.0

One of the biggest new feature is the ability to pass a path of keys as parameter to several PHP Map methods to work on nested arrays directly. Instead of writing own code for diving into multi-dimensional arrays, you can now use the available methods to e.g. get a value by using:

map( ['key' => ['to' => ['value' => 'yes!']]] )
    ->get( 'key/to/value' ); // returns "yes!"

This also works for more advanced methods like col() to reindex an array by using a nested key:

$data = [
    ['name' => 'Tom', 'addr' => ['zip' => '12AB', 'city' => 'NY']],
    ['name' => 'Bob', 'addr' => ['zip' => '23WD', 'city' => 'LA']]
];
 
$map = map( $data )->col( 'name', 'addr/zip' );
// ['12AB' => 'Tom', '23WD' => 'Bob']

By default, a dot (“/”) is used as seperator between the array key names but you can change that for the current map using the sep() method:

$map = map( $data )->sep( '.' )->col( 'name', 'addr.zip' );

If you want to use another seperator in all new PHP Map objects (existing ones will keep their separator), you can change the delimiter globally with the delimiter() method:

Map::delimiter( ',' );

It also returns the delimiter used before if you want to revert the used delimiter later in your code.

Breaking changes in PHP Map 2.0

The new major version contains a few breaking changes to avoid potential problems that came up in the past. You won’t be affected by most of them but you should have a look to prevent unexpected behaviour.

New slash separator

The most important change affects parameter values including slashes because they are now treated as path separators for nested arrays.

$data = [
    'item/id' => 1,
    'item/code' => 'test',
    'item/name' => 'Test'
];
 
map( $data )->col( 'item/code', 'item/id' );
 
// 1.x
[1 => 'test']
 
// 2.x
[]
// use instead
map( $data )->sep( '.' )->col( 'item/code', 'item/id' );

jQuery style method calls

You can call methods of objects in a map like this:

// 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();

Before, the objects had been checked if they really implement the setStatus() and getCode() methods.

To avoid returning an empty map if the method name is wrong or the called method is catched by the __call() magic method, this isn’t the case any more. If the method isn’t implemented by all objects, PHP generates a fatal error now for better error tracing.

Second equals() parameter

The $assoc parameter of the equals() method to compare keys too has been removed and now, you must use the is() method instead:

// 1.x
map( ['one' => 1] )->equals( ['one' => 1], true );
 
// 2.x
map( ['one' => 1] )->is( ['one' => 1] );

New find() argument

The find() method now accepts a default value or exception object as second argument and the $reverse argument is at the third position now:

// 1.x
Map::from( ['a', 'c', 'e'] )->find( function( $value, $key ) {
    return $value >= 'b';
}, true );
 
// 2.x
Map::from( ['a', 'c', 'e'] )->find( function( $value, $key ) {
    return $value >= 'b';
}, null, true );

Semantic change in groupBy()

Before, items have been grouped by the key string itself if the key passed to groupBy() didn’t exist. To offer easier checking and sorting of the keys, an empty string is used as key now:

Map::from( [
    10 => ['aid' => 123, 'code' => 'x-abc'],
] )->groupBy( 'xid' );
 
// 1.x
[
    'xid' => [
        10 => ['aid' => 123, 'code' => 'x-abc']
    ]
]
 
// 2.x
[
    '' => [
        10 => ['aid' => 123, 'code' => 'x-abc']
    ]
]

Semantic change in offsetExists()

The offsetExists() method uses isset() instead of array_key_exists() now to be in line with typical PHP behavior. Thus, keys with NULL values are now treated differently:

$m = Map::from( ['foo' => null] );
 
// 1.x
isset( $m['foo'] ); // true
 
// 2.x
isset( $m['foo'] ); // false

Renamed split() to explode()

To avoid conflicts with the Laravel split() method and to be in line with the PHP explode() method, the static Map::split() method has been renamed to Map::explode(). Also, the argument order has changed:

// 1.x
Map::split( 'a,b,c', ',' );
 
// 2.x
Map::explode( ',', 'a,b,c' );

The PHP Map package contains many methods to ease your day to day work. They are extremely helpful in a lot of situations where you’ve written custom code up to now. This tutorial explains some of the most useful ones you don’t want to miss any more!

• Documentation at Github
• Composer package at Packagist

Installation

To use the PHP Map package, you have to add it to your composer based application:

composer req aimeos/map

Afterwards, there will be a map() function available, that creates a Map object which offers the methods explained.

col(): Map key/value pairs

There are numerous times when you need to transform an existing array into a list of key/value pairs. Think about a list of database records for example which should be indexed by ID instead of a sequential index. The col() method creates that without the necessity of a loop:

$rows = [['id' => 1, 'code' => 'a'], ['id' => 3, 'code' => 'd']];
$result = map( $rows )->col( 'code', 'id' );
 
// Result equals:
map( [1 => 'a', 3 => 'd'] );

This does also work with objects if they implement the magic PHP __get() method.

collapse() and flat(): Transform multi-dimensional arrays

Do you remember the last time when you had a multi-dimensional array and you needed a flat array of all elements? If you know the maximum depth, you can nest several loops but if not, you need to write a recursive function, which is very cumbersome. The Map object offers the flat() method, that can to do that in one line:

$array = [[1, 2], [3, [4, 5]]];
$result = map( $array )->flat();
 
// Result equals:
map( [1, 2, 3, 4, 5] );

There’s a similar method named collapse(), that does almost the same but keeps the key of each value. Thus, it will overwrite elements with duplicate keys (also numeric keys):

$array = [['a' => 1, 'b' => 2], ['c' => 3, ['a' => 4, 'b' => 5]]];
$result = map( $array )->collapse();
 
// Result equals:
map( ['a' => 4, 'b' => 5, 'c' => 3] );

Both methods accept the number of levels they should collapse or flatten as parameter. That way it’s easy to keep e.g. the third level and above unflattened or uncollapsed.

concat(), merge() and union(): Differences in combining arrays

In PHP, you can combine arrays using array_merge() or the + operator but their results are different. The PHP map package also offers the concat() method:

$one = [0 => 'a', 'b' => 2];
$two = ['b' => 3, 0 => 4];
 
$result = map( $one )->concat( $two );
//equals map( [0 => 'a', 'b' => 2, 1 => 3, 2 => 4] );
 
$result = map( $one )->merge( $two );
//equals map( [0 => 'a', 'b' => 3, 1 => 4] );
 
$result = map( $one )->union( $two );
//equals map( [0 => 'a', 'b' => 2] );

concat() combines the elements of both arrays but doesn’t care about their keys and the resulting list will contain all elements of both arrays. merge() which uses the array_merge() function overwrites existing string keys but renumbers numeric keys. union() is the same as using the + operator and doesn’t add elements whose keys does already exist.

equals(): Test if arrays contains the same elements

To compare arrays, PHP only offers the == and === operators. They return only true if both array contains the same elements with the same keys (and the same order in case of ===). Contrary, the equals() method of the Map object can also test arrays without checking the keys:

$one = ['a', 'b'];
$two = ['b', 'a'];
 
map( $one )->equals( $two ); // true
map( $one )->equals( $two, true ); // false

When passing true as second parameter, equals() works like the == operator.

find(): Return the first matching element

Sometimes, you need the first element from an array that matches your needs. The Map object offers the find() method which allows you to pass a closure function as parameter. This anonymous function can check whose element matches your needs:

map( ['a', 'c', 'e'] )->find( function( $value, $key ) {
    return $value >= 'b';
} );
 
// Result equals 'c'

If no matching value is found, null is returned. If you pass true as second parameter, the search for the matching element will be reversed and you will get the last matching element.

first(), last(), get() and pull(): Advanced ways to retrieve an element

Fetching the first, last or any element of a list of elements is very handy and most useful in many cases. But the PHP Map object offers more than that. What if those methods don’t return null if no element is found but throw an exception or execute a closure? Instead of:

if( ( $item = map( [] ) )->first() === null ) {
    throw new \Exception( 'error' );
}
 
if( ( $item = map( [] ) )->last() === null ) {
    // fetch and return record from database
}
$id = $item->getId();

you can simply write:

$id = map( [] )->first( new \Exception( 'error' ) )->getId();
 
$id = map( [] )->last( function() {
    // fetch and return record from database
} )->getId();

All methods (first(), last(), get() and pull()) methods accept either an exception that’s thrown or a closure that’s executed if no element is available. Thus, it saves you the annoying checks that make you code full of if/else statements.

If you pass an exception, the exception object is created whether it’s used or not. This is no problem as long as you don’t do that in a loop. Then, create one exception object before the loop and pass only the variable to the methods.

in(): Check if several elements are in the list

To test if an value is in a list of elements with in() isn’t much different than using in_array(). But what if you need to do that several times with different elements? Then, in() takes away the burden of doing that within a loop:

map( ['a', 'b', 'c'] )->in( 'b' ); // true
map( ['a', 'b', 'c'] )->in( ['b', 'a'] ); // true
map( ['a', 'b', 'c'] )->in( ['d', 'a'] ); // false

The in() method of the Map object checks if all elements of the passed array are available in the list and only then it returns true.

toJson(): Encode everything into JSON

When working with APIs, you almost always need to encode the result into its JSON representation. The PHP map object offers a convenient way to transform all elements to JSON:

map( ['a', 'b', ['c', 'd'] )->toJson();

Like the PHP json_encode() method, it accepts a parameter for passing options that are used during encoding the elements. There are two that you may find extremely useful:

map( ['a', 'b', ['c', 'd'] )->toJson( JSON_FORCE_OBJECT|JSON_HEX_QUOT );

JSON_FORCE_OBJECT always creates {}, even for empty lists to avoid being encoded as []. If you add JSON output to HTML data attributes for storing something you need for dynamic Javascript features later on, JSON_HEX_QUOT saves you from generating invalid HTML.

walk(): Visit each value in a multi-dimensional array

You receive a multi-dimensional array from an HTML form and want to make sure that all values are of a certain type or doesn’t contain HTML tags? Then, the walk() method of the PHP Map object is your friend:

map( ['a', 'b', ['c', '<b>d</b>'] )->walk( function( &$val ) {
    $val = strip_tags( $val );
} );

You can also create a mapping based on the list you pass as second parameter:

$mapping = [1 => 'one', 2 => 'two', 3 => 'three', 4 => 'four'];
 
map( [1, 2, [3, 4] )->walk( function( &$val, $key, $data ) {
    $val = $data[$val] ?? $val;
}, $mapping );
 
// Result equals
map( ['one', 'two', ['three', 'four']] )

method(): Register your own methods

The best of all comes last: You can extend the PHP Map object by your own methods! This is extremely handy if you need the same code several times and different places. To register your own method, just do this:

\Aimeos\Map::method( 'strrev', function( $sep ) {
    return strrev( join( '-', $this->list ) );
} );

Your closure function has access to the internal array of elements using $this->list and you can read and/or modify that internal array of the Map object. You can use your new method the same way as any other method of the Map object afterwards:

map( ['a', 'b'] )->strrev( '-' );
// returns "b-a"

Conclusion

The PHP Map object offers some great methods that can simplify your code drastically and you will never want to miss them any more. Especially the possibility to register own methods to extend the Map object dynamically gives your great power in a few lines of code.

Arrays are the working horse of PHP, the programming language used by the vast majority of web applications. An array seems to be incredible simple to use but things get complicated and ugly when PHP functions for array manipulation come into play. Are you tired of hard to read code with excessive error handling too? Then maps can be the answer.

• Documentation at Github
• Composer package at Packagist

Why?

Here’s a common example of how array manipulation is done in most PHP code:

$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

It adds/removes elements, sorts and transforms the content and retrieves the first element. You can’t write that shorter or more elegant and moreover, you need to check almost all array functions for errors.

Using maps

The map composer package offers an easy API comparable to jQuery or Laravel collections:

composer req aimeos/map

When using the Map object, you can do the same as above more elegant with less code:

$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

And contrary to PHP arrays, you don’t have to care about error handling because either, there are no errors possible or the Map object will throw an exception if something is really wrong.

Of course, you can use the Map object still like a plain PHP array:

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

In addition, Map objects allow you to pass anonymous functions to a lot of methods. Thus, you can process and transform the elements according to your current needs, e.g. using the each() method:

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

You can even extend Maps dynamically by own methods. This is especially useful if you need a transformation of the Map elements more often and at several places of your code:

Map::method( 'strrev', function( $sep ) {
    return strrev( join( '-', $this->list ) );
} );
Map::from( ['a', 'b'] )->strrev( '-' );

The best part is using a Map like a jQuery object, where methods are applied to all objects of the Map. Then, you can create expressive code in one line:

class MyClass {
    private $code;
    private $status;
 
    public function __construct( $code ) { $this->code = $code; }
    public function setStatus( $s ) { $this->stat = $s; return $this; }
    public function getCode() { return $this->code; }
}
 
$objects = Map::from( ['a' => new MyClass( 'x' ), 'b' => new MyClass( 'y' )] );
$result = $objects->setStatus( 1 )->getCode()->toArray();

The example will call setStatus( 1 ) on all objects and creates a new Map with the returned values. Because setStatus() returns the same object ($this), we can apply another method on all objects afterwards (getCode()). The results of getCode() is wrapped in a Map object again and toArray() returns a plain PHP array which consists of:

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

Available methods

The Map object contains methods for almost all array functions available and more like collapse(), flat(), toJson() or methods found in the Javascript Array prototype. Here’s a list of its methods and for documentation, have a look at the Map readme at GitHub where you can also check the code.

• function is_map() : Tests if the variable is a map object
• function map() : Creates a new map from elements
• arsort() : Reverse sort elements with keys
• asort() : Sort elements with keys
• chunk() : Splits the map into chunks
• clear() : Removes all elements
• col() : Creates a key/value mapping
• collapse() : Collapses multi-dimensional elements
• concat() : Combines the elements
• copy() : Creates a new copy
• count() : Returns the number of elements
• diff() : Returns the missing elements
• diffAssoc() : Returns the missing elements and checks keys
• diffKeys() : Returns the missing elements by keys
• each() : Applies a callback to each element
• empty() : Tests if map is empty
• equals() : Tests if map contents are equal
• filter() : Applies a filter to the map elements
• find() : Returns the first matching element
• first() : Returns the first element
• firstKey() : Returns the first key
• flip() : Exchanges keys with their values
• flat() : Flattens multi-dimensional elements
• from() : Creates a new map from passed elements
• get() : Returns an element by key
• has() : Tests if a key exists
• in() : Tests if element is included
• includes() : Tests if element is included
• intersect() : Returns the shared elements
• intersectAssoc() : Returns the shared elements and checks keys
• intersectKeys() : Returns the shared elements by keys
• isEmpty() : Tests if map is empty
• join() : Returns concatenated elements as string
• keys() : Returns the keys
• krsort() : Reverse sort elements by keys
• ksort() : Sort elements by keys
• last() : Returns the last element
• lastKey() : Returns the last key
• map() : Applies a callback to each element and returns the results
• merge() : Combines elements overwriting existing ones
• method() : Registers a custom method
• pipe() : Applies a callback to the map
• pop() : Returns and removes the last element
• pull() : Returns and removes an element by key
• push() : Adds an element to the end
• random() : Returns random elements
• reduce() : Computes a value for the map content
• remove() : Removes an element by key
• replace() : Replaces elements recursively
• reverse() : Reverses the array order
• rsort() : Reverse sort elements
• search() : Find the key of an element
• set() : Overwrites an element
• shift() : Returns and removes the first element
• shuffle() : Randomizes the element order
• slice() : Returns a slice of the map
• sort() : Sorts elements
• split() : Splits a string into map elements
• splice() : Replaces a slice by new elements
• toArray() : Returns the plain array
• toJson() : Returns the elements in JSON format
• uasort() : Sorts elements with keys using callback
• uksort() : Sorts elements by keys using callback
• union() : Combines the element without overwriting
• unique() : Returns unique elements
• unshift() : Adds an element at the beginning
• usort() : Sorts elements using callback
• values() : Returns all elements with new keys

Again, the Map documentation offers descriptions, explains parameters/return values and has examples for each method. Some methods are even better documented than the corresponding PHP array function.

Conclusion

Map objects are an easy to use and elegant way to handle PHP arrays. After using it for a while you won’t want to remember the times before. If you’ve already worked with jQuery and like it’s simplicity, you will feel like home when using appropriate lists of objects in your application.

As the Map methods are using the native array functions or are highly optimized, it’s also save to use them in large scale applications. The documentation contains a section about the Map performance and hints to avoid performance bottlenecks.