README

The official Laravel SDK for sending durable HTTP calls, webhooks, callbacks, email, Slack, Discord, Microsoft Teams and Google Chat 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')
    ->to('second-customer@example.com')
    ->cc('audit@example.com')
    ->cc(['operations@example.com', 'legal@example.com'])
    ->bcc('archive@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();

$result = Queuebeam::discord()
    ->destination('engineering')
    ->message('Deployment failed')
    ->dispatch();

$result = Queuebeam::teams()
    ->destination('operations')
    ->message('Queue backlog exceeded 1,000 jobs')
    ->delay(new DateInterval('PT5M'))
    ->dispatch();

$result = Queuebeam::googleChat()
    ->destination('incidents')
    ->message('Payment provider is degraded')
    ->retries(5)
    ->dispatch();

Create named destinations in the Queuebeam dashboard so credentials stay out of application code. When needed, every message channel also accepts a direct incoming webhook URL:

Queuebeam::discord()
    ->webhookUrl('https://discord.com/api/webhooks/...')
    ->message('Hello from Queuebeam')
    ->dispatch();

Queuebeam::webhook('smoke.test')
    ->destination('webhook')
    ->payload(['source' => 'queuebeam-demo'])
    ->dispatch();

Direct webhook URLs are credentials. Keep them in secrets or environment variables, never commit them, and prefer named destinations in production.

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.

Operation status and smoke tests

Use the returned operation ID to inspect delivery without accessing the dashboard:

use Driade\Queuebeam\Facades\Queuebeam;
use Illuminate\Support\Str;
use RuntimeException;

$result = Queuebeam::slack()
    ->destination('smoke-slack')
    ->message('Queuebeam smoke test')
    ->metas(['suite' => 'providers', 'run_id' => (string) Str::uuid()])
    ->dispatch();

$operation = Queuebeam::waitForOperation(
    $result->operation_id,
    timeout_ms: 30_000,
    poll_interval_ms: 500,
);

if ($operation->status !== 'succeeded') {
    throw new RuntimeException("Delivery ended as {$operation->status}");
}

operation() returns the latest state and safe attempt history. It never returns payloads, provider credentials or remote response bodies. operations() lists project-scoped operations with status, type, date and cursor filters:

$page = Queuebeam::operations(status: 'dead_letter', type: 'email', limit: 50);

foreach ($page->operations as $operation) {
    // $operation->operation_id, status, response_status and attempt_history
}

$next_page = $page->next_cursor === null
    ? null
    : Queuebeam::operations(status: 'dead_letter', type: 'email', limit: 50, cursor: $page->next_cursor);

For email, succeeded means the configured provider accepted the message. Confirming final inbox delivery additionally requires provider delivery events.

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.

driade / queuebeam-laravel

Maintainers

Package info

Statistics

Security