Promise Timer Laravel Package

Getting Started

Install with composer require react/promise-timer. Import the functions early using use function React\Promise\Timer\{timeout, sleep}; to get idiomatic PHP syntax. Your first use case will likely be adding timeouts to async HTTP clients, database queries, or third-party API calls in an event-loop-driven Laravel application (e.g., when using Laravel Octane with Swoole or ReactPHP-based workers). Wrap an existing promise (e.g., from guzzle/promises or a custom async operation) with timeout($promise, 5.0) to enforce a 5-second limit.

Implementation Patterns

• Client-side timeouts: Combine with Guzzle promises or Laravel’s async HTTP client wrappers:
  timeout($guzzlePromise, 3.0)->then(...)->catch(TimeoutException::class, ...).
• Periodic background tasks: Use sleep() to debounce or stagger async operations inside loop workers (e.g., queue consumers or Swoole coroutines).
• Batch coordination: Use timeout(all($promises), 10.0) to ensure a group of operations finishes within a deadline; cancellation propagates to child promises if exceeded.
• Graceful cancellation: Store and call $timeoutPromise->cancel() in Laravel’s finally blocks or onStop handlers to abort lingering operations during shutdown.
• Typed error handling (ReactPHP v3): Prefer catch(TimeoutException $e) over instanceof checks when using ReactPHP v3’s modern promise API.

Gotchas and Tips

• Loop propagation: Avoid manually passing LoopInterface unless you’re explicitly managing non-default loops (e.g., multiple reactors); omitting the third argument uses ReactPHP’s default loop, which integrates cleanly with Laravel’s event-loop integrations.
• Cancellation isn’t automatic: timeout() tries to cancel the inner promise, but cancellation support depends on the underlying promise implementation (e.g., Guzzle promises support it; raw new Promise() callbacks require manual cleanup via $resolver(function($resolve, $reject) { ... }, function() { /* cleanup here */ })).
• Deprecated functions: Skip resolve()/reject()—use sleep($time) for simple delays; resolve($time) returned the duration as a value, but sleep() resolves void and aligns better with standard async semantics.
• Negative/zero time: Passing 0.0 or negative values still spawns a timer; the earliest execution depends on the event loop (often ~1ms). Use Loop::futureTick() for zero-delay scheduling instead.
• Testing: Mock timeout()/sleep() in unit tests by injecting a custom promise resolver; for integration tests, inject a test loop (e.g., EvenLoop\Factory::create()) to control timing.