Async Laravel Package

Getting Started

Start by installing via Composer: composer require react/async. This package provides simple, non-blocking async utilities for ReactPHP-based applications—ideal for building high-performance event-driven systems like CLIs, microservices, or HTTP servers using ReactPHP. The first practical use case is replacing sleep() with React\Async\delay() for non-blocking pauses during retries or polling logic. Next, use await() inside an async() callback to flatten promise-heavy code (e.g., sequential HTTP calls with React\Http\Browser). For example:

use function React\Async\{async, await};
use React\EventLoop\Loop;

Loop::addTimer(0, async(function () {
    $browser = new React\Http\Browser();
    $response = await($browser->get('https://httpbin.org/get'));
    echo $response->getBody();
}));

Check the official README usage examples and verify your environment uses ReactPHP’s event loop—this package does not convert blocking code (like sleep(), file_get_contents(), or PDO) to async; non-blocking libraries are required.

Implementation Patterns

• Sequential Operations: Use await() inside an async() function for linear async workflows (e.g., sequential DB queries or API calls).
• Concurrent Execution: Combine await() with React\Promise\all() or allSettled() to parallelize independent promises (e.g., fetching multiple user profiles).
• Generator-Based Coroutines: Use coroutine() with yield for cleaner syntax than .then() chains (especially in nested loops or error-handling scenarios).
• Event Loop Integrations: Wrap event loop callbacks (Loop::addTimer, stream events, HTTP request handlers) with async() to safely use await() without stalling the loop.
• Error Handling & Cancellation: Leverage try/catch around await(); cancel pending promises via promise->cancel() when aggregating (e.g., cancel outstanding HTTP requests on failure). Async fibers automatically propagate cancellation up the chain.

Gotchas and Tips

• Blocking Code ≠ Async: await() won’t fix sleep(), stream_socket_client(), or database calls that block the loop. Use non-blocking alternatives (e.g., React\Promise\Timer for delays, React\Http\Browser for HTTP, and event-driven DB libraries).
• async() vs await(): await() blocks within the current fiber; async() only prevents external blocking. A function using await() must be wrapped in async() when used as a loop timer/callback.
• Cancellation Behavior: Canceling a promise returned by async() or coroutine() propagates cancellation to all awaited promises inside its scope—ensure child promises support cancellation (most ReactPHP ones do).
• Return Type Mismatch: await() throws UnexpectedValueException if a promise rejects with a non-Throwable (e.g., plain string). Prefer rejecting with Exceptions.
• Fiber Misconceptions: This is not PHP fibers (HP Fibers extension). It simulates async flow control via generators and promises—ideal for existing ReactPHP ecosystems but not a full coroutine system.
• Debugging Tip: Use Loop::debug() to inspect pending timers/events—helpful when delay() or await() unexpectedly stalls output.