DEV Community: Reymart A. Calicdan

PHP Fibers and the Future of MySQL Drivers

Reymart A. Calicdan — Wed, 06 May 2026 15:32:58 +0000

PHP is moving into a new era. With the introduction of Fibers in PHP 8.1, we can finally build long-running and high-performance applications that handle thousands of concurrent tasks. However, to truly unlock this power, we need database drivers that are built specifically for an asynchronous world.

Most existing PHP drivers are blocking. When you send a query, the entire process stands still while waiting for the database. This is a massive bottleneck for modern apps.

I built the Hibla MySQL Client to solve this. It is a ground-up implementation of the MySQL Binary Protocol designed specifically for the Hibla ecosystem.

Efficient connection management

In a traditional script, you connect and disconnect for every single request. In an async application, that is simply too slow. Hibla features a built-in Pool Manager that keeps connections warm and ready to use.

It includes "Check-on-Borrow" logic. This ensures that every connection you get is healthy and active. It also handles connection resetting. This means session variables or temporary tables from a previous task never leak into the next one.

use Hibla\Mysql\MysqlClient;

$db = new MysqlClient(
    config: 'mysql://root:secret@127.0.0.1/app_db',
    minConnections: 5,
    maxConnections: 20
);

// You can easily monitor your pool health
print_r($db->stats); 
/* 
Output includes: active_connections, pooled_connections, 
waiting_requests, and more. 
*/

Handling transaction failures automatically

Transactions are often the most fragile part of database logic. Deadlocks and lock wait timeouts are common in busy systems. Usually, you have to write manual loops and complex retry logic to handle these transient errors.

Hibla builds this directly into the API. You can define a transaction block and tell the client how many times it should try again if an error occurs. It simplifies your code and makes your application much more resilient.

use Hibla\Sql\TransactionOptions;

await($db->transaction(function($tx) {
    // This entire block will be retried automatically on deadlocks
    $balance = await($tx->fetchValue("SELECT balance FROM accounts WHERE id = :id", null, ['id' => 1]));

    await($tx->execute(
        "UPDATE accounts SET balance = :b WHERE id = :id", 
        ['b' => $balance - 100, 'id' => 1]
    ));
}, TransactionOptions::default()->withAttempts(3)));

Processing large datasets without memory spikes

When you need to process a million rows, loading them all into memory is not an option. Hibla supports true unbuffered streaming. This allows you to work through massive result sets one row at a time.

We also implemented a smart backpressure handler. If your code is processing rows slower than the database can send them, Hibla automatically pauses the underlying socket. It only resumes when your code is ready for more. This keeps your memory usage low and predictable even during heavy data exports.

$stream = await($db->stream("SELECT * FROM massive_log_table"));

// The stream pauses the socket automatically if the buffer fills up
foreach ($stream as $row) {
    // Process each row one by one
    await(doComplexProcessing($row));
}

echo "Stream finished. Total rows: " . $stream->stats->rowCount;

Stopping slow queries in their tracks

In a standard PHP environment, once you send a query, you are committed. If the user cancels their request or a timeout hits, the database keeps running that query anyway. This wastes server resources and holds up important locks.

Hibla solves this with side-channel cancellation. When you cancel a promise in PHP, the client opens a brief secondary connection to the server and issues a KILL QUERY command. The server stops the work immediately.

use Hibla\EventLoop\Loop;

$promise = $db->query("SELECT some_very_slow_calculation()");

// If we decide we do not want this anymore after 1 second...
Loop::addTimer(1.0, fn() => $promise->cancel());

try {
    await($promise);
} catch (CancelledException $e) {
    // The query was killed on the MySQL server instantly
    echo "Query stopped and server resources were freed.";
}

Built for modern security and speed

This client is not a wrapper around older extensions. It talks directly to the MySQL socket. This allows us to support a wide range of modern features out of the box without any external dependencies.

This includes SSL and TLS encryption for secure data transfer. We also support zlib compression to save bandwidth on large queries. The driver handles both Native and SHA256 authentication plugins automatically.

// Simple configuration via URI for complex features
$db = new MysqlClient(
    config: 'mysql://user@host/db?ssl=true&compress=true&charset=utf8mb4'
);

Moving PHP forward

The goal of this project is to make PHP feel as modern and capable as any other async-first language. By implementing the protocol from scratch, we get absolute control over the connection lifecycle.

