Php Engine Utils Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require event-engine/php-engine-utils
   

   Add to composer.json under require or require-dev if needed.

2. First Use Case: The package primarily provides utility classes like MapIterator and Callback for common PHP operations. Start with:

   use EventEngine\Utils\MapIterator;
   
   $array = ['a' => 1, 'b' => 2, 'c' => 3];
   $iterator = new MapIterator($array, fn($key, $value) => "Key: $key, Value: $value");
   
   foreach ($iterator as $item) {
       echo $item . "\n";
   }
   

3. Where to Look First:

   • src/: Core utility classes (e.g., MapIterator, Callback).
   • Tests: /tests/ for usage examples and edge cases.
   • README: Minimal docs, but releases highlight fixes (e.g., MapIterator improvements).

Implementation Patterns

Core Workflows

1. Transforming Traversable Objects: Use MapIterator to apply callbacks to arrays, Traversable, or generators without manual loops:

   $users = collect([['name' => 'Alice'], ['name' => 'Bob']]);
   $names = new MapIterator($users, fn($user) => $user['name']);
   

2. Callback Utilities: Leverage Callback for reusable logic (e.g., validation, transformations):

   use EventEngine\Utils\Callback;
   
   $validateName = Callback::create(fn($name) => strlen($name) > 3);
   $validateName('Alice'); // Returns true
   

3. Integration with Laravel:

   • Service Providers: Register utilities as singletons:

     $this->app->singleton(MapIterator::class, fn() => new MapIterator([]));
     

   • Collections: Chain with Laravel’s Collection:

     $collection->map(fn($item) => $item)->all(); // Replace with MapIterator for custom logic.
     

4. Generators and Lazy Loading: Use MapIterator with generators to avoid loading large datasets:

   $generator = (function() {
       yield 1;
       yield 2;
   })();
   
   $iterator = new MapIterator($generator, fn($item) => $item * 2);
   

Gotchas and Tips

Pitfalls

1. MapIterator Traversable Quirks:

   • BC Breaks: Versions 0.1.1–0.1.2 changed MapIterator from \Iterator to \Traversable and back. Ensure your code handles both:

     if (!$iterator instanceof \Iterator) {
         $iterator = new \ArrayIterator(iterator_to_array($iterator));
     }
     

   • Double Callback Calls: Pre-0.1.3, callbacks fired twice. Test with:

     $calls = 0;
     $iterator = new MapIterator([1, 2], fn() => $calls++);
     iterator_to_array($iterator); // $calls should be 2 (pre-0.1.3) or 1 (post).
     

2. PHP 8+ Compatibility:

   • Test with PHP 8.0+ (package supports it, but edge cases may exist). Use strict types if needed:

     /** @var \Traversable $traversable */
     $iterator = new MapIterator($traversable);
     

3. Performance:

   • MapIterator with generators is lazy but may cause memory issues with deep recursion. Limit generator depth or use iterator_to_array() for finite datasets.

Debugging Tips

• Callback Errors: Wrap callbacks in try-catch to avoid silent failures:

  $iterator = new MapIterator($data, function($item) {
      try {
          return process($item);
      } catch (\Throwable $e) {
          report($e);
          return null;
      }
  });
  

• Iterator Validation: Check for valid() method before rewinding:

  if (method_exists($iterator, 'valid')) {
      $iterator->rewind();
  }
  

Extension Points

1. Custom Iterators: Extend MapIterator for domain-specific logic:

   class UserMapIterator extends MapIterator {
       public function __construct(array $users) {
           parent::__construct($users, [$this, 'transformUser']);
       }
   
       public function transformUser($user) {
           return (object) $user; // Auto-convert to object.
       }
   }
   

2. Callback Composition: Combine callbacks for complex pipelines:

   $pipeline = Callback::create(fn($data) => $data)
       ->then(fn($data) => strtolower($data))
       ->then(fn($data) => ucfirst($data));
   $pipeline('HELLO'); // Returns "Hello".
   

3. Testing: Mock MapIterator in tests to isolate logic:

   $this->partialMock(MapIterator::class, ['__invoke'])
       ->shouldReceive('__invoke')
       ->andReturn('mocked');