README

Laravel queue driver for Oxide, built on top of mrfelipemartins/oxide-php.

This package registers an oxide queue connector, so Laravel can dispatch, delay, retry, fail, monitor, and clear jobs through the normal queue APIs.

Requirements

• PHP 8.2+
• Laravel 12 or 13
• A running Oxide server

Installation

composer require mrfelipemartins/oxide-laravel

Publish the optional defaults file:

php artisan vendor:publish --tag=oxide-queue-config

Configuration

Add an Oxide connection to config/queue.php:

'connections' => [
    'oxide' => [
        'driver' => 'oxide',
        'host' => env('OXIDE_HOST', '127.0.0.1'),
        'port' => (int) env('OXIDE_PORT', 7379),
        'auth_token' => env('OXIDE_AUTH_TOKEN'),
        'queue' => env('OXIDE_QUEUE', 'default'),
        'retry_after' => (int) env('OXIDE_RETRY_AFTER', 90),
        'block_for' => env('OXIDE_BLOCK_FOR') !== null
            ? (int) env('OXIDE_BLOCK_FOR')
            : null,
        'after_commit' => false,
    ],
],

Then set:

QUEUE_CONNECTION=oxide
OXIDE_HOST=127.0.0.1
OXIDE_PORT=7379
OXIDE_AUTH_TOKEN=

The published config/oxide-queue.php file contains the full set of defaults for stream creation, claim batching, acknowledgement batching, timeouts, and worker behavior. Values in config/queue.php override those defaults for that connection.

Usage

Dispatch jobs exactly as you would with any Laravel queue connection:

ProcessPodcast::dispatch($podcast);
ProcessPodcast::dispatch($podcast)->onConnection('oxide')->onQueue('high');
ProcessPodcast::dispatch($podcast)->delay(now()->addMinutes(5));

Run workers with Laravel's queue commands:

php artisan queue:work oxide --queue=high,default
php artisan queue:monitor oxide:default --max=1000
php artisan queue:clear oxide --queue=default --force

Job Metadata

Laravel payloads are stored unchanged. The driver derives Oxide metadata from normal Laravel payload fields:

• uuid is used as the Oxide idempotency key.
• retryUntil is used as the Oxide deadline.
• maxTries and the first backoff value are used for the Oxide retry policy.
• retry_after is used as the claim lease / TTR.

Jobs can optionally provide Oxide-specific metadata:

public function oxideLaneKey(): ?string
{
    return 'account:' . $this->accountId;
}

public function oxidePriority(): int
{
    return 10;
}

public function oxideHeaders(): array
{
    return ['tenant_id' => (string) $this->tenantId];
}

Behavior Notes

• Oxide delivery is at-least-once, so jobs should be idempotent.
• Laravel failed-job storage remains Laravel-owned.
• When Laravel finally fails a job, the Oxide work item is acknowledged and removed.
• With --queue=high,default, only the first queue uses blocking waits; secondary queues are polled so priority order stays predictable.
• queue:clear removes ready, delayed, and claimed jobs by default. Stop workers before clearing if you do not want running jobs removed, or set clear_claimed=false.

Testing

composer test
composer lint