You can find the project and the full documentation here:
https://github.com/hiblaphp/mysql

I would love to hear your feedback. Are you building long-running PHP applications? How are you handling database concurrency today?

Streaming AI Responses in PHP with Server-Sent Events

Reymart A. Calicdan — Sun, 03 May 2026 06:29:13 +0000

If you have ever built something with an LLM API like Gemini or OpenAI, you know the experience people expect: text that streams in word by word, like the model is thinking in real time. Achieving that in PHP has traditionally meant a lot of plumbing. You end up wrestling with raw curl handles, manual buffer flushing, or even reaching for a Node.js sidecar just to handle the stream.

I built Hibla HTTP Client to make this feel natural in PHP. It is an async-first, fiber-based HTTP client with first-class SSE support baked in. This post walks through how SSE works in the library and how you can use it today to consume streaming AI responses cleanly.

What is SSE and why does it matter for AI?

Server-Sent Events is a simple HTTP-based protocol where the server keeps a connection open and pushes data to the client as it becomes available. Every major LLM API, Gemini, OpenAI, Anthropic, Mistral, uses SSE to stream generated tokens back to you incrementally instead of making you wait for the full response.

The wire format looks like this:

data: {"candidates":[{"content":{"parts":[{"text":"Hello"}]}}]}

data: {"candidates":[{"content":{"parts":[{"text":" world"}]}}]}

Parsing that manually, reconnecting on drop, and handling backpressure is tedious. That is exactly what Hibla handles for you.

Installation

The library is currently in beta. Add this to your composer.json first:

{
    "minimum-stability": "beta",
    "prefer-stable": true
}

Then install:

composer require hiblaphp/http-client

Requirements: PHP 8.4+ and ext-curl.

A real example: streaming Gemini

Here is a complete working example that streams a response from Google Gemini and prints each token as it arrives:

<?php

declare(strict_types=1);

require 'vendor/autoload.php';

use Hibla\HttpClient\Http;
use Hibla\HttpClient\SSE\SSEControl;
use Hibla\HttpClient\SSE\SSEDataFormat;

use function Hibla\await;

function ask(string $prompt): void
{
    await(
        Http::client()
            ->withHeader('x-goog-api-key', getenv('GEMINI_API_KEY'))
            ->withMethod('POST')
            ->withJson([
                'contents' => [[
                    'role'  => 'user',
                    'parts' => [['text' => $prompt]],
                ]],
            ])
            ->sse('https://generativelanguage.googleapis.com/v1beta/models/gemma-3-27b-it:streamGenerateContent?alt=sse')
            ->withoutReconnection()
            ->withDataFormat(SSEDataFormat::DecodedJson)
            ->onEvent(function (array|string $data, SSEControl $control) {
                echo $data['candidates'][0]['content']['parts'][0]['text'] ?? '';
            })
            ->connect()
    );
}

ask('Why is PHP still relevant in 2026?');

Note: I know using getenv() is a bad practice is public code but this is just a sample code and you can use any configuration library of your choice.

That is it. No manual curl setup, no buffer parsing, no event loop wiring. The onEvent callback fires for every chunk the server sends, and SSEDataFormat::DecodedJson means the payload is already decoded for you, so no json_decode() needed.

How the SSE builder works

The .sse() method returns a fluent builder. You chain your configuration on it and call .connect() at the end, which returns a promise that resolves once the HTTP handshake completes. Events keep flowing after that, as the connection stays open.

Http::client()
    ->sse('https://api.example.com/events')
    ->withDataFormat(SSEDataFormat::DecodedJson)
    ->onEvent(function (array|string $data, SSEControl $control) {
        echo $data['message'];

        // stop the stream from inside the callback
        if ($data['done'] ?? false) {
            $control->cancel();
        }
    })
    ->onError(function (Throwable $e) {
        echo "Connection error: " . $e->getMessage();
    })
    ->connect();

A few things worth knowing about how this behaves:

The promise resolves as soon as the server responds with a 2xx status and headers. Events arrive after that. But if the server returns a non-2xx status at handshake time, the promise rejects immediately and no events are delivered.

The operation timeout is disabled by default for SSE connections because they are meant to be long-lived. The connection timeout still applies to the initial handshake, which is exactly what you want.

Data formats

