# aimeos/map: PHP arrays and collections made easy

> aimeos/map turns plain PHP arrays into a chainable collection object, jQuery and Laravel style. It is a small MIT-licensed library for PHP 8+, and the README is honest that it costs performance compared with native array functions.

**aimeos/map** — PHP arrays and collections made easy

- Repository: https://github.com/aimeos/map
- Website: http://php-map.org
- Stars: 4,326 · Forks: 16
- Language: PHP
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/aimeos-map

## The array-filtering boilerplate aimeos/map replaces

The problem is not that PHP arrays are hard. It is that a short sequence of operations on one array turns into five statements that each reassign the same variable. The README opens with exactly that contrast: build a list, append an element, unset an index, call array_filter to drop empties, sort, call array_column to build a keyed array, then reset to get the first value. Seven lines, one intent. The map version expresses the same intent as a single chain: map($list)->push(...)->remove(0)->filter()->sort()->col('value', 'id')->first().

The audience follows from that. This is for application code where arrays carry domain data and the transformations matter more than microsecond timings: building response payloads, reshaping rows from a query, grouping and aggregating before rendering. It is also for developers coming from Laravel Collections or jQuery who want the same chaining style without pulling in a framework. The README states the goal plainly in its title: easy and elegant handling of PHP arrays by using an array-like collection object as offered by jQuery and Laravel Collections. If your project is a tight numeric loop over a million elements, this is not the tool, and the README says so indirectly by giving performance its own section.

## How the Map object works, including the jQuery-style method forwarding

A Map is an object wrapping an array. It implements ArrayAccess, Countable and IteratorAggregate, which is why the README can show $map[] = ..., $map[0], count($map) and foreach ($map as $key => $value) still working after you switch from an array. The functional entry points are two helpers: map() and Map::from(), plus is_map() for checks. Methods fall into groups the README names itself: create, access, add, aggregate, debug, order, shorten, test, mutate and misc.

The unusual mechanism is __call and __callStatic. If your elements are objects, calling a method that Map does not define forwards that call to every element. The README's example builds a map of MyClass instances and calls setStatus(1)->getCode()->toArray(). setStatus(1) runs on both objects; if it returns $this, the new map still holds the two objects, and then getCode() runs on each, producing ['a' => 'x', 'b' => 'y']. Two rules are implied by that example and worth stating: the forwarded method should return $this for chaining to continue, and a method that returns something else replaces the map contents with those return values. That is a real design decision, not a convenience. A typo in a forwarded method name does not fail at parse time; it fails at call time on every element. The README does not document a guard against that in the excerpt.

## Installing aimeos/map and running a first chain

Installation is one Composer command, and it pulls the package from Packagist. The README gives it as composer req, the short form of composer require.

```bash
composer req aimeos/map
```

Version choice is tied to your PHP runtime. The README lists PHP 8+ for the 4.x branch and PHP 7.1+ for 3.x, and the default branch in the repository is 4.x. If you are on PHP 7, you need the 3.x line, and the README points to an upgrade guide for moving between majors.

The first real use is the README's own example, reshaped into a runnable script. It builds a list with a null entry, pushes one more row, removes index 0, drops empty values, sorts, builds a value-keyed array with col(), and takes the first value.

```php
$list = [['id' => 'one', 'value' => 'value1'], ['id' => 'two', 'value' => 'value2'], null];
$value = map( $list )
    ->push( ['id' => 'three', 'value' => 'value3'] )
    ->remove( 0 )
    ->filter()
    ->sort()
    ->col( 'value', 'id' )
    ->first();
```

What you should see is a single scalar in $value, not an array. The README comments the col() step as producing ['three' => 'value3'], which tells you the key comes from the id field and the value from the value field, the same argument order as array_column. If you want to inspect intermediate state instead of the final scalar, the method list includes dump() and dd(), grouped under debug.

Callbacks are accepted in many methods. The README shows each() taking an anonymous function with $val and $key, and the same shape applies wherever a callback is documented: the value first, the key second.

## Where aimeos/map is the wrong choice

The README has a Performance section in its table of contents, which is a signal in itself: the authors consider the cost worth addressing rather than hiding. Every chain allocates a Map object, and each step in the chain produces another one unless the method mutates in place. The method list makes that distinction explicit by pairing names: sort and asort mutate, while sorted and asorted return new maps, and the same pattern repeats for ksort/ksorted and krsort/krsorted. If you chain the non-mutating variants on a large array, you are copying data at every step.

