Package · thread

Thread

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

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.
Engine — the single parent-side configuration root that picks the payload transport and the launcher; the default AdaptiveEngine self-configures for CLI, FPM, and Swoole.

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 — pluggable payload transports (PipeTransport, TempFileTransport, ShmTransport) avoid fd corruption under SWOOLE_HOOK_ALL; the AdaptiveEngine auto-detects an active Swoole runtime.
Pluggable engine — swap the transport, launcher, or runner path through a single Engine for deep framework integration or custom backends (Docker, SSH).
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

GitHub — github.com/flytachi/winter-thread
Packagist — packagist.org/packages/flytachi/winter-thread

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