Queuebeam for Laravel

The official Laravel SDK for sending durable HTTP calls, webhooks, callbacks, email and Slack operations through Queuebeam.

Requirements

• PHP 8.2 or newer
• Laravel 10, 11, 12 or 13. Laravel 10 and 11 compatibility is provided on a best-effort basis because those framework versions no longer receive security fixes.

Installation

composer require driade/queuebeam-laravel
php artisan vendor:publish --tag=queuebeam-config

QUEUEBEAM_URL=https://api.queuebeam.cloud
QUEUEBEAM_API_KEY=qb_live_your_key
QUEUEBEAM_THROWS=true
QUEUEBEAM_TIMEOUT_MS=3000
QUEUEBEAM_ATTEMPTS=3

Laravel discovers QueuebeamServiceProvider and the Queuebeam facade automatically.

Usage

use Driade\Queuebeam\Facades\Queuebeam;

$result = Queuebeam::http()
    ->post('https://example.com/orders', ['order_id' => 8472])
    ->metas(['order_id' => 8472])
    ->idempotencyKey('order-8472')
    ->dispatch();

$result = Queuebeam::email()
    ->to('customer@example.com')
    ->cc('audit@example.com')
    ->subject('Order sent')
    ->html('<p>Your order is on its way.</p>')
    ->dispatch(throws: false);

$result = Queuebeam::slack()
    ->destination('operations')
    ->message('Order blocked')
    ->dispatch();

Every builder supports scheduling, delays, retries, idempotency and metadata. DispatchResult exposes the acceptance state, operation ID, HTTP error information and quota headers returned by Queuebeam, including whether the tenant has unlimited quota.

Configuration

Per-call dispatch(throws: false) overrides the global QUEUEBEAM_THROWS setting. Programming errors such as invalid PHP types are never swallowed.

QUEUEBEAM_TIMEOUT_MS is the total timeout for each request from your Laravel application to Queuebeam, expressed in milliseconds. QUEUEBEAM_ATTEMPTS is the maximum number of calls, including the initial call; its default of 3 therefore means one initial call and up to two retries.

The SDK retries connection errors, timeouts, HTTP 408, 425, 429 and 5xx responses. Authentication, quota and validation failures are returned immediately. Every dispatch without an explicit idempotency key receives a generated key that remains stable across its attempts, preventing a lost 202 response from creating duplicate operations.

QueuebeamException exposes the failed DispatchResult through its $result property, so applications using exception mode can still inspect the HTTP status, error and retryability. Responses with Retry-After are respected up to 30 seconds.

The published configuration can also be edited directly:

return [
    'base_url' => env('QUEUEBEAM_URL', 'https://api.queuebeam.cloud'),
    'api_key' => env('QUEUEBEAM_API_KEY'),
    'throws' => env('QUEUEBEAM_THROWS', true),
    'timeout_ms' => (int) env('QUEUEBEAM_TIMEOUT_MS', 3000),
    'attempts' => (int) env('QUEUEBEAM_ATTEMPTS', 3),
];

Runtime configuration is also supported:

Queuebeam::configure(timeout_ms: 5000, attempts: 5);

Testing

bash format.sh
composer analyse
composer test

License

Queuebeam for Laravel is open-source software licensed under the MIT license.