Spatie Async

Spatie Async is a small, focused PHP library that wraps the PCNTL and POSIX extensions to run code across multiple parallel processes. It provides an ergonomic Pool API — add closures or Task objects, attach then/catch/timeout callbacks, and wait for results — so CPU- or IO-heavy work can be spread across the operating system’s process scheduler.

Built on top of symfony/process, it spawns child PHP processes, communicates results back to the parent via serialized output and SIGCHLD signal handling, and transparently falls back to synchronous execution when the required extensions are unavailable. The result is a dependency-light way to add real parallelism to plain PHP scripts and long-running jobs.

What You Get

• A fluent Pool API with concurrency, timeout, autoload, and sleep-time configuration
• Per-process then(), catch(), and timeout() event callbacks
• Functional async()/await() helper functions as an alternative to the Pool object
• A Task base class for child processes that need setup (containers, config) before running
• Automatic synchronous fallback when pcntl/posix extensions are unavailable

Common Use Cases

• Fan out many independent HTTP requests or API calls and collect responses in parallel
• Process large batches of records or files across multiple CPU cores
• Speed up data crunching or report generation by splitting work into concurrent tasks
• Run isolated jobs that need their own bootstrapped environment via Task objects

Under The Hood

Architecture - The core is the Pool class (src/Pool.php), which maintains queues of Runnable processes and enforces a concurrency limit. Work is wrapped as ParallelProcess objects that fork via ParentRuntime/ChildRuntime (src/Runtime); each child bootstraps an autoloader, deserializes the closure with laravel/serializable-closure, runs it, and writes serialized output back to the parent. The parent listens on the SIGCHLD signal to detect completion and dispatches then/catch/timeout callbacks through the ProcessCallbacks trait.

Tech Stack - Pure PHP 8.3+ targeting the pcntl and posix extensions, built on symfony/process for spawning and managing child processes and laravel/serializable-closure for shipping closures across the process boundary. Tests use Pest/PHPUnit, and code style is enforced with php-cs-fixer.

Code Quality - The codebase is small, cohesive, and well-namespaced (Spatie\Async), with a clear split between Pool orchestration, Process abstractions, Runtime forking, and Output/exception handling. A dedicated tests/ suite (Feature tests plus fixture classes for exceptions and tasks) covers success, failure, timeout, and synchronous-fallback paths.

API Design - The public surface is deliberately tiny and fluent: Pool::create() plus add(), then(), catch(), timeout(), and wait(), mirrored by async()/await() helpers. Getting started takes only a few lines, exception handling reads naturally through type-hinted catch callbacks, and the automatic synchronous fallback keeps code portable across environments without the extensions.