Skip to main content

​
What is Laravel List?

Laravel List is a lightweight Laravel package that provides ListCollection, a specialized collection class that enforces sequential 0-based integer keys (0, 1, 2, 3…) at all times. It extends Laravel’s powerful Collection class while guaranteeing true list behavior.

​
The Problem It Solves

Laravel’s standard Collection class is incredibly versatile, but this flexibility can lead to unexpected behavior when you need predictable, sequential keys: 
use Illuminate\Support\Collection;

$collection = collect([1, 2, 3, 4, 5]);
$filtered = $collection->filter(fn($v) => $v > 2);

// Unexpected: Keys are preserved from original collection
$filtered->all(); // [2 => 3, 3 => 4, 4 => 5]

// Problems arise:
$filtered[0]; // null (key 0 doesn't exist!)
$filtered->toJson(); // {"2":3,"3":4,"4":5} (JSON object, not array)
With ListCollection, keys are automatically reindexed after every operation: 
use dhy\LaravelList\ListCollection;

$list = new ListCollection([1, 2, 3, 4, 5]);
$filtered = $list->filter(fn($v) => $v > 2);

// Keys are always sequential
$filtered->all(); // [0 => 3, 1 => 4, 2 => 5]
$filtered[0]; // 3 (predictable access)
$filtered->toJson(); // [3,4,5] (JSON array)

​
Key Features

Automatic Reindexing

All operations that modify keys automatically reindex to maintain sequential 0-based keys. No manual values() calls needed.

Laravel Collection API

Extends Laravel’s Collection class, so you get all the familiar methods like map(), filter(), sort(), and more.

Type-Safe

Full PHP 8.3+ type hints and generics support with PHPStan for robust, maintainable code.

Predictable JSON

Always serializes to JSON arrays, never objects. Perfect for APIs and frontend integration.

Protection from Associative Operations

Methods that would produce associative keys (like flip(), groupBy(), keyBy()) throw exceptions to prevent misuse.

Zero Configuration

Works out of the box with Laravel 11+ and PHP 8.3+. No configuration files or migrations required.

​
When to Use Laravel List

Use ListCollection when you need:
  • Predictable sequential array keys
  • JSON arrays (not objects) for API responses
  • List-like behavior similar to Python lists or JavaScript arrays
  • Protection against accidental associative key operations
Stick with standard Collection when you need:
  • Associative arrays with custom keys
  • Key preservation across operations
  • Methods like groupBy(), keyBy(), or flip()

​
Real-World Example

Imagine building an API endpoint that returns a filtered list of active users: 
use dhy\LaravelList\ListCollection;

public function getActiveUsers()
{
    $users = User::all(); // Eloquent Collection
    
    // Convert to ListCollection for guaranteed list behavior
    $activeUsers = new ListCollection($users)
        ->filter(fn($user) => $user->active)
        ->map(fn($user) => [
            'id' => $user->id,
            'name' => $user->name,
            'email' => $user->email,
        ])
        ->sortBy('name');
    
    // Always returns JSON array with sequential keys
    return response()->json($activeUsers);
    // Output: [{"id":1,"name":"Alice",...},{"id":3,"name":"Bob",...}]
}

​
Get Started

Installation

Install Laravel List via Composer and get up and running in seconds.

Quickstart

Learn the basics with a hands-on example that demonstrates core functionality.

Core Concepts

Understand how Laravel List maintains sequential keys and which methods are supported.

Build docs developers (and LLMs) love

Get started for freeTalk to us