Weave Code
Pipeline Bundle Laravel Package
phphd/pipeline-bundle
A Symfony bundle for building reusable PHP pipelines with a clean, stage-based API. Chain processing steps, pass data through each stage, and organize complex workflows into testable, configurable components that fit naturally into Symfony applications.
A streamlined implementation of Chain of Responsibility pattern on top of Symfony Messenger component
Frequently asked questions about Pipeline Bundle
- What is phphd/pipeline-bundle and what problem does it solve?
- It is a Chain of Responsibility implementation built on top of Symfony Messenger, packaged as a bundle with a stage-based API for reusable pipelines. The release adds the #[NextForwarded] PHP 8 attribute, which declares a message's next forwarding target, plus a phd_pipeline.forward_chain middleware alias that walks the resulting chain. Routing intent lives on the message class instead of a config array or switch statement, so chains are colocated, discoverable, and testable. The pattern maps conceptually onto Laravel's Illuminate\Pipeline.
- How do I install and register phphd/pipeline-bundle?
- Install it with Composer using composer require phphd/pipeline-bundle. Then register the phd_pipeline.forward_chain middleware alias in the relevant pipeline or kernel configuration. Annotate exactly one low-risk message class with #[NextForwarded] and exercise it behind a feature flag before rolling out further. Note that it ships as a Symfony bundle, so confirm bundle/service-provider registration works in your framework before depending on it.
- Does phphd/pipeline-bundle support Laravel 10, 11 and 12?
- Laravel 10, 11 and 12 support is assumed in the technical assessment but explicitly unverified. PHP 8.1 or newer is required because the API relies on attribute syntax. Check the package's composer.json constraints for the actual Illuminate and PHP version ranges before adopting it. If the constraints are missing or loose, treat compatibility as something you must prove with a spike.
- How does #[NextForwarded] compare to Laravel's Bus::chain()?
- Both express multi-step dispatch, but #[NextForwarded] colocates routing intent on the message class, so you can find usages through your IDE instead of reading a config array or switch statement. Bus::chain() is built into Laravel and has no extra dependency, while this package is aimed at replacing hand-rolled forwarding logic. Before choosing it, verify that the middleware composes cleanly with dispatch(), Bus::chain(), and queue middleware without double-forwarding the same message. If it does, it is a net reduction in bespoke code; if not, stick with the framework primitive.
- Is chain depth bounded and are cycles detected at boot or at dispatch?
- There is no stated termination guarantee, which the assessment flags as the single largest risk. A self-referencing or mutually-referencing #[NextForwarded] pair can turn one inbound message into an unbounded queue and CPU loop. You need an explicit answer on cycle detection at boot or compile time, plus a hard depth cap, before this reaches production. Treat both as verification tasks rather than design objections.
- What happens when a message has no #[NextForwarded] attribute?
- The behaviour is not documented: forwarding could stop quietly, throw an exception, or log a warning. Undefined semantics here is exactly how messages silently vanish in production. Test the zero-attribute case explicitly and, if it is a silent no-op, add your own guard or assertion. Do not assume a failure will surface on its own.
- Is #[NextForwarded] repeatable for fan-out, or single-valued for a linear chain?
- The assessment lists this as an open question, and the answer determines whether you get a linear chain or fan-out to N targets. Repeatable attributes imply fan-out amplification, which multiplies queue volume and makes cycle risk worse. Single-valued means a strictly linear chain that is easier to reason about and cap. Confirm which it is before modelling any workflow on it.
- Is phphd/pipeline-bundle safe under Laravel Octane or long-running workers?
- Attribute reads are reflection calls, so any attribute-to-class map the package caches must be invalidated on deploy. Under Octane or FrankenPHP, a stale cache means old chains silently persist across worker reloads. The assessment rates this a medium risk and asks where the attribute-to-target map is cached and whether it is reload-safe. Verify that behaviour with a deploy-and-reload test, not just a local run.
- How are failures, retries and dead letters handled across pipeline hops?
- The package documentation says nothing about retry, dead-letter, or idempotency semantics when hop N fails after hop N-1 already succeeded. You need to know whether retries are per-hop, whole-chain, or fail-fast, because each choice changes your failure surface. Design every stage to be idempotent so a replayed hop cannot duplicate side effects. If the semantics are unclear, wrap stages in your own retry and dead-letter policy rather than relying on defaults.
- Is phphd/pipeline-bundle production-ready at version 1.0.0?
- Treat the version number as intent, not evidence: a 1.0.0 semver claim with a thin changelog suggests an asserted API contract rather than a battle-tested one. There is no installed base, so migration is purely additive, which makes a cautious trial cheap. Feature-flag the first annotated message class, watch queue depth and failure rates, and expand only after cycle handling and retry behaviour are proven. Also clarify the ownership and support model for the phd_ namespace before it becomes load-bearing.
Weaver
How can I help you explore Laravel packages today?