Block React Laravel Package

Getting Started

Start by installing via Composer: composer require clue/block-react. This library is not a standalone tool—it's a bridge to allow ReactPHP-based async components (like HTTP clients, databases, or sockets) to be used in synchronous, blocking contexts (e.g., CLI scripts, traditional PHP apps, or Laravel jobs). Use it when you want to call async ReactPHP code immediately and synchronously—like echo $loop->run($asyncPromise);. Begin with the Loop class: it manages the ReactPHP event loop for the duration of your blocking call and cleans up afterward.

Implementation Patterns

• CLI Scripts: Wrap ReactPHP async operations (e.g., HttpClient, Filesystem) in a closure passed to Block\run().

  use Clue\Block;
  
  $result = Block\run(function () {
      $loop = React\EventLoop\Loop::get();
      $client = new React\Http\Client($loop);
      $promise = $client->get('https://api.example.com/data');
      return $promise;
  });
  

• Laravel Jobs/Commands: Use inside handle() or execute() to perform async I/O (e.g., call external APIs, write to Redis) without resorting to pcntl_fork or Guzzle promises in blocking mode.
• Testing: Wrap async ReactPHP calls in Block\run() inside PHPUnit tests to assert on their results synchronously.
• Avoid Manual Loop Management: Prefer Block\run() over manually instantiating Loop—it handles automatic cleanup and reentrant loop behavior.

Gotchas and Tips

• Deprecation Warning: As of PHP 8.1+, preg_replace_callback with null in subject is deprecated—some older ReactPHP components may trigger this; ensure all dependencies are modern.
• Reentrant Loops: clue/block-react uses Loop::run() internally, which may cause issues if you manually start another loop elsewhere in the same process (e.g., Laravel Octane + ReactPHP). Avoid overlapping loops.
• Timeouts Matter: Long-running async operations will block your PHP script indefinitely. Always use Block\withTimeout() to add safety:

  $result = Block\run(function () use ($loop) {
      return (new React\Promise\Timer\Timeout::Promise(
          $someAsyncOperation(),
          5.0,
          $loop
      ));
  });
  

• No Async in Web Contexts: Do not use this in HTTP requests under FPM/Apache—it blocks the worker thread. Reserved for CLI, queue workers, or short-lived processes.
• Fallback Loop: If ReactPHP’s loop is already running (e.g., in Swoole), Loop::get() may return a non-reentrant loop—check environment compatibility.
• Deadlock Risk: Calling Block\run() recursively (e.g., inside a run() callback that itself calls run()) causes deadlocks—avoid this pattern.