Download the PHP package flytachi/winter-thread without Composer

Winter Thread: A Modern Process Control Library for PHP

Winter Thread is a process engine for PHP: a clean, object-oriented, Java-like API for running and controlling background tasks as isolated OS processes — for parallel and long-running work.

It's an engine — the foundation you build on. A small, dependable core, not a batteries-included framework: the layer your queues, pools, schedulers and workers sit on top of. You bring the higher-level concurrency; the engine handles the hard, boring parts — spawning, signals, isolation, transports.

A Thread here is a process, not a PHP thread. The name is a deliberate nod to a familiar API — just as Python's multiprocessing.Process mirrors its threading interface. Every Thread is one fully isolated OS process wearing a clean, thread-like face (start(), join(), isAlive()) — so there's no shared state to corrupt and nothing to leak between tasks.

No heavy extensions. Unlike pthreads, ext-parallel, or Swoole, it needs no ZTS build and no exotic runtime — just proc_open and the standard POSIX extensions (ext-pcntl, ext-posix) that ship with nearly every PHP install. Each task runs in a fresh, isolated PHP process, so there is no shared state to corrupt and no inherited connections to break.

Key Features

• No heavy extensions: No swoole / parallel / pthreads, no ZTS build — just proc_open + standard POSIX. Runs on a normal PHP install.
• Clean process isolation: Each task runs in a brand-new PHP process — no inherited DB connections, sockets, or global state to corrupt.
• Fluent, Object-Oriented API: Manage background processes as objects.
• Full Process Control: start(), join(), pause(), resume(), terminate(), and kill().
• Advanced Process Naming: Identify your processes easily with namespaces, names, and tags.
• Safe by Default: Output goes to /dev/null by default — no Broken pipe risk for fire-and-forget jobs.
• Swoole / Event-Loop Compatible: Launch background tasks from inside a coroutine safely — the default AdaptiveLauncher routes to a Swoole-native backend (Coroutine\System::exec) where proc_open would corrupt the reactor's fds, with pipe-free payload transports (temp-file, shared-memory). No ext-swoole required; it's used only when present.
• Zombie-free fire-and-forget: Optional detached mode (fork + setsid) reparents workers to init, so long-lived parents (FPM, daemons) never accumulate zombies.
• Pluggable backend: Swap the payload transport or the whole spawn strategy through a single Launcher — build custom backends (Docker, SSH, …) without touching Thread.
• Java-like API: Familiar method names like isAlive() and join() for an easy learning curve.

Requirements

• PHP >= 8.4
• ext-pcntl
• ext-posix
• opis/closure ^4.5 (required; enables safe serialization of anonymous classes and closures)
• ext-shmop (optional; only for the shared-memory transport)

Installation

Quick Start

Configuration — the Launcher

Configuration goes through a single Launcher, bound once at bootstrap with Thread::bindLauncher(). When you bind nothing, a self-configuring AdaptiveLauncher is used (AdaptiveLauncher::adaptive()), which routes each launch to the right backend for the current runtime — CliLauncher on CLI / FPM, SwooleLauncher inside a Swoole coroutine.

Swoole / Event-Loop Compatibility

When its transport is left unset, the launcher picks a pipe-free transport (TempFileTransport) if it detects an active Swoole runtime — pipe file descriptors from proc_open do not survive SWOOLE_HOOK_ALL intact.

Launching from inside a Swoole coroutine is supported. A pipe-free transport handles the payload, but the spawn is the other half: native proc_open contends with the reactor over the file-descriptor table from inside a coroutine. The default AdaptiveLauncher closes that gap — it routes to SwooleLauncher, which starts the runner as a shell background job (Coroutine\System::exec()) that never touches the reactor's fds. So in-coroutine dispatch works out of the box; plain CLI and FPM go through proc_open exactly as before. See docs/07.

Detached (zombie-free) fire-and-forget

For a long-lived parent (FPM worker, daemon) that dispatches background tasks and never joins them, pass detached: true. The launcher exits immediately and the real worker is reparented to init (pid 1), so no zombie ever accumulates under the parent:

Signal control still works via the worker's self-reported PID (write getmypid() from inside the task to your own store), since the engine's control model is PID-based.

Output Modes

Note: With null, join() and reap() drain the pipes internally while they wait, so a bare join() never deadlocks on a large output — and readOutput() after it returns the full buffered output. Use an explicit readOutput() poll loop only when you want the output live as it is produced.

Process Control

Running Tests

Tests come in two tiers (mirroring the winter-kernel layout):

Default — runs on any machine; unsupported extensions self-skip:

Containered — heavy, environment-specific checks (leak / timing / nested / battle-run, with Cli / FPM / Swoole), run inside Docker across a list of PHP versions:

CI (.github/workflows/ci.yml) runs the default suite via setup-php and the container suite via the bundled tests/docker/Dockerfile, on a PHP 8.4 / 8.5 matrix.

Documentation

Full documentation lives in /docs:

1. Introduction — philosophy, the no-heavy-ext story, when to use it
2. Installation & Requirements
3. Quickstart — a complete parallel example in 5 minutes
4. Basic Usage
5. Output & Debugging
6. Process Control & Lifecycle — signals, graceful shutdown
7. The Launcher
8. Payload Transports
9. Detached Mode
10. Security
11. Architecture & Internals
12. Patterns — pools, returning results, retries
13. Troubleshooting
14. API Reference
15. Testing

Contributing

Contributions are welcome! Please submit a pull request or open an issue for bugs, questions, or feature requests.

License

This library is open-source software licensed under the MIT license.