Promises Laravel Package

Getting Started

Start by installing the package: composer require guzzlehttp/promises. The core concept is simple: Promise objects represent asynchronous operations. Begin by creating a promise, attaching callbacks via then(), and resolving it manually (e.g., $promise->resolve('value')). For immediate values or rejections, use FulfilledPromise and RejectedPromise instead of manually creating promises. The most common first use case is to wrap synchronous logic in a promise for testing or to prepare for async extensions—like mocking API responses that could be async later.

Implementation Patterns

• Manual Promise Wrapping: Wrap blocking I/O (e.g., file reads, DB queries) in promises using the constructor’s $waitFn to trigger resolution. This enables uniform handling of sync and async flows.
• Chaining for Composability: Use then() extensively to build pipelines—return new promises or values to chain operations. Rely on rejection forwarding (return new RejectedPromise(...)) to propagate errors cleanly.
• Coroutine Promises: Use Coroutine::of() for async/await-style code—this leverages yield inside a generator to write asynchronous logic that reads synchronously.
• Integration with Guzzle HTTP: While guzzle/promises is standalone, it’s tightly integrated with guzzlehttp/guzzle. In custom HTTP clients or async workers, use Utils::queue()->run() periodically in event loops (e.g., ReactPHP) to resolve pending promises.
• Testing Strategy: Replace real promises in tests with FulfilledPromise/RejectedPromise to force deterministic behavior and avoid timing issues.

Gotchas and Tips

• Stack Safety: Although iteration avoids stack overflow, then callbacks must not block indefinitely—otherwise, wait() hangs. Always set timeouts or integrate with event loops via Utils::queue().
• Unwrapping Behavior: By default, wait(true) throws for rejections or unwraps nested promises. Use wait(false) if you only need to ensure resolution (e.g., cleanup), and check state manually via getState().
• Cancellation Dependencies: Cancelling a promise only works if you provided a $cancelFn during construction. If you wrap third-party code (e.g., curl multi), ensure cancellation propagates to the underlying operation.
• Promise Interop: While then() works with foreign promises (e.g., ReactPHP), wait()/cancel() won’t propagate across implementations. Wrap external promises with new Promise(fn) if you need synchronous control or cancellation.
• Task Queue is Crucial: In non-blocking event loops, always run Utils::queue()->run() on each loop tick—otherwise, promises never resolve, even if their data is ready. For Swoole or ReactPHP, this is non-negotiable.
• Rejection Reasons Matter: Rejecting with non-Exception values (e.g., strings, arrays) causes wait() to throw RejectionException. Always throw real Exceptions for cleaner error handling in production.