Parallel Laravel Package

Getting Started

Install via Composer: composer require mehr-als-nix/parallel. Then, for CLI jobs (e.g., Artisan commands, pipelines), instantiate a Manager, add Worker instances wrapping your callback logic, call execute(), and read results via getResult() on each worker after completion. Start with the example.php in the repo—copy it into your project and adjust paths/callbacks. Critical first check: Confirm you're running CLI (php -r 'echo SAPI_NAME;' → cli) and that pcntl is enabled (php -m | grep pcntl). If not, tasks run silently in serial with a warning.

Implementation Patterns

• Batch Task Parallelization: Wrap independent I/O-bound operations (e.g., HTTP requests, DB calls, file downloads) in closures passed to Worker. Group them into a Manager and execute in parallel to reduce total runtime (e.g., fetching 100 remote endpoints in 2s instead of 10s).
• Controlled Concurrency: Call $manager->setMaxProcesses($count) to cap workers (e.g., avoid overwhelming an external API). Useful when auto-detection overcommits resources or in shared dev environments.
• Robust Error Handling: Enclose worker callbacks in try { ... } catch (\Throwable $e) { throw new \RuntimeException('...', 123); }—exceptions are caught per-worker and stored. After execute(), iterate workers, check getReturnCode() and getError(), and decide (e.g., retry, log, skip).
• Stateless Workers: Pass serializable data (arrays, scalars) into closures; avoid sharing mutable objects, closures with bound scope, or DB connections. Return only necessary data—no side effects in parent process.
• Iterative Results: Use foreach ($manager as $worker) (both interface styles preserve insertion order), but remember: results may be ready out-of-order. Sort if sequence matters.

Gotchas and Tips

• PCNTL is non-negotiable: No pcntl? Parallelism disabled—silently falls back to serial execution with E_USER_NOTICE. Many PHP-FPM/Docker/cloud environments (e.g., Laravel Vapor, Forge) disable pcntl by default—test in production-like envs early.
• Apache/FPM = no parallelism: Even if pcntl exists, running via web server (e.g., Nginx → PHP-FPM) triggers degraded mode. Always run via CLI (php artisan my:command).
• No shared memory: $obj->prop = 'x' inside a worker does not affect the parent. Treat workers as black-box processes—use return values and serialization for data flow.
• Order ≠ Completion: Workers execute concurrently but are iterated in insertion order; late-completing tasks cause bottlenecks. Monitor via getError() and avoid blocking callbacks.
• Process slots are naive: Per TODO, only the oldest slot waits before spawning next—long-running first task stalls others. Mitigate by sorting workers (long → short) or capping concurrency.
• Debugging tip: Use pcntl_fork()-like var_dump(['pid' => getmypid(), 'worker' => $i]) inside workers to verify forking. Compare PIDs to confirm true parallelism (not sequential).
• Not production-ready: Unmaintained since 2017 (no PHP 8+, Laravel 9+ guarantees), 0 dependents, missing IPC (STDOUT/STDERR TODO unresolved). For any critical workload, use spatie/async, react/promise, or Laravel Horizon instead. Reserve this for throwaway CLI tools or legacy maintenance.