One small thing that makes a real difference in practice is the withDataFormat() option. By default the callback receives a full SSEEvent object with all the raw fields, but for AI APIs that send JSON payloads you almost never care about anything other than the data field, already decoded.

use Hibla\HttpClient\SSE\SSEDataFormat;

// Full event object, useful when you need event type, id, or retry hint
->withDataFormat(SSEDataFormat::Event)
->onEvent(function (SSEEvent $event, SSEControl $control) {
    echo $event->data;
    echo $event->id;
})

// Already decoded JSON, the sweet spot for LLM APIs
->withDataFormat(SSEDataFormat::DecodedJson)
->onEvent(function (array|string $data, SSEControl $control) {
    echo $data['choices'][0]['delta']['content'] ?? '';
})

// Raw string, for when you want to handle deserialization yourself
->withDataFormat(SSEDataFormat::Raw)
->onEvent(function (string $data, SSEControl $control) {
    $decoded = json_decode($data, true);
})

Mapping events to typed objects

If you want to keep your onEvent callback clean and strongly typed, you can use map() to transform each event before it reaches the callback. The mapper runs after format conversion, so you get the already-decoded value:

Http::client()
    ->sse('https://api.example.com/stream')
    ->withDataFormat(SSEDataFormat::DecodedJson)
    ->map(fn(array $data) => new ChatChunk($data))
    ->onEvent(function (ChatChunk $chunk, SSEControl $control) {
        echo $chunk->text();
    })
    ->connect();

This is particularly useful if you are building a wrapper around an LLM API and want clean domain objects flowing through your application rather than raw arrays.

Reconnection

For production use cases where you cannot afford to silently drop a stream, Hibla has built-in reconnection with exponential backoff. The Last-Event-ID header is forwarded automatically on reconnect so the server can resume from where it left off:

Http::client()
    ->sse('https://api.example.com/events')
    ->reconnect(
        maxAttempts:       10,
        initialDelay:      1.0,
        maxDelay:          30.0,
        backoffMultiplier: 2.0,
        jitter:            true,
    )
    ->onEvent(fn($data, $ctrl) => handleEvent($data))
    ->connect();

For AI streaming use cases you typically want .withoutReconnection() since a dropped generation is not resumable anyway. But for persistent event feeds like webhooks, live dashboards, or notification streams, the reconnection support is genuinely useful.

Cancellation

You can cancel a stream from inside the callback via SSEControl, or from outside via the promise or connection object:

// From inside, a clean way to stop after a sentinel value
->onEvent(function (array|string $data, SSEControl $control) {
    if (($data['finish_reason'] ?? '') === 'stop') {
        $control->cancel();
    }
})

// From outside
$promise    = Http::client()->sse('...')->onEvent(...)->connect();
$connection = await($promise);

$connection->close();
// or equivalently
$promise->cancel();

Cancellation immediately closes the connection and suppresses any further reconnection attempts.

Running multiple streams concurrently

Because every connect() call returns a promise, you can run multiple SSE connections at the same time using Promise::all(). This is useful if you want to fan out a prompt to multiple models and compare their outputs:

use Hibla\Promise\Promise;
use function Hibla\await;

$stream = fn(string $model, string $prompt) => Http::client()
    ->withHeader('x-goog-api-key', getenv('GEMINI_API_KEY'))
    ->withMethod('POST')
    ->withJson(['contents' => [['role' => 'user', 'parts' => [['text' => $prompt]]]]])
    ->sse("https://generativelanguage.googleapis.com/v1beta/models/{$model}:streamGenerateContent?alt=sse")
    ->withoutReconnection()
    ->withDataFormat(SSEDataFormat::DecodedJson)
    ->onEvent(function (array|string $data, SSEControl $control) use ($model) {
        echo "[{$model}] " . ($data['candidates'][0]['content']['parts'][0]['text'] ?? '');
    })
    ->connect();

await(Promise::all([
    $stream('gemini-2.5-flash', 'Explain fibers in PHP'),
    $stream('gemma-3-27b-it',   'Explain fibers in PHP'),
]));

Both streams run concurrently under the same event loop. No threads, no forking, no extra processes.

Beyond SSE

SSE is one piece of what Hibla HTTP Client covers. The same async-first design applies across the whole library: regular requests, file downloads, uploads, streaming responses, and a full interceptor pipeline for auth, logging, caching, and retry logic. If you have used Laravel's HTTP client, the fluent builder API will feel familiar.

