Commands Queues Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package — the first decision is whether it belongs in your stack at all. In Laravel you already have php artisan queue:work, dispatch(), and Artisan::queue(); this bundle exists to give a Symfony app the same "enqueue a console command, run it in a background worker" capability, persisted through Doctrine. If you're a Laravel dev, the realistic use cases are: (a) you maintain/consult on a Symfony app and need to wire this in, or (b) you're reading it to borrow the design for a custom "command queue" table in Laravel.

Minimal steps in a Symfony app:

1. composer require serendipity_hq/commands-queues-bundle
2. Register the bundle in config/bundles.php (or AppKernel::registerBundles() on older Symfony).
3. Run bin/console doctrine:schema:update --force (or generate/run a migration) to create the queue table backed by the bundle's Doctrine entities.
4. Inspect the config under config/packages/ — the bundle exposes settings for the queue table/entity and processing behavior; publish or hand-write the YAML keyed to the bundle alias.
5. Discover the worker command with bin/console list | grep -i queue and dry-run it against a trivial command (e.g. enqueue cache:clear).

Where to look first: the Doctrine entity for queued commands (the table is the whole state machine), the worker/processor console command, and the service you call to enqueue. First real use case: enqueue one of your existing, slow console commands (report generation, imports, cache warmers) instead of running it inline, then run the worker under supervisor/systemd and watch rows move from queued → running → done/failed.

Implementation Patterns

Enqueue from app code, process out-of-band. Treat enqueueing like Laravel's dispatch(): your controller/service writes a "queued command" row (command name + arguments + priority), returns immediately, and a separate long-running worker consumes it. Keep enqueueing cheap and never run heavy work in the request cycle.

Worker supervision. Run the worker as a daemon (supervisor/systemd), not from a request. In Laravel terms this is queue:work; here you're shelling out Symfony console commands per row, so each "job" is a full process — expect higher overhead per item than a Laravel job.

Status lifecycle as the source of truth. Model your monitoring off the row status/state column(s): queued, in-progress, completed, failed. This is what makes the bundle usable — you can query the table for stuck or failed items, exactly like inspecting failed_jobs in Laravel, and build a small admin view over it.

Prioritize and batch. Use the priority field (if exposed) to push critical commands ahead of bulk work, and enqueue in loops for batch imports — but throttle enqueue rate so the table doesn't balloon and the worker doesn't starve.

Scheduling the enqueue side. Cron/Symfony Scheduler should enqueue, while the worker process drains. Keep these two concerns separate so a missed cron doesn't stall the worker and vice versa.

Porting the pattern to Laravel. If you like the model but live in Laravel, you don't need the bundle — implement a queued_commands table with command, payload, status, priority, attempts, output, timestamps, enqueue via Artisan::queue($command, $args) on the database driver, or use Bus::batch() for grouped work. Use Artisan::call() inside a job only when you specifically need console-command semantics (output capture, exit codes) rather than a plain job class.

Gotchas and Tips

• Doctrine coupling. State lives in the ORM; deploy migrations with your release, and be wary of schema drift between environments. Don't hand-edit the table.
• Concurrency and races. A single worker is serial and safe but slow. Multiple workers can pick the same row unless the bundle uses row locking — verify and, if needed, add SELECT ... FOR UPDATE/SKIP LOCKED semantics or a claimed-by column yourself.
• No built-in Laravel-style retries/backoff (likely). Inspect the worker for failure handling; if retries aren't native, add an attempts counter and requeue logic in a wrapper, and always store stderr/exit code for debugging.
• Long-running commands block the queue. One hung command starves everything behind it. Set per-command timeouts or isolate heavy commands into a separate queue/worker.
• Overlaps with Symfony Messenger. On modern Symfony, Messenger + a transport is the idiomatic successor. Choose this bundle when you specifically want to queue console commands verbatim; choose Messenger for message-based async work.
• Config caching. After changing bundle config run bin/console cache:clear; stale config is the usual cause of "my new setting is ignored."
• Extension points. Lean on Symfony events/subscribers (if the bundle dispatches pre/post-process events) for logging, metrics, and alerting rather than forking the worker — that's the cleanest way to add observability to a fairly minimal bundle.
• Small ecosystem. ~10 stars, zero dependents: read the source before depending on it. Pin the version, expect to maintain it yourself, and keep a fallback (Messenger, or a custom table-driven worker) in mind.
• Exit-code discipline. Since each job shells out to a console command, a non-zero exit is your only universal failure signal — make sure your commands return meaningful codes and that the worker records them.