The second limitation is type. Map works on arrays and on objects whose methods you forward. It is not a typed collection: nothing in the README suggests element types are enforced, so a Map of mixed rows is as possible as it is with a plain array. The is* test methods (isList, isObject, isNumeric, isScalar, isString) inspect contents rather than constrain them.

The third is scope. If your project already depends on Laravel, its Collection class is already loaded and offers the same chaining style; adding a second collection implementation means two vocabularies for one job. And if your array code is three lines in one place, the wrapper adds a dependency and an indirection for no readability gain. The README's own before-and-after example is seven statements against one chain, which is the threshold where the trade pays off.

## aimeos/map against Laravel Collections and plain array functions

The obvious alternative is Laravel's Illuminate\Support\Collection, and the README names it as an inspiration. The difference in approach is packaging and reach. Collection ships with the framework and is coupled to it; aimeos/map is a standalone Composer package that the README describes as offering the same array-like object style, so it fits a Slim, Symfony or legacy project where pulling in Illuminate\Support is a heavier decision than one small dependency. Method names overlap heavily (filter, sort, first, map, each, chunk, groupBy, flatten, collapse), but they are not guaranteed identical in argument order or edge-case behaviour, and the README does not publish a mapping table. If you migrate between the two, check each method you use.

The other alternative is no library at all: native array functions. The README's opening example is the honest comparison, and it cuts both ways. Native functions are faster and have zero install cost, but the sequence is imperative, the intermediate state is visible in every line, and mistakes like forgetting array_values after a filter are easy to make. aimeos/map trades that speed for a chain that reads top to bottom. The README also notes that Map keeps array semantics: append, index access, count and foreach all still work, so the two styles can coexist in one file without a rewrite.

## Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-07-07. The default branch is 4.x, which matches the PHP 8+ line the README documents; the 3.x line covers PHP 7.1+. There is a CircleCI configuration in .circleci/ and a coverage badge in the README, so continuous integration is part of the repository layout, and phpstan.neon.dist and phpunit.xml sit at the top level, which indicates static analysis and a test suite are configured. The README does not state a release cadence or a support window for 3.x.

The licence is MIT, per the repository metadata and the licence badge in the README. In practical terms MIT permits commercial and closed-source use; the obligation that usually matters is retaining the copyright and permission notice with the distributed source. That is a general description of the licence, not legal advice for your situation.

Upgrade cost is the item to price before adopting. The README links an upgrade guide, which implies breaking changes between majors exist. The PHP version split is the clearest one: a project on PHP 7.1 cannot run 4.x, and a project that upgrades PHP must then move the library to 4.x and follow that guide. Because Map forwards unknown method calls to elements, a missing method after an upgrade can surface at runtime rather than at install time, so the upgrade guide is the document to read before bumping the constraint in composer.json.

## Conclusion

Adopt aimeos/map if your codebase is full of nested array_filter, array_column and reset calls and you want them readable as one chain, and if you are on PHP 8+ with Composer already in the project. Do not adopt it for hot loops or large data sets: the README itself points readers to its performance section, and a wrapper object per chain is not free. Before committing, verify two things on your own code: that your PHP version matches the branch you install (4.x needs PHP 8+, 3.x supports PHP 7.1+), and that the methods you rely on exist under the names you expect, since the method list is long and the README does not document every one of them in the excerpt. The licence is MIT, so the main obligation is keeping the copyright notice with the source.

## FAQ

### What is aimeos/map used for?

It wraps a PHP array in a Map object so you can chain operations like push, remove, filter, sort and col instead of writing separate array functions and reassigning the variable. The README positions it as array-like handling in the style of jQuery and Laravel Collections.

### How do I install aimeos/map?

The README gives a single Composer command, composer req aimeos/map, which fetches the package from Packagist. Which version you get depends on your PHP runtime: 4.x requires PHP 8+ and 3.x supports PHP 7.1+.

### Does aimeos/map work without Laravel?

Yes. It is a standalone Composer package, and the README describes it as offering the array-like collection object style used by jQuery and Laravel Collections rather than depending on the framework. That is the main reason to pick it over Illuminate\Support\Collection in a non-Laravel project.

### Can I still use array syntax and foreach with aimeos/map?

The README states you can still append with $map[] = ..., read $map[0], call count($map) and iterate with foreach ($map as $key => $value). The Map class implements ArrayAccess, Countable and IteratorAggregate to make that work.

## Sources

- [aimeos/map on GitHub](https://github.com/aimeos/map)
- [Issues](https://github.com/aimeos/map/issues)
- [License: MIT](https://github.com/aimeos/map/blob/4.x/LICENSE)
- [Project website](http://php-map.org)
- [README](https://github.com/aimeos/map/blob/4.x/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/aimeos-map