// Concurrent requests
[$users, $posts] = await(Promise::all([
    Http::get('https://api.example.com/users'),
    Http::get('https://api.example.com/posts'),
]));

// Sliding window concurrency, keeping 10 requests in flight at a time
$results = await(Promise::concurrent($tasks, concurrency: 10));

// File download with progress tracking
await(Http::download(
    'https://files.example.com/model-weights.bin',
    '/tmp/weights.bin',
    fn(DownloadProgress $p) => printf("%.1f%%\n", $p->percent)
));

Try it out

The library is on GitHub and Packagist. If you are building anything with LLM APIs in PHP, the SSE support is worth a look as it cuts out a lot of the boilerplate that usually comes with streaming responses.

GitHub: https://github.com/hiblaphp/http-client
Packagist: hiblaphp/http-client

Feedback, issues, and contributions are very welcome. The library is young and there is still a lot to build out, including alternative transports beyond cURL. If you try it and run into something unexpected, open an issue.

Have you worked with SSE in PHP before? What was your approach? Let me know in the comments.

The Missing Async Ecosystem for PHP: Fibers, Worker Pools & Fractal Concurrency

Reymart A. Calicdan — Thu, 30 Apr 2026 15:58:57 +0000

For years, the PHP async ecosystem has felt like a fragmented puzzle.

We have amazing foundational libraries and powerful extensions, but building a full-stack async application often means dealing with the dreaded "Function Coloring" problem, managing clunky process wrappers for CPU-heavy tasks, or relying on pcntl_fork which can lead to unpredictable state corruption.

I wanted an async ecosystem that felt native, cohesive, and elegant, built entirely on standard modern PHP.

So, I built the Hibla Ecosystem for PHP 8.4+.

It is a complete, cross-platform suite of packages covering the Event Loop, Fibers, Promises, HTTP, Synchronization, Cancellation, and Multi-processing. Here is a look at what modern PHP async looks like when all the pieces fit perfectly together.

The End of "Function Coloring"

If you've written async code in other languages, you know the "What Color is Your Function?" problem. The moment you use await inside a function, that function must be marked async. This changes its return type to a Promise, forcing every function that calls it to also become async. The "color" infects your entire codebase.

Hibla solves this entirely.

In Hibla, async() and await() are plain PHP functions. await() is context-aware: it checks if it is running inside a Fiber. If it is, it suspends cooperatively. If it isn't (e.g., at the top level of your script), it simply holds the script there and drives the event loop until the promise resolves.

This means you can write normal functions that use await(), and the caller gets to decide whether to run them synchronously or concurrently:

use function Hibla\{async, await};
use Hibla\HttpClient\Http;

// A plain function. No special keywords, no changed return type.
function getUser(int $id): array {
    $response = await(Http::get("https://api.example.com/users/$id"));
    return $response->json();
}

// 1. Works synchronously at the top level and event loop runs underneath automatically!
$user = getUser(1); 

// 2. Works concurrently when wrapped in async() and no changes to getUser() needed!
$promises = [
    async(fn() => getUser(1)),
    async(fn() => getUser(2))
];

[$user1, $user2] = await(Promise::all($promises));

The "color" lives at the call site, not inside your functions. You can sprinkle async logic into existing codebases without rewriting your entire application.

Fractal Concurrency (Fibers + Processes)

Fibers (introduced in PHP 8.1) are perfect for I/O (like HTTP requests or DB queries). But if you try to parse a 50MB CSV inside a Fiber, your entire event loop freezes. Fibers do not run in parallel; they run concurrently on a single thread.

To get true CPU parallelism, Hibla includes Hibla Parallel: a cross-platform, self-healing multi-processing engine.

Because the entire ecosystem is built on a unified Promise interface, the Event Loop doesn't care if a Promise is waiting for an I/O Fiber or an OS-level Process. You can mix them seamlessly:

use Hibla\Parallel\Parallel;
use function Hibla\{async, await};

// Boot a persistent worker pool
$pool = Parallel::pool(size: 4)->boot();

// Mix I/O and CPU work in the exact same loop!
$results = await(Promise::all([
    // I/O Bound: Handled by a Fiber (Non-blocking)
    async(fn() => fetch_api_data()),

    // CPU Bound: Handled by a background OS Process (True Parallelism)
    $pool->run(fn() => crunch_heavy_numbers())
]));

