Collection Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require php-standard-library/collection
   

   No additional configuration is required—just autoload the package.

2. First Use Case:

   use PhpStandardLibrary\Collection\Vector;
   use PhpStandardLibrary\Collection\Map;
   
   // Immutable Vector (fixed-size, ordered)
   $immutableVector = Vector::of(1, 2, 3);
   
   // Mutable Map (key-value, dynamic)
   $mutableMap = new Map();
   $mutableMap->put('name', 'John');
   $mutableMap->put('age', 30);
   

3. Where to Look First:

   • API Docs: Focus on Vector, Map, and Set classes in the PhpStandardLibrary\Collection namespace.
   • Immutable vs Mutable: Decide early whether you need thread-safe immutability or mutable operations.
   • Type Safety: Leverage PHP 8.1+ generics (e.g., Vector<int>) for compile-time checks.

Implementation Patterns

Core Workflows

1. Data Transformation:

   $numbers = Vector::of(1, 2, 3);
   $doubled = $numbers->map(fn($n) => $n * 2); // Immutable
   $mutableDoubled = $numbers->toMutable()->map(fn($n) => $n * 2); // Mutable
   

2. Filtering and Reduction:

   $evenNumbers = $numbers->filter(fn($n) => $n % 2 === 0);
   $sum = $numbers->reduce(0, fn($acc, $n) => $acc + $n);
   

3. Nested Collections:

   $nestedMap = new Map();
   $nestedMap->put('users', Vector::of(
       Map::of('id' => 1, 'name' => 'Alice'),
       Map::of('id' => 2, 'name' => 'Bob')
   ));
   

4. Interoperability with Laravel:

   // Convert Laravel Collection to/from package collections
   $laravelColl = collect([1, 2, 3]);
   $packageVector = Vector::fromArray($laravelColl->toArray());
   

Integration Tips

• Dependency Injection: Bind the package’s collections to Laravel’s container for consistency:

  $this->app->bind(Vector::class, fn() => Vector::empty());
  

• Custom Types: Use Map::of() or Vector::of() with objects for structured data:

  $user = Map::of(
      'id' => 1,
      'roles' => Vector::of('admin', 'user')
  );
  

• Performance: Prefer Vector for ordered, indexed data (O(1) access) and Map for key-value lookups (O(log n) for immutable, O(1) for mutable).

Gotchas and Tips

Pitfalls

1. Immutable vs Mutable Confusion:

   • Immutable collections return new instances on modification (e.g., map(), filter()).
   • Mutable collections modify the original instance (e.g., toMutable()->put()).
   • Fix: Explicitly convert between types with toImmutable()/toMutable().

2. Type Inference Limits:

   • PHP’s generics are nominal; avoid mixing Vector<int> with Vector<string> in the same context.
   • Fix: Use @var annotations or IDE hints for complex cases.

3. Lazy Evaluation:

   • Some methods (e.g., filter()) return lazy iterators. Force evaluation with toArray() or reduce() if needed.

4. Laravel Collection Overlap:

   • Avoid mixing Laravel’s Collection with this package’s collections in the same pipeline (e.g., laravelColl->merge($packageMap) may fail).
   • Fix: Convert explicitly:

     $packageMap = Map::fromArray($laravelColl->toArray());
     

Debugging Tips

• Inspect Structure:

  $map->inspect(); // Dumps the entire structure (useful for debugging)
  

• Check Immutability: Use isImmutable() to verify collection type before operations.

Extension Points

1. Custom Predicates: Create reusable closures for filtering:

   $isEven = fn($n) => $n % 2 === 0;
   $numbers->filter($isEven);
   

2. Serialization: Implement JsonSerializable for custom objects stored in Map/Vector:

   class User implements JsonSerializable {
       public function jsonSerialize() { ... }
   }
   $map->put('user', new User());
   

3. Performance Tuning: For large datasets, prefer mutable operations (e.g., toMutable()->putAll()) over immutable chains.

Config Quirks

• No Built-in Config: The package is framework-agnostic. Configure type hints or aliases in your IDE (e.g., PHPStorm) for autocompletion.