aimeos/map turns PHP array plumbing into a call chain

Why PHP Map: one chain instead of six reassignments

The problem is not that PHP lacks array functions. It has array_filter, array_column, sort, reset and count, and they all work. The problem is that they read as a sequence of statements that reassigns the same variable, and each statement hands the next one a bare array with no memory of where it came from.

aimeos/map answers that with an array-like object. Wrap a value in the map() function and you get something you can push onto, remove from, filter, sort and reduce from, and the methods return a map so calls chain left to right. Who it is for is the developer writing PHP 8 code that pulls rows out of a database or a JSON payload and then trims, sorts and reshapes them before rendering. That is exactly the shape of work the README's own before-and-after example describes, and the library is at its best there.

The object also keeps the array interface open, which matters more than the method count. You can still assign into it with $map[] = ..., read it with $map[0], pass it to count(), and walk it with foreach( $map as $key => $value ). Nothing about the data becomes opaque, so a Map can sit inside code that knows nothing about the library.

The chain collapses six array statements into one expression

The README puts the same task side by side twice, and the comparison is the clearest description of the design. Starting from a list that holds two associative rows and a null, the first version appends an element, unsets index 0, runs array_filter, sorts, pivots into pairs with array_column, then calls reset and coalesces to null.

The second version does all of it as a single expression on a map:

$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 f

Read the method names as the array functions they stand in for: filter removes falsy entries, sort is the sort, col is the column pivot, first is the first value of the resulting map. Many methods also accept a callback, so the filtering step can be as narrow as you like rather than relying on PHP truthiness:

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

That callback support is the part that separates this from a thin wrapper. Operations PHP has no built-in for, grouping or keying or flattening, are all reachable in the same chain as the ones it does have.

The jQuery-style proxy silently needs setStatus() to return $this

Given a map of objects, you can call a method on every element at once and keep chaining on the results. The README's example takes two instances of a class whose setStatus() returns $this and whose getCode() was set in the constructor:

$map->setStatus( 1 )->getCode()->toArray();

setStatus( 1 ) runs on both objects. Because each one returns $this, the intermediate map still holds the same two MyClass instances, and getCode() then runs on those, producing ['a' => 'x', 'b' => 'y'].

Here is the detail worth reading twice: the chaining works because the method happens to return $this. If setStatus() returned void, the same line would have nothing to call getCode() on. The README states the return requirement in a comment on the sample class rather than as a rule. That is a failure mode to keep in mind for anyone who tries the trick on a class written without the collection in mind. Read the target class before you rely on this.

The method list carries near-duplicate names that widen the API surface

The table of contents is long enough to be worth reading as a design signal. It lists both a map function and a map method, both contains and includes, and a full set of both mutating and non-mutating sort variants: sort, sorted, asort, asorted, arsort, arsorted, ksort, ksorted, krsort, krsorted. Add diff, diffAssoc and diffKeys, or intersect, intersectAssoc and intersectKeys, and the pattern is clear. For the sort operations the library offers a version that changes the map in place and a version that returns a new one.

That is a defensible design, since it removes the guesswork about whether a call mutated your variable. It is also a lot of names to learn before you can predict what a call does. If your team is new to the library, the sorted() family is the part worth mapping out first, because the difference between the pair is exactly the question you have to ask about every other method.

The repository layout supports the same impression from the other side. It carries phpstan.neon.dist and phpunit.xml at the root alongside composer.json, and a continuous integration config in .circleci, so the type and test scaffolding is part of the project rather than something a maintainer runs by hand.

composer req aimeos/map and the first chain

Installation is one command, taken from the README:

composer req aimeos/map

That is the whole setup. There is no service to register, no configuration file to write and no key to obtain. What you should see afterwards is a vendor directory containing the package and a composer.json that now requires aimeos/map.

A chain that ends in a value like first() hands you a scalar; one that ends in a transformation hands back a Map. toArray() turns that into the plain array the surrounding code expects.

One detail matters for anything shipping this internally: the package is MIT licensed, so its terms attach no copyleft obligation to code that depends on it.

PHP 8 on the default 4.x branch, PHP 7.1 only on 3.x

The README splits supported runtimes by branch: PHP 8 or newer for 4.x, PHP 7.1 or newer for 3.x. The repository default branch is 4.x, so a fresh install lands on the PHP 8 requirement. A codebase still on PHP 7.x has to hold the older line, and there is no annotated version to point at in that decision.

Where the gap bites is when you cross a branch boundary. Without published release notes you cannot tell from the repository alone whether a given commit changed a return type, dropped one method from the long list, or tightened a signature. The README does carry an upgrade guide in its table of contents, which is the place to look before moving between 3.x and 4.x, but the packaged view of what changed over time does not exist. Budget for reading the diff across the branches you cross.

One more constraint belongs here rather than in a footnote. Because a transformation returns a map rather than a bare array, code that hands those results to functions typed for arrays needs toArray() at the boundary. Nothing in the library enforces that for you.

Where Laravel Collections and the built-in functions take a different route

Laravel Collections solve the same reshaping problem, and aimeos/map describes itself as offering the jQuery and Laravel collection style. The difference in approach is where the object comes from. Laravel Collections are part of the framework and arrive through the container alongside the Eloquent models and the service layer that produces your data, so adopting them costs a framework dependency. aimeos/map is a standalone package with no framework, no container and no configuration, and the default branch is 4.x on PHP 8.

The other honest alternative is to stay on PHP's own array functions. They cost nothing to install, they never need a conversion back to a plain array, and every PHP developer already knows them. The case against them is syntactic rather than functional: a sequence of array_filter, array_column and reset calls reassigns one variable repeatedly, and that is the exact shape the library's chain replaces.

If your arrays are small and reshaped once, the built-ins win and the Map object is overhead. If the same array is pushed, filtered, sorted, pivoted and reduced in one place, the chain pays for itself in readability. Decide on the shape of the code you already have, not on the size of the method list.

Editorial conclusion

Adopt aimeos/map in application code that repeatedly reshapes array data and wants the result back as a plain array: push, filter, sort, col and first read as one intention instead of six reassignments of the same variable. Skip it in library code that should stay on PHP's built-in functions, and skip the jQuery-style proxy entirely unless every target class returns $this from the method you chain onto. Check the PHP runtime first, because the default 4.x branch refuses anything below PHP 8 and the 3.x line is the only path for a 7.x codebase.

Frequently asked questions

Official sources

1. aimeos/map on GitHub
2. Issues
3. License: MIT
4. Project website
5. README