No pcntl_fork cloning nightmares. No deadlocks. And yes, it works natively on Windows (Hibla automatically swaps anonymous pipes for socket descriptors to guarantee true non-blocking I/O across all operating systems).

Structured Cancellation (No More Orphaned Tasks)

When a user clicks "Cancel", or a 30-second API timeout hits, what happens to your background tasks? In many systems, the promises are ignored, but the underlying HTTP requests and background processes keep burning resources until they finish.

Hibla Cancellation introduces .NET-style CancellationTokens. You pass a token into your workflow, and when you cancel the source, everything tracked by that token aborts immediately.

use Hibla\Cancellation\CancellationTokenSource;
use function Hibla\{async, await};

// Automatically cancel everything if it takes longer than 10 seconds
$cts = new CancellationTokenSource(timeoutSeconds: 10.0);

$workflow = async(function () use ($cts) {
    try {
        // By passing the token, Hibla tracks the promise automatically
        $user = await(Http::get('/api/user/1'), $cts->token);

        // If the 10s timeout hits while this parallel process is running,
        // Hibla literally kills the OS worker process instantly!
        $report = await(Parallel::task()->run(fn() => build_report()), $cts->token);

        return $report;
    } catch (\Hibla\Promise\Exceptions\CancelledException $e) {
        echo "Workflow aborted and all resources freed cleanly!";
    }
});

await($workflow);

Under the hood, in-flight cURL requests are aborted, stream watchers are removed, and background OS processes are terminated via full tree-kill. Zero resource leaks.

Async Race Conditions (Yes, they exist in PHP now)

Because PHP is single-threaded, developers often assume we don't have to worry about race conditions. In async PHP, this assumption is dangerous.

Every time a Fiber calls await(), it yields control to the event loop. Another Fiber can wake up and modify shared state while your first Fiber is asleep.

To solve this, Hibla Sync provides async-aware Mutex and Semaphore primitives. They never block the OS thread; they simply queue Fibers cooperatively.

use Hibla\Sync\Mutex;
use function Hibla\{async, await};

$mutex = new Mutex();
$cache = [];

async(function () use ($mutex, &$cache, $key) {
    // Only one Fiber can enter this block at a time.
    // Other Fibers are queued non-blocking.
    await($mutex->withLock(function () use (&$cache, $key) {

        if (!isset($cache[$key])) {
            // Safe! No other Fiber can sneak in while we are awaiting this heavy DB call.
            $cache[$key] = await(fetch_from_database($key));
        }

    }));
});

Zero-Boilerplate Event Loop

At the heart of all this is the Hibla Event Loop. It automatically uses ext-uv (libuv) for massive scale, but falls back to a pure-PHP stream_select implementation if extensions aren't available.

The best part? You never have to call $loop->run().

Hibla utilizes PHP's register_shutdown_function. You just write your code, and when the synchronous script finishes, the loop automatically takes over and drains all pending async tasks, timers, and background processes.

use Hibla\EventLoop\Loop;

// That's it. Just schedule the work.
Loop::addTimer(1.0, fn() => echo "Fired after 1 second!\n");

// The script ends, and the loop automatically runs.

The Vision

PHP 8.4 is an incredibly powerful language. With Fibers, we have the tools to build systems with massive concurrency and fault-tolerant background processing natively.

The Hibla Ecosystem is my attempt to take those raw tools and mold them into a cohesive, elegant, and developer-friendly experience.

You can explore the source code, read the extensive documentation, and try it out today:

hiblaphp/async - Context-independent async/await
hiblaphp/promise - Promises and structured concurrency combinators
hiblaphp/event-loop - The dual-driver core engine
hiblaphp/parallel - Self-healing multi-processing clusters
hiblaphp/cancellation - Structured cancellation tokens
hiblaphp/sync - Async-aware Mutex and Semaphores

If you find this exciting for the future of PHP, please consider dropping a ⭐️ on the GitHub repositories. It helps immensely with visibility and keeps open-source momentum going!

What are your thoughts on the current state of Async PHP? Let me know in the comments!

True Parallel PHP is Here: Elegant Parallelism, Worker Pools, Self-Healing Clusters & Fractal Concurrency

Reymart A. Calicdan — Wed, 29 Apr 2026 17:19:33 +0000

