Download the PHP package jerome/matrix without Composer

Matrix

Matrix is a PHP library that brings asynchronous, non-blocking functionality to PHP, inspired by JavaScript's async/await syntax. With Matrix, you can handle asynchronous tasks and manage concurrency using promises and a simple, intuitive API.

Why Choose Matrix?

Matrix simplifies asynchronous programming in PHP by combining promises with ReactPHP's event loop. It supports non-blocking execution, seamless error handling, and easy integration with existing projects.

Key Features

• JavaScript-like API: Use async() and await() for straightforward asynchronous programming.
• Powered by ReactPHP: Ensures non-blocking execution using ReactPHP's event loop.
• Robust Error Handling: Catch and handle exceptions with .catch() or try-catch.
• Automatic Loop Management: The event loop runs automatically to handle promise resolution.
• Concurrent Operations: Run multiple asynchronous tasks in parallel.
• Rate Limiting: Control the frequency of asynchronous operations.
• Promise Cancellation: Cancel pending operations when they're no longer needed.
• Retry Mechanism: Automatically retry failed operations with configurable backoff strategies.
• Batch Processing: Process items in batches for improved performance.
• Enhanced Error Handling: Add context to errors for better debugging.

Installation

Install Matrix via Composer:

Requirements

• PHP 8.0 or higher
• sockets extension enabled

ReactPHP promises and the event loop will be installed automatically via Composer.

API Overview

Core Functions

async(callable $callable): PromiseInterface

Wraps a callable into an asynchronous function that returns a promise.

await(PromiseInterface $promise, ?float $timeout = null): mixed

Awaits the resolution of a promise and returns its value. Optionally accepts a timeout in seconds.

Promise Combination

all(array $promises): PromiseInterface

Runs multiple promises concurrently and returns a promise that resolves with an array of all results.

race(array $promises): PromiseInterface

Returns a promise that resolves with the value of the first resolved promise in the array.

any(array $promises): PromiseInterface

Returns a promise that resolves when any promise resolves, or rejects when all promises reject.

Concurrency Control

map(array $items, callable $callback, int $concurrency = 0, ?callable $onProgress = null): PromiseInterface

Maps an array of items through an async function with optional concurrency control and progress tracking.

batch(array $items, callable $batchCallback, int $batchSize = 10, int $concurrency = 1): PromiseInterface

Processes items in batches rather than one at a time for improved performance.

pool(array $callables, int $concurrency = 5, ?callable $onProgress = null): PromiseInterface

Executes an array of callables with limited concurrency.

Error Handling and Control

timeout(PromiseInterface $promise, float $seconds, string $message = 'Operation timed out'): PromiseInterface

Creates a promise that times out after a specified period.

retry(callable $factory, int $maxAttempts = 3, ?callable $backoffStrategy = null): PromiseInterface

Retries a promise-returning function multiple times until success or max attempts reached.

cancellable(PromiseInterface $promise, callable $onCancel): CancellablePromise

Creates a cancellable promise with a cleanup function.

withErrorContext(PromiseInterface $promise, string $context): PromiseInterface

Enhances a promise with additional error context.

Timing and Flow Control

delay(float $seconds, mixed $value = null): PromiseInterface

Creates a promise that resolves after a specified delay.

waterfall(array $callables, mixed $initialValue = null): PromiseInterface

Executes promises in sequence, passing the result of each to the next.

rateLimit(callable $fn, int $maxCalls, float $period): callable

Creates a rate-limited version of an async function.

Examples

Running Asynchronous Tasks

Using the Await Syntax

Handling Errors

Chaining Promises

HTTP Requests Example

Database Operations Example

JIRA Integration Example

Advanced Testing

Matrix includes a comprehensive test suite to ensure reliability, including:

Unit Tests

Test individual components in isolation:

Integration Tests

Test how components work together in real-world scenarios:

Error Handling Tests

Test that errors are properly handled and propagated:

Concurrency Pattern Tests

Test various concurrency patterns:

Performance Considerations

• Event Loop: Matrix uses ReactPHP's event loop, which should be run only once in your application.
• Blocking Operations: Avoid CPU-intensive tasks in async functions as they will block the event loop.
• Memory Management: Be mindful of memory usage when creating many promises, as they remain in memory until resolved.
• Error Handling: Always handle promise rejections to prevent unhandled promise rejection warnings.
• Concurrency Limits: Use the concurrency parameters in map(), batch(), and pool() to control resource usage.
• Rate Limiting: Use rateLimit() when working with APIs that have rate limits to avoid being throttled.

How It Works

1. Event Loop Management: The async() function schedules work on ReactPHP's event loop.
2. Promise Interface: Promises provide then and catch methods for handling success and errors.
3. Synchronous Await: The await() function runs the event loop until the promise is resolved or rejected.
4. Concurrency Control: Functions like map(), batch(), and pool() limit the number of concurrent operations.
5. Error Handling: Custom exception classes provide detailed information about failures.

Testing

Run the test suite to ensure everything is working as expected:

Contributing

We welcome contributions! To get started:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please make sure your code follows the project's coding standards and includes appropriate tests.

License

Matrix is open-source software licensed under the MIT License.