Collection Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require loophp/collection
   

   No configuration required—just autoload via Composer.

2. First Use Case Convert an array to a Collection and chain operations:

   use Loophp\Collection\Collection;
   
   $users = ['Alice', 'Bob', 'Charlie'];
   $collection = Collection::from($users);
   
   // Basic filtering
   $filtered = $collection->filter(fn($name) => strlen($name) > 3);
   $filtered->all(); // ['Alice', 'Charlie']
   

3. Key Entry Points

   • Collection::from($array) – Convert arrays/iterables.
   • Collection::make() – Create empty collection.
   • $collection->all() – Get underlying array (eager evaluation).

Implementation Patterns

Lazy Evaluation

Leverage lazy operations to avoid memory spikes:

// Process 1M records without loading all at once
$largeData = Collection::from(range(1, 1_000_000));
$sum = $largeData->map(fn($x) => $x * 2)->sum(); // No intermediate array

Modular Workflows

Break logic into reusable chunks:

// User processing pipeline
$users = Collection::from($dbUsers)
    ->filter(fn($u) => $u['active'])
    ->map(fn($u) => UserModel::fromArray($u))
    ->groupBy(fn($u) => $u->role);

Integration with Laravel

Replace Laravel’s Collection for custom logic:

// Override Laravel’s Collection in a service provider
app()->bind(Collection::class, fn() => new Loophp\Collection\Collection());

// Use in controllers
public function index()
{
    return Collection::from($this->userRepository->all())
        ->pluck('name')
        ->toJson();
}

Custom Iterators

Extend for domain-specific needs:

class UserCollection extends Collection
{
    public function activeOnly(): self
    {
        return $this->filter(fn($user) => $user->isActive());
    }
}

Gotchas and Tips

Pitfalls

1. Double Evaluation Lazy chains reset on each call. Cache intermediate results:

   // ❌ Risky: Re-evaluates on each call
   $filtered = $collection->filter(...);
   $mapped = $filtered->map(...); // Re-filters!
   
   // ✅ Safe: Materialize early
   $filtered = $collection->filter(...)->all();
   $mapped = Collection::from($filtered)->map(...);
   

2. Memory Leaks Avoid mixing lazy and eager operations:

   // ❌ Memory hog: Converts to array too early
   $collection->map(...)->all()->filter(...);
   

3. Laravel Collisions If using both Collection classes, alias one:

   use Loophp\Collection\Collection as LooCollection;
   use Illuminate\Support\Collection as LaravelCollection;
   

Debugging Tips

• Inspect State: Use ->toArray() to debug intermediate steps.
• Performance: Profile with memory_get_usage() before/after operations.
• Custom Methods: Override __toString() for debugging:

  class DebugCollection extends Collection
  {
      public function __toString()
      {
          return print_r($this->all(), true);
      }
  }
  

Extension Points

1. Custom Aggregators Add domain-specific methods:

   Collection::macro('avgAge', function() {
       return $this->sum('age') / $this->count();
   });
   

2. Lazy File Handling Stream large files without loading entirely:

   $lines = Collection::from(fopen('large.csv', 'r'))
       ->map(fn($line) => str_getcsv($line))
       ->filter(fn($row) => $row[0] === 'active');
   

3. Database Integration Use with Eloquent for lazy queries:

   $users = User::query()->get()->toCollection()
       ->filter(fn($u) => $u->posts()->count() > 0);