True Parallel PHP is Here: Elegant Parallelism, Worker Pools, Self-Healing Clusters & Fractal Concurrency

For years, the PHP community has repeated the same mantra: "PHP is single-threaded."

Recently, Fibers (introduced in PHP 8.1) solved the I/O problem. We can now make non-blocking HTTP requests and database queries concurrently. But what happens when you need to parse thousands of massive HTML documents, crunch complex math, or process images?

Fibers block the CPU. If you run a heavy regex on a 5MB string, your entire event loop freezes.

To get true CPU parallelism, you usually have to mess with complex extensions (ext-parallel) or write clunky proc_open wrappers where passing data feels like writing an old-school TCP socket protocol or relying on pcntl wrapper libraries.

I wanted something that felt as natural as writing standard async PHP. So, I built Hibla Parallel: a cross-platform, self-healing, multi-processing engine for PHP 8.4+.

Here’s a look at what makes its syntax and architecture special.

Crossing the Boundary: Value Objects & Clean Syntax

In Hibla, you don't have to manually encode/decode JSON to talk to your background processes. It handles the serialization of closures, variables, and objects seamlessly.

Pass objects in, get objects out.

use App\ValueObjects\ReportResult;
use function Hibla\{parallel, await};

// Spawn a background process, run the closure, and wait for the result
$result = await(parallel(function () {
    $data = heavy_data_processing();

    // Return a rich Value Object directly from the worker
    return new ReportResult(
        status: 'success', 
        rowsProcessed: 50000,
        data: $data
    );
}));

echo get_class($result); // "App\ValueObjects\ReportResult"
echo $result->rowsProcessed; // 50000

Under the hood, Hibla handles the OS-level IPC (Inter-Process Communication), reconstructs your objects, and preserves their types.

Seamless Framework Bootstrapping

When you spawn a new PHP process, it starts as a blank slate. If you want to use Laravel's Eloquent ORM, Symfony's container, or your own legacy global functions inside a worker, you need to load them.

Hibla makes this a one-liner using withBootstrap(). It loads your environment into the worker seamlessly:

use Hibla\Parallel\Parallel;

$pool = Parallel::pool(size: 4)
    // Boot Laravel (or Symfony, etc.) inside every worker process automatically
    ->withBootstrap(__DIR__ . '/bootstrap/app.php', function (string $file) {
        $app = require $file;
        $app->make(Illuminate\Contracts\Console\Kernel::class)->bootstrap();
    });

// Now you can freely use your ORM and framework helpers inside the closure!
$pool->run(function () {
    return User::where('active', true)->count();
});

Persistent Worker Pools

Spawning a new process for every small task is expensive, especially if your worker needs to boot up a heavy framework every time.

Hibla solves this with persistent Worker Pools featuring a beautifully expressive, fluent API. You boot the pool and the framework once, and the workers stay alive to crunch through your queue.

$tasks = [/* 10,000 heavy items */];

foreach ($tasks as $item) {
    // Workers are reused. No framework boot penalty per task!
    $pool->run(function () use ($item) {
        return process_item($item);
    })->then(fn($result) => echo "Done: $result\n");
}

$pool->shutdown();

How Does it Compare to Python's Multiprocessing?

Python is famous for making data processing easy, but its multiprocessing library has some infamous quirks. Because of how Python spawns processes across different OS environments (like Windows), you are forced to wrap your execution logic in an if __name__ == '__main__': block, or you trigger an infinite fork bomb.

Python (concurrent.futures):

import concurrent.futures

def process_item(item):
    return item * 2

# This guard is strictly required on Windows and macOS!
if __name__ == '__main__': 
    items = [1, 2, 3, 4, 5]
    with concurrent.futures.ProcessPoolExecutor(max_workers=4) as pool:
        results = list(pool.map(process_item, items))
        print(results)

PHP (Hibla Parallel):
Hibla handles closure AST serialization and fork-bomb prevention safely under the hood. No boilerplate guards required. Using our Promise::map utility combined with the pool's runFn() factory, it becomes a beautiful one-liner:

use Hibla\Parallel\Parallel;
use Hibla\Promise\Promise;
use function Hibla\await;

$pool = Parallel::pool(size: 4);
$items = [1, 2, 3, 4, 5];

// Map concurrently across the process pool without double-wrapping closures!
$results = await(
    Promise::map($items, $pool->runFn(fn($item) => $item * 2))
);

