Amp Laravel Package

Getting Started

Install amphp/amp and revolt/event-loop via Composer. Start with simple Amp\async() + Amp\delay() examples to grasp coroutine execution. The minimal working example in the README (using Amp\async() and Amp\delay(5)) is the ideal first use case — it demonstrates non-blocking concurrency without callbacks or generators. Verify your environment: PHP ≥8.1, no required extensions (though revolt/event-loop must be explicitly required).

Implementation Patterns

• Sequential-ish code with concurrent side-effects: Write code as if synchronous ($result = $future->await();) but trigger independent I/O in parallel via Amp\async() before awaiting.
• Combinators for batch I/O: Use Future\await() to trigger many requests concurrently (e.g., HTTP calls, DB queries), then await all at once — ideal for microservice aggregation or batch data fetching. Prefer awaitAll() when you need per-result error isolation, or awaitAny()/awaitFirst() for timeouts/fallbacks.
• Wrapping blocking code: For legacy or ext-based blocking operations, use Amp\async() inside a cancellable scope to avoid process-wide lock. Combine with amphp/parallel for true thread-level offloading.
• Custom Futures with DeferredFuture: Only for low-level abstractions (e.g., integrating non-Amp socket libraries). Avoid passing DeferredFuture around — keep it local to the operation creator.

Gotchas and Tips

• Fibers ≠ threads: Only one fiber runs at a time. Blocking calls (sleep(), stream_socket_client(), fgets()) still freeze the entire process. Replace all blocking I/O with Amp/Revolt-aware alternatives (e.g., Amp\delay(), ByteStream streams).
• No await() outside coroutine context: Future::await() only works inside Amp\async() callbacks or Revolt event-loop hooks. For CLI scripts, wrap top-level logic in Amp\async() and call Amp\async()->await().
• Event loop lifecycle traps: Scripts exit immediately if no suspended coroutines remain. Always ensure your top-level operation (e.g., server start, batch job) keeps the loop alive — use Future\await() at the end.
• Error propagation is strict by default: await() aborts on the first error in the iterable. Use awaitAll() or catch() on individual futures for graceful failure handling.
• finally() is your debugging friend: Attach ->finally(fn() => error_log('completed')) to futures for tracing async control flow — crucial since stack traces are truncated across suspension points.
• Extensions matter at scale: While amphp/amp itself needs no extensions, exceed ~1000 concurrent sockets? Install revolt/event-loop with PECL extensions (e.g., event, libevent, ev) for scalability.