Promise Laravel Package

Getting Started

Install via Composer: composer require react/promise. This package is dependency-free and requires only PHP 7.4+, making it lightweight for integration into any project—even non-ReactPHP ones. Start by importing the namespace: use React\Promise;. The most immediate use case is wrapping synchronous or asynchronous operations in a promise: use React\Promise\resolve($value) or React\Promise\reject($reason) to create promises inline. For asynchronous tasks, instantiate React\Promise\Deferred, return its promise, and control resolution via resolve() or reject() from your async logic (e.g., event loop callbacks or I/O operations). The README’s examples are concise and worth studying first.

Implementation Patterns

• Delegating I/O: Wrap non-blocking operations (e.g., HTTP clients, database queries, or ReactPHP streams) in Deferred promises. Keep the Deferred private and return only the promise to callers to enforce encapsulation of resolution authority.
• Promise chaining & composition: Use then() for transformations, catch() for error recovery (with type-hinting for granular error handling), and finally() for cleanup (e.g., closing connections, logging). Example: $promise->then($mapper)->catch($errorHandler)->finally($cleanup) mimics synchronous try/catch/finally.
• Bulk operations: Leverage Promise\all(), Promise\race(), and Promise\any() to orchestrate multiple concurrent promises. All three support cancellation—calling cancel() on the aggregate promise cancels all child promises (e.g., aborting parallel HTTP requests).
• Async-to-sync bridges: Use Promise\resolve($value) to normalize mixed synchronous/asynchronous return values (e.g., caching layer fallbacks) without duplicating logic.
• Laravel integration: Wrap Eloquent or external API calls in promises within jobs, queue workers, or route controllers. Combine with React\EventLoop for non-blocking I/O in CLI tools or custom workers—especially useful when building high-concurrency APIs.

Gotchas and Tips

• Unhandled rejections: Rejected promises left uncaught (no then($null, $onRejected), catch(), or finally()) will emit warnings via the rejection handler when garbage-collected. Always attach a rejection handler—use set_rejection_handler() globally for custom logging (e.g., to Monolog) if needed.
• Type hints matter: In catch() callbacks, type-hinting (e.g., catch(function (\PDOException $e) {})) ensures only matching errors are caught; others propagate. Avoid catching \Throwable too early unless you intend to swallow all errors.
• No automatic resolution of promises in return values: If your then() handler returns a PromiseInterface, it auto-wraps (chains). But if you forget and return a plain value or forget to return from your handler, you may get unexpected state transitions—explicitly return in then() callbacks.
• Avoid circular references: When using closures in deferred cancellers (especially with $this), be mindful of object lifecycle—use unset() or closures without use where possible to avoid memory leaks in long-running processes.
• Extension point: Custom promise implementations: Though Promise is final, any class implementing PromiseInterface can be used interchangeably (e.g., Laravel’s PendingPromise wrappers). This enables testing with fake promises: ->then(fn() => 'fake').
• Not framework-specific: Despite being low-level, it integrates cleanly with Laravel by wrapping async logic in service classes or jobs—no need for service providers unless adding global helpers.