$pool->drain();
print_r($results);

It feels just like writing modern, asynchronous JavaScript, but you are utilizing every CPU core on your server.

Fault-Tolerant Parallelism (The Supervisor Pattern)

In distributed systems, things fail. A worker might hit an Out-Of-Memory (OOM) error, cause a segmentation fault, or trigger a fatal exit(1). In most PHP libraries, this deadlocks your queue or crashes the parent process.

Hibla brings Erlang’s "Let it Crash" philosophy to PHP. If a worker dies, Hibla immediately detects the crash, spawns a fresh replacement to maintain pool capacity, and fires an onWorkerRespawn hook so you can resubmit the lost work.

But true fault tolerance isn't just about recovering from crashes, it's about preventing state corruption and memory leaks. Long-running PHP scripts naturally accumulate memory over time.

To solve this, Hibla gives you PHP-FPM style worker management. You can set hard limits on execution time, memory, and automatically recycle workers to keep RAM usage perfectly flat:

use Hibla\Parallel\Parallel;

$pool = Parallel::pool(size: 4)
    // 1. Proactive Limits: Kill any rogue task taking longer than 60 seconds
    ->withTimeout(60)

    // 2. Memory Sandbox: Isolate the worker's memory limit
    ->withMemoryLimit('256M')

    // 3. FPM-Style Recycling: Retire and replace the worker after 100 tasks 
    // to cleanly flush all framework state and memory leaks
    ->withMaxExecutionsPerWorker(100)

    // 4. Circuit Breaker: Shut down the pool if >5 workers crash in 1 second
    ->withMaxRestartPerSecond(5)

    // 5. Supervisor Hook: Resubmit long-running tasks to the replacement worker
    ->onWorkerRespawn(function ($pool) use ($daemonTask) {
        echo "Worker recycled or crashed! Spawning replacement & resubmitting...\n";
        $pool->run($daemonTask); 
    });

With this setup, your application stays online, recycles its own memory automatically, heals itself from segfaults, and alerts you when things go critically wrong. It's production-grade process supervision, out of the box.

Real-Time Output Streaming

One of the most frustrating things about traditional PHP background processes is that echo and print get swallowed until the process finishes (or they break the IPC protocol entirely).

Hibla intercepts PHP's output buffer and streams it back to the parent process in real-time, completely non-blocking.

use function Hibla\{parallel, await};

await(parallel(function () {
    echo "Starting process...\n";
    sleep(1);
    echo "50% complete...\n";
    sleep(1);
    echo "Finished!\n";
}));
// The parent console prints these lines immediately as they happen in the worker!

Structured Message Passing

Sometimes raw console output isn't enough. If you are running a long-lived task and need to send structured data (like progress updates, partial JSON records, or value objects) back to the parent before the task finishes, Hibla provides the emit() and onMessage() APIs.

Just like return values, emitted messages cross the process boundary with their types preserved:

use Hibla\Parallel\Parallel;
use App\Messages\ProgressUpdate;
use function Hibla\emit;

Parallel::task()
    // The parent process listens for messages asynchronously
    ->onMessage(function ($msg) {
        if ($msg->data instanceof ProgressUpdate) {
            echo "Worker {$msg->pid}: {$msg->data->percent}% complete\n";
        }
    })
    ->run(function () {
        // The worker emits data back to the parent mid-execution
        emit(new ProgressUpdate(percent: 25));
        do_heavy_work();
        emit(new ProgressUpdate(percent: 100));

        return "Task Done!";
    });

This is perfect for building real-time progress bars, logging systems, or streaming data out of a massive batch job.

Exception Teleportation

Debugging distributed systems is a nightmare. Usually, if a child process dies, you just get a generic "Process exited with code 255" error.

Hibla features Exception Teleportation. If your worker throws an exception, Hibla catches it, serializes it, teleports it back to the parent, and merges the stack traces.

use function Hibla\{parallel, await};

try {
    await(parallel(function () {
        throw new \InvalidArgumentException("Invalid CSV format!");
    }));
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // "Invalid CSV format!"

    // The stack trace shows exactly where the parallel() call started 
    // AND where the exception was thrown inside the worker!
    echo $e->getTraceAsString(); 
}

The Holy Grail: Fractal Concurrency

This is where Hibla flexes its architectural muscles. Because Hibla is built on top of a unified Promise and Event Loop system, it doesn't care if a Promise is waiting for an I/O Fiber or an OS-level Process.

