Bqueuebundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package — that's the first thing to internalize. It wraps a database-backed (Doctrine) message queue with a producer/consumer model. In a Laravel codebase you have two realistic entry points:

1. As a standalone library — pull it in with Composer and wire its services into Laravel's container manually.
2. As a sidecar Symfony service — run the producer/consumer inside a small Symfony app and have Laravel push/poll over HTTP or a shared DB.

Minimal steps:

composer require strnoar/bqueuebundle

• Check the composer.json constraints first. Given the zero-star, zero-dependent footprint, expect an older Symfony (2.x/3.x) and pre-PHP 8 constraint — you will likely need --ignore-platform-reqs or a fork.
• Register the bundle in AppKernel/bundles.php (Symfony) or publish a service provider that binds its dispatcher and consumer classes into Laravel's container.
• Run the bundle's schema migration to create the queue table (typically a jobs/bqueue table with status, payload, priority, retry count).
• Dispatch your first job by pushing a serialized payload to the dispatcher, then start the consumer command in a foreground terminal so you can watch output.

First use case: a small background job (resize an image, send an email) enqueued from a request handler, picked up by a long-running console command. Do this in isolation before trusting it with anything critical.

Implementation Patterns

Producer/consumer via DB table. The core pattern is: a producer INSERTs a row, a worker polls for pending rows, marks them processing, runs your handler, then marks done or increments retries. Everything hinges on that table's state.

Laravel queue driver adapter. Write a class implementing Illuminate\Contracts\Queue\Queue that delegates push() to BQueue's dispatcher and pop() to its consumer's claim logic. Register it in config/queue.php under a custom connection. This keeps your jobs portable and lets you swap back to Redis/SQS later.

Supervision. The consumer is a blocking polling loop. Run it under Supervisor/systemd with --timeout, restart-on-exit, and log rotation. Do not run it from a web request.

Priority and retry. Model tries and backoff explicitly in your wrapper, mapping them onto whatever columns BQueue exposes (priority int, attempts int, available_at). Don't assume Laravel's semantics survive.

Integration tip: treat the queue table as a boundary. Producers and consumers should only touch it through the bundle's API, so a future migration to Laravel's native queue means rewriting one adapter, not every call site.

Idempotency wrapper. Because retries re-run the payload, wrap handlers in an idempotency guard (unique job key) — a DB-backed lock table works and matches the stack's existing style.

Gotchas and Tips

• Maturity risk is real. Zero stars, zero dependents, Symfony-era code. Treat this as unmaintained: vendor it, pin the commit, and expect to maintain a fork. Check for PHP 8 / modern Symfony compatibility before committing.
• Not a Laravel queue. No Horizon, no dispatch()->onQueue(), no native event hooks. Don't try to bolt Laravel's ShouldQueue contract straight onto it without the adapter in place.
• Polling overhead. A DB-polling consumer means steady queries and potential lock contention under load. Verify whether it uses SELECT ... FOR UPDATE or SKIP LOCKED; without row-level locking you will double-process jobs when you scale to multiple workers.
• Serialization. Payloads are likely PHP serialize(). Closures, resources, and non-serializable objects will fail silently or loudly depending on error handling. Prefer arrays and plain DTOs.
• Failures get stuck. If the worker crashes mid-job, rows can sit in processing forever. Add a reaper query that resets stale claims older than a threshold.
• Debugging. Inspect the queue table directly (SELECT status, attempts, priority, payload FROM ...) — it's your source of truth. Tail consumer output; the bundle's verbosity may be low, so add your own logging around the handler.
• Retry/backoff quirks. Confirm whether backoff is linear or exponential and whether attempts reset on manual replay. Test with a job that throws every time.
• Extension points. Look for bundle events (pre/post dispatch, job failed) and the handler registration mechanism — that's where you inject metrics, tracing, and dead-letter routing rather than editing the vendor code.