README

Parallite {PHP Client}

Execute PHP closures in true parallel - A standalone PHP client for Parallite, enabling real parallel execution of PHP code without the limitations of traditional PHP concurrency.

✨ Features

• 🚀 True Parallel Execution - Execute multiple PHP closures simultaneously
• 🎯 Simple async/await API - Familiar Promise-like interface
• 🔄 Promise Chaining - Chainable then(), catch(), and finally() methods
• 🌍 Cross-platform - Works on Windows, Linux and macOS
• ⏯️️ Automatic Daemon Management - Optional auto-start/stop of Parallite daemon
• ⚡ Binary MessagePack Transport - Ultra-fast daemon communication (2-5x faster than JSON)

📋 Requirements

• PHP 8.3+
• ext-sockets
• ext-zip
• rybakit/msgpack
• opis/closure

⚠️ Important Notice:

Passing closures that capture $this will cause opis/closure to serialize the entire object instance. This often includes non‑serializable dependencies (e.g., PDO, CurlHandle, resource, sockets, Laravel Models, Collections, etc) and may lead to errors.

👉 Please review the Troubleshooting page for guidance on how to avoid this issue and know more.

📦 Installation

composer require parallite/parallite-php

Add the install/update scripts to your composer.json:

{
  "scripts": {
    "post-install-cmd": [
      "@php vendor/parallite/parallite-php/bin/parallite-install"
    ],
    "post-update-cmd": [
      "@php vendor/parallite/parallite-php/bin/parallite-update"
    ]
  }
}

See more about these scripts: Installation Guide.

After adding the scripts, run (to download Parallite binary):

composer install

# or update
composer update

🚀 Quick Start

<?php

require 'vendor/autoload.php';

// Basic usage - no imports needed!
$result = await(async(fn() => 'Hello World'));
echo $result; // Hello World

// Parallel execution
$p1 = async(fn() => sleep(1) && 'Task 1');
$p2 = async(fn() => sleep(1) && 'Task 2');
$p3 = async(fn() => sleep(1) && 'Task 3');

$results = await([$p1, $p2, $p3]);
// Total time: ~1s (parallel) instead of 3s (sequential)

// Promise chaining
$result = await(
    async(fn() => 1 + 2)
        ->then(fn($n) => $n * 2)
        ->then(fn($n) => $n + 5)
);
echo $result; // 11

// Error handling
$result = await(
    async(function () {
        throw new Exception('Oops!');
    })->catch(fn($e) => 'Caught: ' . $e->getMessage())
);
echo $result; // Caught: Task failed: Oops!

That's it! The daemon is automatically managed - no manual setup required!

📚 Documentation

• Quick Start Guide - Get up and running in minutes
• Installation - Detailed installation instructions
• Configuration - Customize daemon behavior and PHP includes
• API Reference - Complete API documentation
• Complex Data Handling - How to handle complex data structures
• Troubleshooting - Common issues and solutions
• Examples - Real-world usage examples

⚡ Performance

Parallite provides significant speedup for I/O-bound and CPU-bound tasks:

Parallelism is beneficial when:

✅ CPU-intensive operations (image processing, complex calculations)
✅ Independent I/O-bound operations (external API calls, multiple databases)
✅ Database with good concurrency (MongoDB, PostgreSQL, SQL Server, MySQL)
❌ SQLite with concurrent writes
❌ Operations are already very fast

Example using the Filamentphp demo

Project with + 20 thousand orders, simulating several heavy calculations and with json transformation, as if it were for a heavy dashbaord (when I have time, I'll add this demo project to git):

✅ With Parallite:

🚫 Without Parallite:

The increase was approximately 321.4% in orders processed per second.

Real-World Example

// Fetch multiple APIs in parallel
$promises = [
    'users'    => async(fn() => file_get_contents('https://api.example.com/users')),
    'posts'    => async(fn() => file_get_contents('https://api.example.com/posts')),
    'comments' => async(fn() => file_get_contents('https://api.example.com/comments')),
];

$data = await($promises);
// 3x faster than sequential fetching!

Run the real-world test suite (uses data available at https://jsonplaceholder.typicode.com):

RUN_REAL_WORLD_TESTS=1 vendor/bin/pest tests/Feature/RealWorldDataProcessingTest.php --no-coverage

🌐 Platform Support

🐛 Troubleshooting

Having issues? Check the Troubleshooting Guide for solutions.

Quick tip:

• You can use pd() inside async() calls, it will throw an exception with the dump data.
• Never capture $this in closures passed to async(). Use static methods or extract primitives instead.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Credits

• Parallite Daemon: b7s/parallite
• Closure Serialization: opis/closure
• MessagePack: rybakit/msgpack
• Inspired by: Pokio

📮 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Made with ❤️ by the Parallite community