Sqs Queue Bundle Laravel Package

Getting Started

Be clear-eyed about the first step: this is a Symfony bundle, not a Laravel package. There is no service provider, no config/queue.php driver, and nothing that plugs into queue:work. In a pure Laravel app you would not install it at all — Laravel already ships a first-party SQS driver via aws/aws-sdk-php, and QUEUE_CONNECTION=sqs plus config/queue.php gives you everything this bundle offers, wired into the framework's worker, retries, and failed-job table. Installing a 2020-era Symfony bundle into Laravel means fighting the container for no gain.

So the realistic day-to-day leverage falls into two buckets:

1. Mixed-stack bridging. A Laravel app produces into SQS; a Symfony service (which may use this bundle) consumes. Or the reverse. You need to understand this bundle's message envelope so the two sides agree on payload shape.
2. Reference reading. The bundle is small enough to read end-to-end in an hour. Its consumer loop, visibility-timeout handling, and handler dispatch are a decent template if you're writing a custom SQS consumer as an artisan command.

Minimal steps if you do need it on the Symfony side:

composer require tritran/sqs-queue-bundle

Then, in order — this is the order that saves time:

1. Read DependencyInjection/Configuration.php first, not the README. For a package this size the config schema is the documentation, and the README examples are frequently stale relative to the tree. That file tells you the exact YAML keys, defaults, and whether credentials are required inline.
2. Register the bundle in config/bundles.php (Symfony Flex) or AppKernel::registerBundles() (older).
3. Configure config/packages/<bundle>.yaml with region, credentials, and queue URL/name. Expect AWS SDK v3-era key names (key, secret, region, queue_url or similar) — verify against step 1.
4. Implement the bundle's handler interface for your message type, tag it as a service, and let the bundle's consumer command dispatch to it.
5. Run the consumer under a process supervisor (supervisor, systemd) — never in a request cycle.

First use case worth shipping: a single low-volume async job — thumbnail generation, transactional email, webhook fan-out — where the producer is one send() call and the consumer is one handler class. Do not start with FIFO, batching, or DLQ redrive; get one message round-tripping first.

Implementation Patterns

Producer pattern (Laravel side). Ignore the bundle and use the framework: dispatch(new GenerateThumbnail($id)) on an sqs connection. If you need to emit a message that the Symfony consumer understands, use Queue::connection('sqs')->pushRaw(json_encode($payload), $queueUrl) and keep the envelope hand-rolled and documented. This is the single most common integration shape and it costs you nothing in dependencies.

Producer pattern (Symfony side, if using the bundle). Inject the bundle's producer service rather than constructing an SQS client yourself — that keeps endpoint/region/credential config in one place. Serialize to JSON, keep the message body minimal, and put routing metadata in SQS message attributes rather than inside the JSON so the consumer can filter without deserializing.

Consumer pattern. Long-running worker process, one handler per message type, dispatched by a type field or attribute. Return normally on success (message deleted); throw on failure (message returns to the queue after visibility timeout, up to maxReceiveCount before DLQ). Keep the handler idempotent — SQS is at-least-once no matter what the wrapper claims. Dedupe on a business key stored in a unique index or a short-TTL cache entry.

Visibility timeout tuning. Set the queue's visibility timeout to comfortably exceed your p95 handler runtime — 6× is the AWS rule of thumb. A worker that takes 90s against a 30s visibility timeout will be re-delivered mid-flight and processed twice. This bites harder in this bundle than in Laravel because Laravel's worker will extend the visibility lock for you; a hand-rolled or third-party consumer usually won't.

Bridging envelopes. Laravel's SQS payload is a structured job envelope (uuid, displayName, job, data, attempts, …). This bundle almost certainly does not speak that format, and Laravel's worker won't parse this bundle's format. If you bridge the two, pick one side to own the envelope and write an explicit adapter — do not assume either consumer will "just deserialize" the other's messages. Verify by dumping one raw message from each side with aws sqs receive-message --queue-url ... --max-number-of-messages 1.

Local development. Point both sides at ElasticMQ or LocalStack via an endpoint override in config, and run the consumer in a terminal rather than under supervisor. Round-trip a message locally before touching a real queue.

Testing. Unit-test the handler in isolation by invoking it with a decoded array; you do not need SQS in the loop. Reserve integration tests (LocalStack) for the send/receive plumbing.

Gotchas and Tips

The release date is the headline risk. Last release 2020-02-19. That predates most of the PHP 8.x line and Symfony 6. Expect composer conflicts against a modern aws/aws-sdk-php, and expect the bundle's service definitions to fail autowiring or to reference removed Symfony APIs. Budget a fork-and-patch or a composer why-not investigation before promising it works. With 27 stars and zero dependents, you are the only one who will hit the bug.

No Laravel integration exists, and none is coming. No service provider, no facade, no queue:work support, no failed-job table, no retry_after mapping. Anything Laravel gives you for free — backoff, --tries, --timeout, Horizon-style monitoring — you rebuild by hand on the Symfony side.

Credentials in config. A 2020-era bundle very likely wants inline key/secret in YAML. Do not do that in a real deployment. Use an IAM role on the instance/task, or environment variables resolved at container compile time. Check Configuration.php for whether the fields are isRequired() — if they are, you may need to pass dummy values and let the SDK's default credential provider chain do the work.

Configuration is the API. With so little documentation, DependencyInjection/Configuration.php and the bundle's service XML/YAML are the authoritative source. Read them before every "why isn't it autowiring" debugging session.

256 KB message limit and 14-day retention are SQS invariants the bundle cannot paper over. Large payloads go to S3 with a pointer in the message body. Messages not consumed within the retention window are silently gone — for anything you can't afford to lose, this is the wrong queue primitive.

FIFO is probably unsupported. If you need ordering or deduplication IDs (MessageGroupId, MessageDeduplicationId), verify explicitly. Most thin wrappers from this era are standard-queue only, and adding FIFO support means patching sendMessage params — an easy fork if it isn't there.

Long polling. If the consumer uses short polling you'll burn money on empty receives and see high CPU idle. Confirm WaitTimeSeconds = 20 is set; if it isn't configurable, that alone justifies forking.

Debugging in production: watch CloudWatch ApproximateNumberOfMessagesVisible (backlog), ApproximateAgeOfOldestMessage (stalled consumer), and the DLQ's NumberOfMessagesSent (poison messages). Pull raw messages with aws sqs receive-message --visibility-timeout 0 — zero visibility means you can inspect without stalling the real worker.

Extension points: the producer and consumer are ordinary services, so decoration is the clean lever — decorates: the bundle's producer to add logging or envelope translation, and decorate the handler dispatcher to add metrics. Avoid editing vendor/; a fork on GitHub with "repositories": [{"type": "vcs", ...}] in your root composer.json is more maintainable than a patch file if you expect more than one fix.