Amazon SQS driver

Last updated: October 13, 2026

babelqueue-sqs is a drop-in queue connection that makes an Amazon SQS queue polyglot. It extends Laravel’s native sqs driver: jobs that opt into BabelQueue are sent as the canonical envelope with the §3 SQS MessageAttributes, so a Go, Python, Node, Java or .NET worker can route and trace them — while standard Laravel jobs on the same connection pass straight through unchanged.

Requirements

The AWS SDK for PHP is required (Laravel lists it as a suggestion):

composer require aws/aws-sdk-php

Configuration

Add a connection in config/queue.php with driver set to babelqueue-sqs. The config keys are exactly Laravel’s stock sqs keys:

'connections' => [
    'babelqueue-sqs' => [
        'driver' => 'babelqueue-sqs',
        'key'    => env('AWS_ACCESS_KEY_ID'),
        'secret' => env('AWS_SECRET_ACCESS_KEY'),
        'prefix' => env('SQS_PREFIX', 'https://sqs.eu-central-1.amazonaws.com/your-account-id'),
        'queue'  => env('SQS_QUEUE', 'orders'),
        'suffix' => env('SQS_SUFFIX', ''),
        'region' => env('AWS_DEFAULT_REGION', 'eu-central-1'),
    ],
],

The connector mirrors the stock SqsConnector (credentials, prefix/suffix), so anything that works for sqs works here. For LocalStack/ElasticMQ, set an endpoint key as you would for the native driver.

Produce

Producing is identical to the other BabelQueue drivers — see Producing messages. Dispatch a typed ShouldQueuePolyglot job (or use the BabelQueue facade) onto the connection:

use BabelQueue\Facades\BabelQueue;

BabelQueue::onConnection('babelqueue-sqs')
    ->publish('urn:babel:orders:created', ['order_id' => 1042]);

The job is sent as the canonical envelope (MessageBody) with the projected MessageAttributes (bq-job/bq-trace-id/bq-message-id/bq-schema-version/ bq-source-lang/bq-created-at). A plain Laravel job dispatched to the same connection is encoded the normal Laravel way — no envelope, no attributes — so existing workers keep working.

Consume

Run a worker against the connection as usual:

php artisan queue:work babelqueue-sqs

Polyglot messages — including those produced by another language’s SDK — are decoded, routed by URN through the dispatcher and handled; standard jobs run as normal. See Consuming messages for handler registration.

Before decoding, the queue version-gates on the bq-schema-version message attribute (§3.7). A missing or blank value (the empty string, or only ASCII whitespace: space, tab, LF, VT, FF, CR) changes nothing: the body is decoded as usual. Any other value is compared with "1" exactly as sent, with no trimming, so "2", "x", "01" and " 1" are all rejected without decoding the body: the message is handed to the dispatcher’s unsupported-schema-version path instead of a handler. With the dead-letter queue enabled it is quarantined there (reason poison) and deleted; with it disabled the dispatcher throws an InvalidEnvelopeException (unsupported_schema_version), so the worker’s retry and failed_jobs path records it. It is never deleted without a trace. A "1" value does not skip the body check: the decoded envelope still goes through the schema_version validation.

Dead-letter queue name (since 1.10.0). SQS queue names cannot contain a dot, so the cross-language DLQ of an SQS queue is <queue>-dlq (FIFO: <queue>-dlq.fifo), not <queue>.dlq. With dead_letter.suffix left at its default (null), an Amazon SQS connection (babelqueue-sqs or the stock sqs driver) resolves it to -dlq (a FIFO queue keeps .fifo last: orders.fifo → orders-dlq.fifo) and every other driver to .dlq. Create that queue first. An explicit suffix or dead_letter.queue always wins, so a published config that still carries 'suffix' => '.dlq' keeps .dlq.

attempts note. As a Laravel driver, the reserved job surfaces the broker’s native receive count via SqsJob::attempts() (i.e. ApproximateReceiveCount). This is the documented, exempt divergence from the framework-less SDKs, which reconcile attempts to ApproximateReceiveCount − 1 — see the SQS binding.

Because the wire format is the canonical envelope, a message your Laravel app consumes may have been produced by any BabelQueue SDK, and vice-versa.