Event Loop Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require revolt/event-loop
   

   Requires PHP 8.1+.

2. Basic Event Loop Initialization:

   use Revolt\EventLoop\EventLoop;
   
   $loop = EventLoop::get();
   $loop->run();
   

3. First Use Case: Non-blocking HTTP Requests

   $suspension = EventLoop::getSuspension();
   $response = $suspension->suspend(fn() => file_get_contents('https://example.com'));
   echo $response;
   

Where to Look First

• Official Documentation – Covers core concepts, API reference, and extensions.
• Examples Directory – Practical use cases (HTTP clients, WebSockets, timers).
• EventLoop Class – Central interface for managing the loop lifecycle, suspensions, and error handling.

Implementation Patterns

Core Workflows

1. Fiber-Based Concurrency

• Pattern: Use EventLoop::getSuspension() to yield control back to the loop.
• Example:

  $suspension = EventLoop::getSuspension();
  $data = $suspension->suspend(fn() => fetchDataFromDatabase());
  // Process `$data` while other fibers run.
  

2. Timers and Periodic Tasks

• Pattern: Schedule one-time or repeating tasks.
• Example:

  $loop = EventLoop::get();
  $timer = $loop->addTimer(1.0, fn() => echo "Task completed after 1 second\n");
  

3. Error Handling

• Pattern: Centralize error handling via setErrorHandler.
• Example:

  EventLoop::get()->setErrorHandler(fn(Throwable $e) => error_log($e->getMessage()));
  

4. Fiber-Local Storage

• Pattern: Store context per fiber (e.g., logging, request IDs).
• Example:

  $fiberLocal = new FiberLocal();
  $fiberLocal->set('request_id', uniqid());
  // Accessible in other fibers via `$fiberLocal->get('request_id')`.
  

5. Integration with Laravel

• Pattern: Use Revolt in Laravel’s service providers or console commands.
• Example:

  // In a service provider:
  public function boot()
  {
      $loop = EventLoop::get();
      $loop->addTimer(5.0, fn() => $this->scheduleCleanup());
  }
  

Integration Tips

• Avoid Blocking Calls: Replace sleep() with $loop->addTimer().
• Leverage Suspensions: Wrap blocking operations (e.g., file_get_contents, DB queries) in suspensions.
• Use Extensions: For high-performance I/O (e.g., revolt/uv), install via:

  pecl install revolt-uv
  composer require revolt/uv
  

Gotchas and Tips

Pitfalls

1. Unresumed Suspensions

   • Issue: Forgetting to resume suspensions causes memory leaks.
   • Fix: Always resume suspensions or use try-finally:

     $suspension = EventLoop::getSuspension();
     try {
         $result = $suspension->suspend(fn() => blockingCall());
     } finally {
         $suspension->resume();
     }
     

2. Fiber Destruction Order

   • Issue: PHP 8.4+ may crash if fibers are destroyed in the wrong order.
   • Fix: Avoid manual fiber destruction; let the event loop manage it.

3. Callback Ordering

   • Issue: Callbacks may execute out of order if not queued properly.
   • Fix: Use EventLoop::queue() for microtasks or addTimer for delayed execution.

4. Serialization Warnings

   • Issue: Serializing the loop driver throws an exception.
   • Fix: Never serialize/deserialize EventLoop instances.

5. PCNTL Dependencies

   • Issue: Some drivers (e.g., uv) require pcntl extensions.
   • Fix: Enable pcntl or use the select driver as a fallback.

Debugging Tips

• Stack Traces: Enable EventLoop::setErrorHandler to log uncaught exceptions with stack traces.
• Suspension Inspection: Use EventLoop::getSuspension()->getStackTrace() to debug hanging fibers.
• Driver Selection: Check available drivers with:

  print_r(EventLoop::getAvailableDrivers());
  

Extension Points

1. Custom Drivers

   • Implement Revolt\EventLoop\Driver\DriverInterface for custom I/O backends.

2. Decorators

   • Wrap the event loop to add middleware (e.g., logging, metrics):

     $loop = new Decorator(EventLoop::get(), new LoggingMiddleware());
     

3. Fiber Hooks

   • Override Fiber::start() or Fiber::suspend() for custom behavior.

Laravel-Specific Quirks

• Service Container: Register the loop in a provider:

  $this->app->singleton(EventLoop::class, fn() => EventLoop::get());
  

• Queue Workers: Use Revolt for long-running queue jobs to avoid timeouts:

  $loop = EventLoop::get();
  $loop->addTimer(60, fn() => $this->processQueue());
  $loop->run();