You can seamlessly mix async I/O (Fibers) and parallel CPU work (Processes). I call this Fractal Concurrency and from the event loop's perspective, it's all just streams.

Practical Example: High-Performance Web Scraping

Imagine you need to scrape and extract data from 10,000 URLs.

Fetching the HTML is network-bound (I/O). We should use Fibers for this.
Parsing the DOM (running regex or heavy DOM tree parsing) is CPU-bound. If we do this in a Fiber, we block the loop. We should distribute this across our CPU cores using a Process Pool.

By combining Hibla Parallel with the newly released async-first Hibla HTTP Client, we can build a wildly efficient, non-blocking scraper in just a few lines of code:

use Hibla\Parallel\Parallel;
use Hibla\HttpClient\Http;
use Hibla\Promise\Promise;
use function Hibla\await;

// 1. Boot a persistent pool with 1 worker per CPU core
$pool = Parallel::pool(size: 8)->boot();

$urls = [/* 10,000 URLs */];

// 2. Map over the URLs with a concurrency limit of 50 active tasks
$scrapedData = await(Promise::map($urls, function(string $url) use ($pool) {

    // Step A (I/O Bound): Fetch the HTML asynchronously using a Fiber.
    // No process is spawned here. The Event Loop just handles the sockets.
    $response = await(Http::get($url));
    $html = $response->body();

    // Step B (CPU Bound): Offload the heavy HTML parsing to a background worker.
    // The Event Loop is NOT blocked while the worker parses the DOM!
    $parsedResult = await($pool->run(function () use ($html) {
        return my_heavy_dom_parser($html);
    }));

    return $parsedResult;

}, concurrency: 50));

$pool->shutdown();

echo "Successfully parsed " . count($scrapedData) . " pages!";

Why this is amazing:
The Event Loop is orchestrating HTTP socket streams and IPC process streams simultaneously. While Core 1 is parsing HTML, the main thread is downloading the next 49 pages. You get near the raw speed of Go or Node.js, entirely in PHP, without blocking a single thread.

True Cross-Platform Non-Blocking Parallel execution (Yes, Even on Windows)

Have you ever actually run a true parallel PHP script on a Windows machine?

Chances are, you haven't. Or if you did, it broke unexpectedly. Almost all existing PHP multiprocessing libraries rely on pcntl_fork(). There are two massive problems with this:

pcntl simply does not exist on Windows. Your code immediately breaks if you share it with a teammate on a Windows dev environment.
Even on Linux, pcntl_fork() is incredibly dangerous. It clones the entire memory space of the parent process. Shared database connections, Redis instances, and event loops get duplicated across children, leading to bizarre race conditions, corrupted connections, and segfaults.

Hibla doesn't use pcntl_fork(). It spawns fresh, perfectly isolated OS processes using proc_open(). They share nothing, meaning zero chance of corrupted database connections.

But wait, isn't spawning processes from scratch slow?
Yes, it can be. But that is exactly why Hibla features Persistent Worker Pools. Because the workers boot up once and stay alive to receive tasks over IPC streams, the process creation overhead is amortized to zero. The performance impact becomes completely negligible.

But there is a dark secret to proc_open(): Anonymous pipes on Windows ignore stream_set_blocking(false). A blocking read on a Windows pipe will freeze your entire PHP event loop instantly.

Hibla fixes this at the architectural level. When you spawn a worker, Hibla detects your OS. On Linux/macOS, it uses highly optimized kernel pipes. On Windows, it automatically swaps the transport layer to use socket descriptors, ensuring true, 100% non-blocking I/O.

Your code behaves identically on your local Windows dev machine and your production Linux server. No deadlocks. No memory-cloning hacks. Just pure parallelism.

Final Thoughts

I built the Hibla ecosystem because I wanted the multi-processing and async power of modern languages, but with the elegant, standard syntax of modern PHP.

If you are building high-performance CLI apps, web scrapers, daemons, or background workers in PHP, I'd love for you to try it out.

Check out and learn more about the repos here:

hiblaphp/parallel (true parallel engine)
hiblaphp/http-client (high performance elegant http-client)

(Make sure to drop a ⭐️ on GitHub if you find it useful!)

Let me know what you think in the comments! How are you currently handling heavy background processing in your PHP apps?