Queue Bundle Laravel Package

Getting Started

• Install with composer require roslov/queue-bundle:^2.2.1. Pinning to ^2.2.1 (rather than ^2.2) matters here — 2.2.1 contains the exception shortener fix, and 2.2.0 will happily satisfy the looser constraint on existing installs.
• Runtime floor is unchanged in this release; the PHP 8.4/8.5 work is confined to the test matrix. That is a signal you can run the package on 8.4/8.5 in your own CI with reasonable confidence, but it is not a hard guarantee of production-grade 8.5 support — smoke-test your worker process on the new PHP version before rolling it out.
• Look first at: the bundle's DI extension class and its configuration tree, the console command that runs the worker, and the persistence layer (entity/migration) behind the queue table. Those three files tell you more about operational behaviour than the README does.
• First use case: a single low-risk producer → worker loop. Push one job type onto the queue from a controller, run the worker in the foreground with verbose output, and watch the queue table drain. Confirm the retry/failure path by throwing deliberately inside the handler before you wire up anything important.
• Laravel caveat up front: this is a Symfony-style bundle, not a Laravel package. There is no package auto-discovery, no vendor:publish of config, no facade. Budget for a thin bridge (a service provider that registers the bundle's services and a small Artisan command that invokes the worker) rather than assuming composer require is the whole job.

Implementation Patterns

• Producer/consumer split. Enqueue from your HTTP layer, consume in a long-running worker process. Keep the job payload small and serialisable — IDs, not Eloquent models. This package's persistence model means a payload referencing a stale model will fail at consumption time, not enqueue time.
• Thin job adapter. Rather than letting application code call the bundle's queue API directly everywhere, wrap it: App\Queue\Dispatcher with push(Job $job): void. When you eventually migrate to a native Laravel queue driver (or the reverse), you change one class instead of every call site.
• Transactional enqueue is the classic trap. Enqueueing inside a DB::transaction means the worker can pick up a job whose row is not yet committed. Either enqueue after the transaction commits (DB::afterCommit) or accept at-least-once semantics and make handlers idempotent. Prefer the latter as the default posture.
• Idempotency by design. Assume every handler can run twice. Guard writes with unique constraints or updateOrCreate keyed on a business identifier carried in the payload.
• Bridge the worker into Artisan. A queue:work-bundle command that bootstraps the bundle's container and runs its worker loop keeps your ops runbook (php artisan ..., Horizon-style supervision, deploy hooks) uniform with the rest of the app.
• Config as code. Since there is no vendor:publish, build the bundle's config array in a dedicated config/queue_bundle.php and translate it in your service provider. This gives you env-var control and makes the mapping reviewable in a diff.
• Testing. Use a synchronous/in-memory transport for unit tests of handlers, and reserve the real persistence-backed queue for a small number of integration tests that assert the round trip, including the failure path.

Gotchas and Tips

• The exception shortener fix is the only behavioural change in 2.2.1. If you parse, display, or alert on stored failure messages, re-read a sample of failed-job rows after upgrading. Previously shortened exception messages could be malformed or truncated mid-word; anything keyed off message prefixes (alert routing, error grouping) may shift. Test this explicitly if you have dashboards built on those strings.
• No breaking changes, no deprecations in this release. The remaining items (coding style, .editorconfig, .gitattributes, README dependency bumps, typos) are cosmetic. The one to sanity-check is .gitattributes: if export-ignore rules changed, composer install --prefer-dist archives may now include or omit files differently than 2.2.0. Rarely matters, occasionally breaks tooling that reads package files from vendor/.
• Framework mismatch is the dominant pitfall. Expect to hand-wire: service registration, the console command, and configuration translation. Do not assume Symfony's autowiring conventions apply — Laravel's container will not resolve Symfony service definitions for you.
• Worker lifecycle. Long-running workers leak memory and hold stale container state. Set a --max-jobs/--timeout equivalent and recycle the process; always run under a supervisor (Supervisor, systemd, or a queue-aware orchestrator) rather than in a terminal.
• Poison messages. Know exactly how many attempts your config permits and where failed jobs land. Without a dead-letter view you will discover failures only when a customer complains.
• Debugging. Run the worker with the highest verbosity flag the command supports and tail the queue table directly. When a job silently vanishes, the cause is almost always (a) a payload that fails to unserialise, or (b) a handler exception swallowed by the retry logic.
• Upgrade hygiene for a patch release. The diff is small (changelog 2.2.0...2.2.1 is four PRs). Read it, run your test suite, and deploy to a canary worker first — the risk here is concentrated in the error-reporting path, which by definition only fires when something else is already wrong.
• Extension points worth locating early: the job handler resolution strategy and the failure/retry policy hooks. Both are the usual places you need per-job-type behaviour, and retrofitting them after the queue is load-bearing is painful.