Thread Laravel Package

Getting Started

Start by not starting. amphp/thread is archived, has had no release since 2014-09-09, and its own description points you at amphp/parallel. There is no day-to-day leverage to gain here in a modern Laravel codebase — the realistic first use case is removing it, not adopting it.

Before you write any code, establish why the package is in the tree at all:

1. composer why amphp/thread — find the transitive dependency or the forgotten require.
2. composer show amphp/thread — confirm you are on the 2014 line.
3. grep -R "Amp\\\\Thread\|amphp/thread" app/ config/ routes/ — find actual call sites vs. dead weight.
4. Check the runtime it assumes: php -v, php -m | grep -i pthreads, and whether your PHP is ZTS (php -i | grep Thread). This package rode on ext-pthreads, which requires a ZTS build. Official php Docker images, Laravel Sail, Herd, and Valet are almost all NTS. If pthreads is not loaded, the package cannot work at all.

If you genuinely must run legacy code that depends on it (e.g. an old CLI worker script), isolate it in a dedicated container pinned to the matching PHP version, run it only from artisan/CLI, and never load it in the HTTP or queue worker process.

The correct first "use case" to learn instead is amphp/parallel (v2, fiber-based) for in-process-style parallelism via worker processes, or plain Laravel queues for anything that can tolerate latency. For CPU-bound fan-out, Illuminate\Process / Symfony\Process is usually the pragmatic choice.

Implementation Patterns

Treat this package as a migration source, not an integration target. The patterns below are what you actually ship.

Adapter-first extraction. Wrap every call site behind a small interface (HeavyTaskRunner::run(callable $job, array $args)) so the legacy thread implementation and the replacement are swappable. The old API is built around spawning a worker that executes a serializable payload and returns a serializable result — mirror that contract exactly so the swap is mechanical.

Replace with amphp/parallel worker pools. For parallel CPU work:

• Define a Task implementing Amp\Parallel\Worker\Task.
• Submit through a Worker\ContextWorkerPool / Worker\WorkerPool.
• Keep inputs and outputs scalar/array-serializable; no closures, no Eloquent models, no open PDO handles crossing the boundary.
• Drive the event loop from an artisan command (Amp\Loop::run(...) / Amp\async on Amp v3), never from a controller inside FPM.

Replace with Laravel queues when possible. Most jobs people reached for threads to solve are better as dispatch() on a Horizon/Redis queue: retries, backoff, observability, and no ZTS build. Reserve true parallelism for sub-second fan-out where queue latency is unacceptable.

Replace with subprocesses for isolation. Process::run([...]) (or Symfony\Process) gives you crash isolation that pthreads never did. Good for image/PDF tooling, external binaries, and anything that might segfault.

Batch fan-out pattern. A common real-world shape: fetch N remote resources or run N CPU jobs, collect results, write once. With amphp/parallel, submit all tasks to the pool, Future\awaitAll, then persist in the parent process. With Laravel, Bus::batch([...])->dispatch() and use then() for the writeback. Both keep DB connections out of workers.

Integration tip: if you run Octane or a long-lived queue worker, do not spawn workers per request/loop iteration without a bounded pool — you will exhaust memory and file descriptors. Use a pool with a fixed size tied to nproc.

Gotchas and Tips

• ZTS-only, effectively. ext-pthreads requires a ZTS PHP build. Standard distro packages and Docker images are NTS; recompiling PHP just to run an archived 2014 library is almost never the right trade.
• PHP version cliff. pthreads is abandoned and does not support modern PHP (8.x). If your app is on PHP 8, this package is dead on arrival regardless of what composer.json says.
• Composer conflicts. This package pulls Amp 1.x-era constraints. It will fight amphp/amp v2/v3 and amphp/parallel if both are present. Expect composer update failures the moment you add a modern Async dependency.
• No security patches, no maintainer. Archived since long before current PHP. Treat any surviving usage as tech debt with a CVE surface.
• Debugging is brutal. Xdebug does not follow execution into pthreads workers. Failures manifest as segfaults, silent no-ops, or truncated output with no stack trace. If you're debugging legacy behavior, add file-based logging at the worker boundary — that's often the only signal you get.
• Shared state lies. Anything passed across the boundary is copied/serialized; mutations in the worker are invisible to the parent. Closures and resources (PDO, sockets, file handles) generally cannot cross. Re-open connections inside the worker or, better, don't do I/O there at all.
• Never in FPM. Spawning threads per HTTP request multiplies memory by worker count and can take down the pool. CLI-only, bounded pool, explicit shutdown.
• php.ini quirks. Per-thread memory limits and stack sizes are configured separately; a job that passes in CLI can OOM in a thread. Check memory_limit in the worker context, not just the parent.
• Extension points are a trap. There is no maintained plugin surface worth extending. If you need behavior changes, port the code — do not fork a 2014 archived repo into vendor/ overrides.
• Migration checklist. (1) Inventory call sites behind an adapter. (2) Port each to amphp/parallel, a queued job, or Process. (3) Delete the require. (4) Remove any ZTS/pthreads build steps from Dockerfiles and CI. (5) Add a composer audit/composer outdated gate so abandoned packages don't creep back in.
• Signal for review. A score of ~1 and archived status means any PR adding this package should be blocked at review. If it's already there, file it as a modernization task with a deadline rather than a "someday" cleanup.