Home

Awesome

Matrix

Matrix

Latest Version on Packagist Tests Check & fix styling Total Downloads

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.

Key Features


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

Matrix\Task

Matrix\Exceptions\Handler


Contributing

We welcome contributions! To contribute:

  1. Fork the repository.
  2. Create a new branch (git checkout -b feature/new-feature).
  3. Make your changes and commit (git commit -m 'Add new feature').
  4. Push your branch (git push origin feature/new-feature).
  5. Open a pull request!

License

Matrix is licensed under the MIT License. See the LICENSE file for more information.


Authors

See also the list of contributors who participated in this project.

Acknowledgments

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.