Pqueue Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package — there is no ServiceProvider, no config/pqueue.php, no Laravel queue driver. If you're working in a Laravel codebase, the realistic first move is to treat the worker as a sidecar process (or use michel/pqueue directly and write a thin service provider), rather than expecting php artisan queue:work parity.

Minimal path:

1. composer require the bundle and register it in config/bundles.php.
2. Open config/packages/pqueue.yaml first — this is the entire surface area of the release. The default transport is Filesystem, so you can dispatch and consume jobs on a single machine with zero infrastructure. Start there before reaching for a broker.
3. Define a handler class, then register it under the bundle's handler discovery config (sources for the directory, classes for explicit entries).
4. Constructor-inject the Dispatcher service wherever you enqueue work, and dispatch a trivial job.
5. Run bin/console pqueue:worker:run and confirm the job is consumed. Run with --help first — the option list (memory/time limits) is the most useful documentation you have in an alpha.

First use case: local development and single-host background processing — image resizing, PDF generation, outbound webhooks — where a Filesystem transport is genuinely sufficient and you don't want Redis in the stack yet.

Implementation Patterns

Config-driven handler registration. The bundle discovers handlers from sources and classes rather than service tags. This is low-friction but means your services.yaml tells you nothing about what's wired — pqueue.yaml becomes the source of truth. Keep the sources directory aligned 1:1 with your autoload namespaces so discovery doesn't drift.

Inject, don't locate. Dispatcher and Consumer are ordinary DI services. Constructor-inject Dispatcher into controllers, console commands, and domain services. Because it's injected, you can swap the underlying transport per environment (Filesystem in test, something durable in prod) without touching call sites.

Supervised long-running worker. Don't run pqueue:worker:run in a terminal and forget it. Set --memory-limit and --time-limit deliberately — the time limit is what lets a supervisor restart the process on a schedule, which is your main defense against memory leaks in an alpha-quality worker. Use supervisor/systemd/container restart policies, and restart workers on every deploy.

Filesystem-as-a-bus for a sidecar. In a Laravel app, the practical integration is a dedicated worker container or supervisor program sharing the queue directory with the app via a volume, with Laravel dispatching through a small adapter service. It's unglamorous but it isolates the Symfony dependency cleanly.

Scale out, not up. Multiple worker processes against the same Filesystem transport is the intended concurrency story on a single host. Beyond one host you need a different transport.

Gotchas and Tips

• 0.0.1-alpha means exactly that. Config keys, the config tree shape, and the command's option names can all change. Pin the exact version in composer.json and avoid exposing the bundle's classes in your own public API.
• Filesystem transport is single-host, full stop. No shared-filesystem-over-NFS heroics. It also makes atomicity/locking behavior the thing to watch for duplicate processing — load-test with two workers before you trust it.
• Silent handler non-discovery is the #1 failure mode. A namespace typo in sources produces a worker that starts cleanly and processes nothing. Verify with bin/console debug:container that Consumer actually received your handlers, and log loudly on unhandled messages.
• Stale services in a long-running process. Handlers are constructed once per worker lifetime. Don't hold request-scoped state, open DB connections, or cache entity managers across jobs — this is the classic Messenger worker pitfall and it will bite you in a bundle this new.
• Config cache. After editing pqueue.yaml, run bin/console cache:clear. A stale container is a very common "my config change did nothing" report.
• No operational scaffolding. There's no failed-job table, retry UI, or metrics endpoint here — no Horizon equivalent. Retries, dead-letter handling, and observability are yours to build inside your handlers. Decide this before you ship, not after.
• Extension points. The transport is configured, not hardcoded, so a broker-backed transport is the intended escape hatch when you outgrow Filesystem. Dispatcher and Consumer are plain services, so decorating them (logging, metrics, tracing) is cheaper than forking the bundle — and decorating survives minor version bumps better than subclassing.