configured/race

Race for Laravel: run multiple attempts concurrently and return the first valid result.

v0.2.1 2026-05-05 13:46 UTC

Requires

• php: ^8.3
• ext-pcntl: *
• ext-posix: *
• ext-sockets: *
• illuminate/support: ^11.0|^12.0|^13.0
• spatie/fork: ^1.2.7

Requires (Dev)

• laravel/boost: ^2.4
• orchestra/testbench: ^9.15|^10.6|^11.1
• pestphp/pest: ^3.8

MIT

• Joe Campo

README

Run multiple forked attempts concurrently and return the first valid result.

Race for Laravel requires PHP 8.3+, PCNTL, POSIX, and socket support. It does not use queues, so times: 5 means five child processes are forked immediately from the current PHP process.

Installation

composer require configured/race:^0.1.0

Publish the config file if you want to customize timing behavior:

php artisan vendor:publish --tag=race-config

return [
    'poll_interval_ms' => 10,
    'execution_buffer_seconds' => 5,
];

execution_buffer_seconds is added to the race timeout when Race temporarily raises PHP's max_execution_time. For example, timeout(60) with the default buffer sets the process execution limit to 65 seconds while the race runs, then restores the previous limit.

Usage

$result = race(
    times: 3,
    timeout: 20,
    callback: fn () => Ai::agent()->prompt($prompt, timeout: 15),
    valid: fn ($result) => filled((string) $result),
    map: fn ($result) => (string) $result,
);

use Configured\Race\Exceptions\RaceFailedException;

$result = Race::times(3)
    ->timeout(20)
    ->valid(fn ($result) => filled($result))
    ->map(fn ($result) => (string) $result)
    ->failed(function (RaceFailedException $failure): string {
        logger()->warning('All race attempts failed.', [
            'attempts' => $failure->attempts(),
            'timed_out' => $failure->timedOut(),
            'failures' => $failure->failures(),
            'invalid_results' => $failure->invalidResults(),
        ]);

        return 'fallback';
    })
    ->run(CheckFlakyApi::class, [
        'prompt' => $prompt,
    ]);

The first attempt that passes the valid callback wins. Remaining child processes are terminated and ignored.

The failed callback runs only when the whole race fails. It receives a RaceFailedException with the number of attempts, failed attempt details, invalid results, and whether the race timed out. If the callback returns a value, that value is returned as the race result.

Available failure details:

$failure->attempts();       // Total attempts considered by the race.
$failure->timedOut();       // True when child processes were still running at timeout.
$failure->failures();       // Thrown attempt errors: attempt, class, message.
$failure->invalidResults(); // Results that completed but failed your valid callback.