Vec Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require php-standard-library/vec
   

   No configuration required—just autoload and use.

2. First Use Case: Replace raw arrays with Vec for safer, expressive operations:

   use PhpStandardLibrary\Vec;
   
   $users = Vec::fromArray(['Alice', 'Bob', 'Charlie']);
   $names = $users->map(fn($name) => strtoupper($name));
   // Returns Vec(['ALICE', 'BOB', 'CHARLIE'])
   

3. Where to Look First:

   • API Docs (hypothetical)
   • Vec::fromArray(), Vec::empty(), and core methods (map, filter, reduce).

Implementation Patterns

Core Workflows

1. Functional Pipelines: Chain operations for declarative data processing:

   $result = Vec::fromArray([1, 2, 3, 4, 5])
       ->filter(fn($n) => $n % 2 === 0)
       ->map(fn($n) => $n * 2)
       ->reduce(0, fn($sum, $n) => $sum + $n);
   // Returns 12 (2+4+6)
   

2. Immutable Operations: Use push(), pop(), or splice() to avoid side effects:

   $vec = Vec::fromArray([1, 2, 3]);
   $newVec = $vec->push(4); // Original remains unchanged
   

3. Laravel Integration:

   • Collections: Convert Laravel Collections to Vec for specialized ops:

     $laravelCollection = collect([1, 2, 3]);
     $vec = Vec::fromArray($laravelCollection->toArray());
     

   • Service Layer: Use Vec in DTOs or domain objects for explicit intent:

     class UserList {
         public function __construct(private Vec $users) {}
     }
     

4. Validation: Replace manual array checks with Vec assertions:

   $vec = Vec::fromArray([1, 2, 3]);
   $vec->assertNotEmpty(); // Throws if empty
   

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • Vec is optimized for clarity, not raw speed. Benchmark before use in hot paths (e.g., loops).
   • Avoid converting back to arrays unnecessarily:

     // Bad: Unwrapping repeatedly
     $array = $vec->toArray();
     $array = array_map(...);
     
     // Good: Chain Vec methods
     $vec->map(...)->filter(...);
     

2. Indexing Quirks:

   • Vec enforces 0-based, contiguous indexing. Sparse arrays (e.g., [1 => 'a']) may behave unexpectedly.
   • Use Vec::fromAssoc() for associative-like data (though it’s not a primary use case).

3. Laravel-Specific:

   • Collection Compatibility: Not all Laravel Collection methods are mirrored. Stick to Vec's API for consistency.
   • Service Container: Bind Vec interfaces to implementations if extending:

     $this->app->bind(VecInterface::class, fn() => new Vec());
     

Debugging Tips

1. Type Hints: Use Vec in method signatures to enforce usage:

   public function process(Vec $items): Vec { ... }
   

2. Immutable Debugging: Log intermediate Vec states to trace transformations:

   $vec->tap(fn($v) => Log::debug($v->toArray()));
   

3. Common Errors:

   • OffsetExistsException: Caused by accessing invalid indices. Use get() with a default:

     $vec->get(10, null); // Returns null instead of throwing
     

   • Method Chaining: Ensure each method returns a Vec (e.g., map does, but toArray() doesn’t).

Extension Points

1. Custom Methods: Extend Vec via traits or decorators:

   trait VecExtras {
       public function chunk(int $size): Vec {
           return Vec::fromArray(array_chunk($this->toArray(), $size));
       }
   }
   

2. Laravel Service Providers: Register Vec as a global helper:

   Vec::macro('greet', fn() => Vec::fromArray(['Hello', 'Vec!']));
   // Usage: Vec::greet()->implode(' ');
   

3. Testing: Use Vec::empty() for test fixtures and assert with:

   $this->assertEquals(Vec::fromArray([1, 2]), $result);