Promise Laravel Package

Getting Started

Start by understanding that this package provides a lightweight PSR-18-compatible Promise interface for handling asynchronous HTTP operations—commonly used as a bridge between HTTPlug and PSR-18/PSR-7 ecosystems. If you’re building or consuming async HTTP clients (e.g., with Guzzle 7+, Symfony HttpClient, or custom adapters), this promise enables you to write non-blocking code without bloating dependencies.

First use case: you have a PSR-18 client and want to make multiple requests concurrently. You wrap each client call in a Http\Promise\Promise (or Http\Promise\FulfilledPromise/RejectedPromise) and use Promise::when() or async() methods to resolve them collectively.

Check src/Promise.php, src/FulfilledPromise.php, and src/RejectedPromise.php for core classes. Readme docs are minimal—look at usage in dependencies like php-http/discovery or php-http/guzzle6-adapter for real-world integration.

Implementation Patterns

• Async Request Chains: Use promises to sequence HTTP calls without blocking:

  $promise = new Promise(function () use ($client, $request) {
      $response = $client->sendRequest($request);
      return $response->getStatusCode();
  });
  $promise->then(function ($status) { /* handle */ });
  

• Futures / Concurrency: Combine multiple requests using Promise::when() to resolve when all complete:

  $promises = array_map(function ($url) use ($client, $requestFactory) {
      $request = $requestFactory->createRequest('GET', $url);
      return new Promise(function () use ($client, $request) {
          return $client->sendRequest($request);
      });
  }, $urls);
  $results = Promise\when($promises)->wait();
  

• Adapter Layer: Use in HTTP client adapters (e.g., async Guzzle, ReactPHP, Swoole) to convert callback-based APIs into a standardized promise chain.
• Testing: In unit tests, stub Promise with FulfilledPromise/RejectedPromise to simulate success/failure paths without real network calls.

Gotchas and Tips

• No native async I/O: This package does not perform actual async I/O—it’s a promise abstraction; actual concurrency depends on the underlying client (e.g., Guzzle’s HandlerStack with multi-handle). Don’t expect ReactPHP-like behavior unless the client supports it.
• wait() blocks synchronously: Calling $promise->wait() halts execution until resolved. Use it only in CLI scripts or explicit async integrations.
• Exception safety: Rejections are typically \Exception objects—always handle rejections via then(null, $onRejected) or await() with try/catch.
• Integration with Laravel: Rarely used directly in app code. Typically幕后 in HTTP client packages (e.g., Laravel’s Http facade doesn’t use it), but important when developing Laravel packages that need PSR-18/HTTPlug async compatibility.
• No async middleware: This isn’t an HTTP middleware—it’s a promise wrapper. Pair it with PSR-15/HTTPlug middleware if you need request interception/logic.
• Upgrade caution: v2.0+ uses native Throwable in signatures—ensure your then() callbacks expect both \Exception and \Throwable.