Iter Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require php-standard-library/iter
   

   Add to composer.json under require:

   "php-standard-library/iter": "^6.2"
   

2. First Use Case: Replace a simple foreach loop with iter():

   use Iter\Iter;
   
   $numbers = [1, 2, 3, 4, 5];
   $doubled = Iter::from($numbers)
       ->map(fn($n) => $n * 2)
       ->toArray();
   // Result: [2, 4, 6, 8, 10]
   

3. Where to Look First:

   • Documentation for API reference.
   • Iter\Iter class methods (e.g., map, filter, reduce, chunk).
   • Example workflows in the README.

Implementation Patterns

Usage Patterns

1. Lazy Evaluation Pipelines: Process iterables without materializing intermediate results:

   $result = Iter::from($largeDataset)
       ->filter(fn($item) => $item['active'])
       ->map(fn($item) => $item['id'])
       ->chunk(100)
       ->toArray();
   

2. Generator Integration: Work seamlessly with PHP generators:

   function fetchUsers(): Generator {
       yield ['id' => 1, 'name' => 'Alice'];
       yield ['id' => 2, 'name' => 'Bob'];
   }
   
   $activeUsers = Iter::from(fetchUsers())
       ->filter(fn($user) => $user['active'])
       ->toArray();
   

3. Composable Transformations: Chain operations like map/filter/reduce:

   $total = Iter::from($orders)
       ->filter(fn($order) => $order['status'] === 'completed')
       ->map(fn($order) => $order['amount'])
       ->reduce(fn($carry, $amount) => $carry + $amount, 0);
   

4. Laravel-Specific Workflows:

   • Eloquent: Process cursor results lazily:

     $users = User::query()->cursor();
     $names = Iter::from($users)->pluck('name')->toArray();
     

   • API Resources: Transform collections:

     $resources = Iter::from($posts)
         ->map(fn($post) => new PostResource($post))
         ->toArray();
     

5. Batch Processing: Use chunk for memory-efficient batching:

   Iter::from($largeArray)
       ->chunk(500)
       ->each(fn($chunk) => processBatch($chunk));
   

Workflows

1. Data Cleaning:

   $cleaned = Iter::from($rawData)
       ->filter(fn($item) => !empty($item['value']))
       ->map(fn($item) => sanitize($item['value']))
       ->toArray();
   

2. Nested Iterables: Flatten or transform nested structures:

   $flat = Iter::from($nestedArray)
       ->flatten()
       ->map(fn($item) => $item * 2);
   

3. Conditional Aggregation:

   $stats = Iter::from($logs)
       ->groupBy(fn($log) => $log['level'])
       ->map(fn($group) => count($group))
       ->toArray();
   

Integration Tips

1. Type Safety: Use PHP 8.1+ return types for clarity:

   /** @return array<int, int> */
   public function getDoubled(array $numbers): array {
       return Iter::from($numbers)
           ->map(fn($n) => $n * 2)
           ->toArray();
   }
   

2. Error Handling: Wrap pipelines in try-catch for robustness:

   try {
       $result = Iter::from($generator)
           ->map(fn($item) => riskyOperation($item))
           ->toArray();
   } catch (Throwable $e) {
       Log::error('Pipeline failed', ['error' => $e->getMessage()]);
   }
   

3. Performance:

   • Prefer toArray() only when needed (materializes the iterable).
   • Use each() for side effects without intermediate storage:

     Iter::from($items)->each(fn($item) => $item->save());
     

4. Testing: Mock generators in unit tests:

   $mockGenerator = $this->createMock(Generator::class);
   $mockGenerator->method('getIterator')->willReturn(new ArrayIterator([1, 2, 3]));
   
   $result = Iter::from($mockGenerator)->sum();
   $this->assertEquals(6, $result);
   

Gotchas and Tips

Pitfalls

1. Lazy Evaluation Surprises:

   • Pipelines are lazy; operations like toArray() or sum() trigger execution.
   • Debugging: Add tap() to inspect intermediate states:

     Iter::from($data)
         ->tap(fn($i) => Log::debug('After filter:', $i->toArray()))
         ->filter(...);
     

2. Generator Exhaustion:

   • Generators can only be iterated once. Recreate or store results if needed:

     $generator = fetchData();
     $firstPass = Iter::from($generator)->filter(...)->toArray();
     $secondPass = Iter::from(fetchData())->map(...); // Re-fetch
     

3. Type Inconsistencies:

   • Mixed iterables (e.g., ArrayObject + Generator) may require explicit casting:

     $iterable = new ArrayObject([1, 2, 3]);
     $result = Iter::from(iterator_to_array($iterable))->sum();
     

4. Memory Leaks:

   • Avoid holding references to large lazy iterables in class properties or closures:

     // Bad: Holds reference to unevaluated generator
     class Processor {
         private $iterable;
         public function __construct(Generator $generator) {
             $this->iterable = Iter::from($generator); // Unevaluated!
         }
     }
     

5. PHP 8.1+ Dependencies:

   • Uses iterable return types and named arguments. Ensure your project targets PHP 8.1+.

Debugging Tips

1. Inspect Iterables: Use toArray() or tap() to debug:

   Iter::from($data)
       ->tap(fn($i) => dd($i->toArray()))
       ->filter(...);
   

2. Stack Traces: Lazy pipelines may obscure errors. Add context:

   try {
       $result = Iter::from($data)
           ->map(fn($item) => $item->invalidMethod())
           ->toArray();
   } catch (Throwable $e) {
       throw new RuntimeException(
           "Pipeline failed at step 'map': " . $e->getMessage(),
           0,
           $e
       );
   }
   

3. Performance Profiling: Compare lazy vs. eager operations:

   // Lazy (memory-efficient)
   $lazySum = Iter::from($largeArray)->sum();
   
   // Eager (materializes)
   $eagerSum = array_sum($largeArray); // May crash with OOM
   

Config Quirks

1. Global Helpers: The package doesn’t auto-register helpers. Add manually if desired:

   // In AppServiceProvider
   if (!function_exists('iter')) {
       function iter(iterable $iterable): Iter\Iter {
           return Iter\Iter::from($iterable);
       }
   }
   

2. Custom Iterators: Extend Iter\Iter for domain-specific logic:

   class UserIter extends Iter\Iter {
       public function active(): self {
           return $this->filter(fn($user) => $user->active);
       }
   }
   

3. Configuration: No runtime config. All behavior is method-based (e.g., Iter::from($data)->...).

Extension Points

1. Custom Methods: Add domain-specific operations:

   Iter::from($users)
       ->map(fn($user) => $user->fullName())
       ->filter(fn($name) => str_contains($name, 'Admin'))
       ->toArray();
   

2. Integration with Laravel:

   • Service Provider:

     public function register() {
         $this->app->singleton('iter', fn() => new Iter\Iter());
     }
     

   • Facade:

     // app/Facades/Iter.php
     namespace App\Facades;
     use Illuminate\Support\Facades\Facade;
     class Iter extends Facade {
         protected static function getFacadeAccessor()