RUEN
Package · thread

Thread

Winter Thread provides a clean, object-oriented API for running and controlling background processes in PHP — a familiar, threading-style interface for parallel and long-running tasks, built on isolated OS processes. It abstracts the complexities of proc_open and POSIX signals into a powerful, easy-to-use interface.

It's an engine — and a Thread is a process

Winter Thread is a small, dependable engine, not a batteries-included framework: the layer your queues, pools, schedulers and workers are built on top of. And a Thread is a process, not a PHP thread — the name mirrors a familiar API (much as Python’s multiprocessing.Process mirrors its threading interface), so each Thread is one isolated OS process wearing a start() / join() / isAlive() face. See the Mental model.

Philosophy

The core idea is a developer-friendly, Java-like threading model in a language that traditionally lacks built-in multi-threading. This is achieved by leveraging separate OS-level processes:

  • True parallelism — each task runs in its own process and can be scheduled on a different CPU core, achieving real parallel execution.
  • Isolation — processes are fully isolated. A fatal error or memory leak in one child never affects the main application or other children.
  • Simplicity — a clean Thread and Runnable API lets you focus on task logic instead of pipes, signals, and serialization.

Core concepts

  • Thread — the object that manages a child process: starting, stopping, monitoring.
  • Runnable — an interface representing a unit of work. Any class implementing it can be executed by a Thread; your logic lives in run().
  • Runner script — an internal executable (wRunner) that bootstraps the new process, deserializes the task, and runs it.
  • Launcher — the parent side: it spawns the process and owns the payload-signing secret. The default AdaptiveLauncher picks a backend to match the runtime — CliLauncher for CLI and FPM, SwooleLauncher inside a coroutine.

Key features

  • Fluent, object-oriented API — manage background processes as objects.
  • Full process control — start(), join(), pause(), resume(), terminate(), kill().
  • Advanced process naming — identify processes via namespaces, names, and tags.
  • Safe by default — output goes to /dev/null, so there is no Broken pipe risk for fire-and-forget jobs.
  • Swoole / event-loop compatible — under an active Swoole runtime the launch goes through SwooleLauncher and the payload is delivered pipe-free (shared memory or a temp file), so the reactor’s descriptors stay intact.
  • Swappable launch backend — the Launcher interface is two methods, so your own way of starting a process (Docker, SSH, a remote node) plugs in via Thread::bindLauncher().
  • Java-like API — familiar method names like isAlive() and join().

Good fit for

Independent tasks that don’t need complex IPC: heavy computation (image/video encoding, report generation), I/O-bound work (email batches, external APIs), or offloading any long-running operation to keep the main thread responsive.

Requirements

  • PHP ≥ 8.4
  • ext-pcntl, ext-posix
  • A POSIX OS (Linux, macOS, BSD) — not compatible with Windows
  • opis/closure ^4.5 — enables safe serialization of anonymous classes and closures

Install

bash
composer require flytachi/winter-thread

Quick start

Define a task, wrap it in a Thread, and start it — your script never blocks:

php
$thread = new Thread(new ReportGenerator(42));

$pid = $thread->start();   // runs in the background, returns immediately
$thread->join();           // optional: wait for it to finish

Walk through it end to end — install to a verified background job in five minutes — in the Quickstart.

Source & links

Continue with Installation & requirements, the Quickstart, and the Mental model.