Laravel Parallel Laravel Package

Getting Started

Install with Composer (auto-discovery registers the service provider):

composer require recca0120/laravel-parallel

Before writing any code, verify the runtime can actually fork — this package leans on pcntl and posix, which are Unix-only and frequently disabled on shared hosting:

php -m | grep -E 'pcntl|posix'

If either is missing, plan a sequential fallback (see Gotchas). Windows is a non-starter.

Minimal first use case — run independent closures concurrently and collect results in order:

use Recca0120\LaravelParallel\Facades\Parallel;

$results = Parallel::run([
    fn () => DB::table('users')->count(),
    fn () => DB::table('orders')->sum('total'),
    fn () => Http::get('https://api.example.com/health')->json(),
]);

Where to look first:

1. The Parallel facade/class and its config (concurrency, timeout, polling/sleep).
2. The underlying spatie/async Pool docs — that engine dictates the semantics you'll actually live with.
3. Then move the call into a php artisan command or a dedicated App\Support\ParallelRunner service instead of leaving it inline in a controller.

Best first real use case: a report/aggregate command or a cache-warming job where you fan out N independent pieces of work and join the results.

Implementation Patterns

• Fan-out/fan-in in console commands. Split an import, report, or crawler workload into N closures, cap concurrency, aggregate. This is the natural home for the package — fork overhead is trivial against the work being parallelized.
• Wrap it in a runner service. Create ParallelRunner::run(array $tasks) so controllers and jobs stay thin, and so you can swap a sequential implementation in tests without pcntl.
• Concurrency cap is the main knob. Set Parallel::concurrency(5) (or the config default) to roughly min(CPU cores, DB pool size, target API's rate limit). Oversubscribing turns parallel into thrash.
• Pair with the queue for durability. Use this package for in-process fan-out of latency/CPU-bound work; keep Bus::batch/queues for retryable, durable jobs. Don't treat Parallel::run as a queue substitute.
• Always set a timeout. Especially for HTTP or external services — a slow child otherwise parks the pool. Combine a per-task timeout with a sane poll/sleep interval and inspect partial results for nulls/errors.
• Structured task results. Have each closure return ['ok' => true, 'data' => ...] (or ['ok' => false, 'error' => ...] on catch) so one failure doesn't collapse into an ambiguous null in the results array.
• Key results back to input. The pool returns results indexed by task id; zip them against your original task list rather than assuming array order. Chunk large inputs — array_map(fn ($c) => fn () => process($c), $chunks) trades memory for fewer forks.
• Closures inherit the container. app(), facades, and injected services resolve inside children — but from the snapshot taken at fork time (see Gotchas).

Gotchas and Tips

• Fork, not thread — nothing propagates back. DB connections, logger state, singleton mutations, config() writes, and static properties are per-child copies. Reconnect the DB inside each task if you see "server has gone away" or "packets out of order" — children inherit an already-open PDO handle.
• Return values must be serializable. Resources (PDO, streams, file handles), closures, and objects holding them will break or silently become null crossing the IPC boundary. Return scalars, arrays, or plain DTOs.
• Per-task error handling is on you. A fatal in a child can look like a missing result. Wrap each closure in try/catch and encode the exception (message + stack) into the return payload.
• pcntl_fork is Unix-only. Gate CI and production; add a sequential fallback for Windows laptops and hosts where the extension is disabled. Never let unit tests depend on pcntl.
• Process exhaustion is real. Each task is a real OS process. Nested parallelism (a task that itself calls Parallel::run) multiplies the count and can hit RLIMIT_NPROC, container PID caps, or memory limits. Keep concurrency ≤ CPU cores for CPU-bound work.
• Memory duplication via copy-on-write. Large datasets pre-loaded in the parent are essentially duplicated per child the moment they're touched. Load data inside the closure or chunk it instead of capturing giant arrays.
• Debugging output interleaves. dd()/dump()/echo from children land on the shared TTY and mix together. Log with a task id on a dedicated channel (Log::channel('parallel')->info("[task {$id}] ...")) and capture stack traces in the returned payload.
• Container is a fork-time snapshot. Services already resolved and cached with once()/singletons reflect parent state. If correctness matters, rebind or re-resolve inside the task rather than trusting the inherited instance.
• Timeout + sleep are the two config quirks to confirm. Dump config('parallel') to see effective defaults; override per call (->concurrency(), timeout) on hot paths instead of changing the global config.
• Watch the release cadence. Last release 2024-05-03 — pin the version and re-read the spatie/async changelog on every upgrade, since pool behavior defines this package's semantics more than its own README does.