Configure the Laravel driver

Last updated: October 13, 2026

BabelQueue plugs into Laravel’s queue system as a custom connection driver, then adds its own URN routing and dead-letter config.

Queue connection

Add a BabelQueue connection in config/queue.php. Use babelqueue-redis for the Redis transport:

// config/queue.php
'connections' => [

    'babelqueue' => [
        'driver'     => 'babelqueue-redis',
        'connection' => 'default',
        'queue'      => env('BABELQUEUE_QUEUE', 'default'),
        'retry_after' => 90,
    ],

],

Or babelqueue-rabbitmq for the RabbitMQ transport:

// config/queue.php
'connections' => [

    'babelqueue' => [
        'driver' => 'babelqueue-rabbitmq',
        'host'   => env('RABBITMQ_HOST', '127.0.0.1'),
        'port'   => env('RABBITMQ_PORT', 5672),
        'queue'  => env('BABELQUEUE_QUEUE', 'default'),
    ],

],

Package configuration

config/babelqueue.php maps incoming URNs to handler classes and controls what happens to messages with an unknown URN:

// config/babelqueue.php
return [

    // Map each URN to the handler that consumes it.
    'handlers' => [
        'urn:babel:orders:created' => App\Babel\Handlers\OrderCreatedHandler::class,
    ],

    // What to do when an incoming URN has no registered handler:
    // 'fail' | 'delete' | 'release' | 'dead_letter'
    'on_unknown_urn' => 'dead_letter',

    // Where exhausted / unroutable messages go. Failures from "orders"
    // are republished to "orders.dlq" as the same envelope plus an
    // additive `dead_letter` block, so any SDK can triage them.
    'dead_letter' => [
        'enabled' => true,
        'suffix'  => null, // null = ".dlq" ("-dlq" on an Amazon SQS connection)
    ],

];

All keys

Key	Default	Meaning
`handlers`	`[]`	URN to handler class map.
`on_unknown_urn`	`'fail'`	Strategy for an unmapped URN: `fail`, `delete`, `release` or `dead_letter`. `dead_letter` only quarantines when `dead_letter.enabled` is on; otherwise it drops.
`unknown_urn_release_delay`	`0`	Seconds of delay applied when `on_unknown_urn` is `release`.
`connection`	`null` (`BABELQUEUE_CONNECTION`)	Queue connection `BabelQueue::publish()` uses by default. It must point at a `babelqueue-*` connection in `config/queue.php` (`babelqueue-redis`, `babelqueue-rabbitmq`, `babelqueue-sqs` or `babelqueue-artemis`); `null` uses the app’s default queue connection.
`dead_letter.enabled`	`false` (`BABELQUEUE_DLQ_ENABLED`)	Turns the cross-language DLQ on.
`dead_letter.connection`	`null`	Connection to publish the DLQ onto (`null` is the message’s own).
`dead_letter.queue`	`null`	Explicit DLQ name (`null` is the original queue name plus `suffix`).
`dead_letter.suffix`	`null` (`.dlq`; `-dlq` on Amazon SQS)	Appended to the original queue name when `queue` is `null`. `null` resolves to `.dlq` on every driver except an Amazon SQS connection (`babelqueue-sqs` or the stock `sqs` driver), where it is `-dlq` because SQS queue names cannot contain a dot. An explicit value wins.
`idempotency.enabled`	`false` (`BABELQUEUE_IDEMPOTENCY_ENABLED`)	Dedupe deliveries on `meta.id`. See Idempotency.
`idempotency.store`	`'redis'` (`BABELQUEUE_IDEMPOTENCY_STORE`)	`redis`, `database` or `memory`; or rebind `BabelQueue\Idempotency\IdempotencyStore` in the container to your own store. The `redis` store requires a predis-backed connection (`redis.client = 'predis'` in `config/database.php`, with `predis/predis` installed); under the default `phpredis` client it throws `InvalidArgumentException` — pick `database` or switch the client.
`idempotency.connection`	`null` (`BABELQUEUE_IDEMPOTENCY_CONNECTION`)	Redis or database connection name for the store (`null` is that store’s default connection).
`idempotency.ttl`	`3600` (`BABELQUEUE_IDEMPOTENCY_TTL`)	Seconds an in-flight claim is held before a crashed worker’s id can be re-claimed (claiming `redis` / `database` stores).
`idempotency.table`	`'bq_idempotency'`	Dedupe table for the `database` store.
`idempotency.prefix`	`'bq:idem:'`	Key namespace for the `redis` store.

Next: Producing messages.