Download the PHP package derheyne/laravel-list without Composer

A Laravel Collection that guarantees sequential, 0-based integer keys at all times.

Laravel List

ListCollection is a drop-in replacement for Illuminate\Support\Collection that enforces a single invariant: keys are always [0, 1, 2, ...]. Every operation that would otherwise leave gaps re-indexes automatically, and operations that fundamentally produce associative keys throw a BadMethodCallException instead of silently changing the shape of your data.

Why?

Laravel's Collection preserves keys through almost every operation. After filter(), sort(), unique(), or forget() you are typically left with gaps:

This is the right default for a general-purpose collection, but it is the wrong default any time the data is conceptually a list -- an API response, a frontend payload, an indexed sequence, anywhere a "missing" key would be a bug. Defending against it manually means sprinkling ->values() calls through your code and remembering to do so every time.

ListCollection removes that whole class of bug:

Installation

There is no service provider, facade, or configuration. Use the class directly wherever you would use a Collection.

Usage

Creating a list

The constructor and all static factories normalise their input to a sequential list. Associative keys, sparse integer keys, and Collection inputs are all flattened to [0, 1, 2, ...]:

The package also ships a global list_of() helper, the ListCollection analogue of Laravel's collect(). It accepts either a single iterable / Arrayable / Collection, or any number of variadic items:

Filtering, sorting, deduplicating

These all return a new ListCollection with re-indexed keys -- no ->values() required:

Adding, removing, replacing

forget(), prepend(), transform(), pull(), push(), pop(), shift(), and splice() mutate in place. Methods like filter(), map(), sort(), slice(), and concat() return a new instance. This is the same split as Illuminate\Support\Collection.

Setting values by index

offsetSet is constrained to keep the list contiguous. Valid replacement indices are 0 through count($list); anything else appends:

This means $list[$i] = $value is always safe -- it can never punch a hole in the list or create a string key.

Transformations

partition() and chunk() recursively return ListCollection instances, so the invariant holds at every level.

Pulling values

pull() removes an item by index, returns it, and re-indexes the remainder. Defaults can be a value or a closure:

pluck()

pluck() works as usual when you only ask for values:

Calling pluck() with the second $key argument throws a BadMethodCallException, because using one column as keys inherently produces an associative result.

JSON serialisation

Because keys never have gaps, toJson() always produces a JSON array, never an object:

This is the most common reason to reach for ListCollection in a Laravel app -- API responses, resource collections, and frontend payloads stay consistent regardless of what filtering or sorting happens upstream.

Blocked methods

The following methods are blocked with a BadMethodCallException. Each one inherently produces associative keys, so silently re-indexing would discard information the caller asked for:

If you genuinely need one of these shapes, hand the data off to a regular Collection:

All supported Collection methods

Everything else on Illuminate\Support\Collection works and keeps the invariant. A non-exhaustive list:

add, all, chunk, collapse, concat, contains, count, diff, each, every, except, filter, first, firstWhere, flatMap, flatten, forget, get, implode, intersect, isEmpty, isNotEmpty, join, last, map, max, median, merge, min, nth, only, pad, partition, pipe, pluck (without $key), pop, prepend, pull, push, random, reduce, reject, replace, reverse, search, shift, shuffle, skip, skipUntil, skipWhile, slice, sole, some, sort, sortBy, sortByDesc, sortDesc, sortKeys, sortKeysDesc, splice, sum, take, takeUntil, takeWhile, toArray, toJson, transform, unique, unless, values, when, where, whereIn, whereNotIn, zip.

Type safety

ListCollection is annotated as @extends Collection<int, TValue>, so PHPStan and your IDE understand that keys are always int and values keep their type through map(), filter(), pluck(), and friends. The package itself is analysed at PHPStan level: max.

Requirements

• PHP 8.3+
• Laravel 11 or 12

Testing

The test suite runs on PHP 8.3 and 8.4 against Laravel 11 and 12, on both Ubuntu and Windows.

Changelog

Please see CHANGELOG for recent changes.

Contributing

Pull requests are welcome. Please run composer test and composer analyse before opening a PR, and add a Pest test for any new behaviour.

Credits

• Daniel Heyne
• All Contributors

License

The MIT License (MIT). Please see the License File for more information.