jerome / matrix
An unparalleled PHP asynchronous experience, offering genuine concurrency and fiber-based task management.
Fund package maintenance!
thavarshan
Buy Me A Coffee
Installs: 1 450
Dependents: 1
Suggesters: 0
Security: 0
Stars: 29
Watchers: 3
Forks: 0
Open Issues: 0
Requires
- php: ^8.2
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.64
- guzzlehttp/guzzle: ^7.0
- mockery/mockery: ^1.6
- pestphp/pest: ^3.0
- php-mock/php-mock: ^2.5
- php-mock/php-mock-mockery: ^1.4
- phpstan/phpstan: ^1.11.5
- squizlabs/php_codesniffer: ^3.7
README
Matrix
Matrix is a cutting-edge PHP library for asynchronous task management, inspired by JavaScript’s async
/await
paradigm but leveraging PHP's native Fibers. Matrix provides a streamlined, non-blocking API to run tasks, manage errors, and handle results—all without the need for explicit task starting.
Matrix also supports manual task management through the Task
class and robust error handling through a customizable ErrorHandler
.
Why Matrix?
Matrix brings a JavaScript-like async experience to PHP, providing developers with the simplicity and power of managing asynchronous tasks without complexity.
- JavaScript-like async API: Matrix introduces a simple and elegant API inspired by JavaScript’s async functions.
- Built on PHP Fibers: Using PHP 8.1+ Fibers, Matrix delivers true non-blocking concurrency.
- Customizable Error Handling: Handle task failures gracefully with an extensible error handler.
- Manage Task Lifecycles: Direct control over task status with methods for pausing, resuming, and canceling tasks.
Key Features
- JavaScript-like async/await API for seamless asynchronous task execution.
- Non-blocking concurrency: Built on top of PHP 8.1+ Fibers.
- Error handling with custom error recovery using the
Handler
class. - Task lifecycle management: Start, pause, resume, cancel, or retry tasks.
Installation
Install Matrix via Composer:
composer require jerome/matrix
Matrix requires PHP 8.1 or above.
JavaScript-like Async API
Matrix brings the familiarity of JavaScript's async
/await
into PHP, making it incredibly easy to work with asynchronous tasks. Here's how you can use it:
use Matrix\AsyncHelper; use function Matrix\async; // Execute an asynchronous task with success and error handling async(fn () => 'Task result') ->then(function ($result) { echo $result; // Output: Task result }) ->catch(function ($e) { echo $e->getMessage(); // Handle any errors });
This JavaScript-like API allows you to define tasks, handle success, and catch errors seamlessly—without needing to call a start
method explicitly.
Handling Errors in Async Tasks
Matrix also makes it easy to handle errors in asynchronous tasks:
async(fn () => throw new \RuntimeException('Error occurred')) ->catch(function ($e) { echo "Caught error: " . $e->getMessage(); // Output: Caught error: Error occurred });
The catch()
method allows you to define an error handler, making it straightforward to manage exceptions during task execution.
Task Management with the Task Class
If you prefer more manual control over your tasks, Matrix provides the Task
class, allowing you to directly manage task lifecycles.
Creating and Managing Tasks
use Matrix\Task; // Define a task that performs an operation $task = new Task(function () { for ($i = 0; $i < 3; $i++) { echo "Working...\n"; \Fiber::suspend(); // Pause execution and yield control } return "Task completed"; }); // Start the task $task->start(); // Resume the task until it completes while (!$task->isCompleted()) { $task->resume(); } echo $task->getResult(); // Output: Task completed
Pausing and Resuming Tasks
Matrix allows you to pause and resume tasks at will:
$task->pause(); // Pause the task $task->resume(); // Resume the task
Task Status Management
Each task has a status (PENDING
, RUNNING
, PAUSED
, COMPLETED
, FAILED
, CANCELED
) that can be queried using the getStatus()
method.
Error Handling with the Handler Class
Matrix provides robust error handling through the Handler
class. This class allows you to define retry logic, error logging, and final failure handling.
Example of Error Handling with Task
use Matrix\Task; use Matrix\Exceptions\Handler; // Define an error handler $errorHandler = new Handler(3, [\RuntimeException::class]); // Create a task that throws an exception $task = new Task(function () { throw new \RuntimeException('Something went wrong'); }, $errorHandler); try { $task->start(); } catch (\Throwable $e) { $errorHandler->handle('task_1', $task, $e); } // Retry the task if it failed if ($task->getStatus() === TaskStatus::FAILED) { $task->retry(); }
The Handler
class can automatically retry tasks or log errors, making it highly customizable.
API Reference
Matrix\AsyncHelper
then(callable $callback)
: Registers a success callback and starts the task.catch(callable $callback)
: Registers an error callback and starts the task.start()
: Manually starts the task (called automatically when usingthen
orcatch
).
Matrix\Task
start()
: Starts the task execution.pause()
: Pauses the task if it’s running.resume()
: Resumes a paused task.cancel()
: Cancels the task.retry()
: Retries a task if it has failed or completed.getStatus()
: Returns the task status (PENDING
,RUNNING
,PAUSED
,COMPLETED
, etc.).getResult()
: Retrieves the result of the task once completed.
Matrix\Exceptions\Handler
handle($contextId, $context, Throwable $e)
: Handles task errors.retryTask($taskId, Task $task)
: Retries a task.handleFinalFailure($taskId, Task $task)
: Handles a task’s final failure after all retries are exhausted.
Contributing
We welcome contributions! To contribute:
- Fork the repository.
- Create a new branch (
git checkout -b feature/new-feature
). - Make your changes and commit (
git commit -m 'Add new feature'
). - Push your branch (
git push origin feature/new-feature
). - Open a pull request!
License
Matrix is licensed under the MIT License. See the LICENSE file for more information.
Authors
- [Jerome Thayananthajothy] - Initial work - Thavarshan
See also the list of contributors who participated in this project.
Acknowledgments
- Special thanks to the PHP community for their support and inspiration for this project.
Get Involved
Matrix offers a unique PHP async experience, bringing true concurrency and fiber-based task management to PHP developers. Star the repository on GitHub to help Matrix grow and to stay updated on new features.