Pqueue Bundle Laravel Package

Product Decisions This Supports

• Adding background processing without a queue service. This package gives a first-party async job pipeline (dispatcher, worker, handler discovery) inside an existing Symfony app. It supports the decision to ship long-running or bursty work — email/notification fan-out, image or document processing, report/export generation, webhook retries, third-party API syncs — off the request cycle rather than bolting on a separate queue platform.
• Build vs. buy for queueing. With a filesystem transport as the default, this is the "lowest-friction, no new infrastructure" option in the build/buy matrix. It lets you defer (or avoid) a managed queue purchase while validating whether async processing actually matters to the product. If volume, cross-service fan-out, or guaranteed delivery become requirements, the buy decision gets revisited with real data.
• Architecture decision: queue-agnostic boundaries. Because the package wires the Dispatcher and Consumer as DI services behind configuration, the product can commit to "jobs are dispatched through an internal interface" and treat the transport as a swappable implementation detail. That reduces the cost of a later migration and keeps the decision reversible.
• Roadmap sequencing for async features. Handler auto-discovery via config means new job types are additive, low-ceremony work. That supports scheduling a series of incrementally-released async features (v1: single job type; v2: retries and scheduling) without re-platforming each time.
• Operational levers as product requirements. The pqueue:worker:run command exposes memory-limit and time-limit options, which supports defining SLOs and operational runbooks — worker recycling, restart strategy, and container sizing — as explicit product/ops commitments rather than implicit assumptions.
• Scope decision: framework fit. This release targets Symfony integration, so it supports roadmap decisions for Symfony-based services. If your product surface is Laravel, this is not a fit for the primary queue path; it would only be relevant for a Symfony service inside a polyglot estate.

When to Consider This Package

Consider it when:

• You are on Symfony (this release is Symfony integration of michel/pqueue, not a Laravel package) and want queueing with minimal new vendor footprint.
• You are pre-product-market-fit or in an internal tool / MVP where a filesystem-backed transport is acceptable and operational simplicity outweighs throughput and durability guarantees.
• You want configuration-driven job registration — handlers declared via config/packages/pqueue.yaml — so adding a job type is a config change rather than bespoke wiring.
• Your team values a small, understandable surface: one worker command, a dispatcher, a consumer, no dashboard, no proprietary protocol.
• You are prototyping async processing and deliberately want to defer a queue vendor decision until volumes are known.

Look elsewhere when:

• Version maturity is a hard gate. 0.0.1-alpha means no stability guarantees, likely no deprecation policy, and API churn should be assumed. Do not put revenue-critical or exactly-once workloads on it.
• You need durability and delivery guarantees beyond what a filesystem transport provides — multi-node consumption, at-least-once semantics under crash, poison-message handling, dead-letter queues.
• You need retries, backoff, scheduling/delayed jobs, priorities, or rate limiting. None are described in this release; treat them as absent until documented.
• You need observability: queue depth metrics, per-job latency, failure dashboards, alerting. Not present here; you would build it.
• You need managed hosting, autoscaling workers, or a UI for operations/support staff.
• Your estate is Laravel-first — Laravel's native queue abstraction already covers this ground with broader transport support and a mature ecosystem.

How to Pitch It (Stakeholders)

To executives: This is a small, low-cost enabler that lets us run work in the background — emails, exports, integrations — without buying queue infrastructure or signing a vendor contract. It is a deliberate "keep the option open" move: the transport is a configuration setting, so if we outgrow it we can swap in a managed service without rewriting the features built on top. The trade-off to state plainly: it is an alpha (0.0.1), suitable for internal tools and early features, not for revenue-critical paths. Recommend funding it as an experiment with a defined review point tied to volume and reliability thresholds.

To engineering: This release integrates michel/pqueue into Symfony with four concrete capabilities: transport configuration (filesystem by default) in config/packages/pqueue.yaml; automatic handler discovery and registration from configured sources and classes; Dispatcher and Consumer exposed as DI services; and a pqueue:worker:run console command supporting memory-limit and time-limit for worker lifecycle management. The integration is thin and idiomatic — adopt it if you want queueing with almost no new concepts. Be explicit about what is not here: no retries/backoff, no delayed or scheduled jobs, no dead-letter handling, no metrics or dashboard, and no stability guarantee at 0.0.1-alpha. Recommended posture: isolate dispatch behind our own interface, keep job handlers side-effect-idempotent, wrap the worker in a supervisor with restart policy, and instrument logging ourselves from day one so a transport swap or an upgrade later is a contained change. Flag that this is a Symfony integration — if the target service is Laravel, we should use the framework's native queue instead.