ByJG PHPThread: Simplified Threads and Non-Blocking Code in PHP
ByJG PHPThread simplifies working with threads and non-blocking code in PHP, bridging the gap for a language that was not inherently designed for threading.
Table of Contents
Overview
PHPThread is a polyfill library that abstracts threading functionality for PHP, providing a consistent interface regardless of the underlying PHP setup (ZTS or Fork). It empowers developers to implement thread-like behavior and asynchronous processing in PHP applications.
Why Threads in PHP?
PHP is traditionally designed for a request-response cycle, where scripts are executed only in response to client requests and terminate after sending a response. While efficient for web applications, this architecture lacks native threading support for background or concurrent tasks.
With PHPThread, you can overcome these limitations by leveraging:
- Forking (Default PHP) for simulating threading.
- Zend Thread Safety (ZTS) for true multi-threading environments.
How It Works
Default PHP (Non-ZTS)
In standard PHP installations (without ZTS), threading is simulated using the fork command.
This approach creates a new process by cloning the parent process. While not a true thread,
this method can approximate threading behavior.
Requirements:
PHP ZTS (Zend Thread Safety)
With ZTS-enabled PHP, true multi-threading becomes possible. This setup is ideal for production environments where
robust threading is required. The ZTS version is compiled with the --enable-zts flag, but it may not be included in
all PHP distributions.
Requirements:
Features
- Thread Management: Simplified thread creation and execution (docs).
- Thread Pools: Efficiently manage and reuse threads for multiple tasks (docs).
- Promises: Truly asynchronous and non-blocking task management with a JavaScript-like Promise API (docs, benchmark).
Supported Promise Methods:
then(): Execute a callback on promise resolution.catch(): Execute a callback on promise rejection.finally(): Execute a callback after resolution or rejection.Promise::resolve(): Resolve a promise.Promise::reject(): Reject a promise.Promise::all(): Wait for all promises to resolve.Promise::race(): Wait for the first promise to resolve.
Limitations
CLI Mode Only
This library only works in CLI mode (command-line interface). It will NOT work in web server environments such as:
- PHP-FPM
- Apache with mod_php
- Any other web server SAPI
Why?
Both threading approaches used by this library require direct process control, which is unavailable in web server environments:
- pcntl extension (used for forking): Disabled in web server contexts for security and stability reasons. The
pcntl_fork()function and related process control functions only work in CLI mode. - parallel extension (used for true threading): Also requires CLI mode and is not available in web server SAPIs.
Additionally, forking or creating threads within a web server process would interfere with the server's own process/thread management, potentially causing instability.
Use Cases:
This library is designed for:
- CLI scripts and daemons
- Background job processors
- Command-line tools
- Long-running CLI applications
- Scheduled tasks (cron jobs)
For web applications requiring asynchronous processing, consider using message queues (RabbitMQ, Redis, etc.) with background workers running in CLI mode.
Forking and Data Sharing
When simulating threads with fork, data cannot be returned directly from the child process
to the parent. Use the shmop extension to share memory between processes.
However:
- Avoid returning large or complex objects, as this may cause memory exhaustion.
Installation
Requirements
Non-ZTS (Default PHP)
- PHP ≥8.3
pcntlextensionshmopextension
ZTS (Zend Thread Safety)
- PHP ≥8.3 compiled with
--enable-zts parallelextensionshmopextension (for Promises support)
Install via Composer
composer require byjg/phpthread