Pipeline Bundle Laravel Package

Getting Started

1. Install the package via Composer (e.g. composer require phd/pipeline) and let Laravel auto-discover the service provider.
2. Publish the config if the package ships one: php artisan vendor:publish --tag=phd_pipeline-config. The main file is typically config/phd_pipeline.php.
3. Register the middleware alias phd_pipeline.forward_chain in your HTTP kernel (app/Http/Kernel.php) or, on Laravel 11+, in bootstrap/app.php via $middleware->alias([...]).
4. Look first at:
   • src/Attributes/NextForwarded.php – the new attribute that declares the next message/handler in a chain.
   • src/Middleware/ForwardChainMiddleware.php – the middleware that reads the attribute and performs the forwarding.
   • The package README section on “Chained forwarding” for a ready-made example.
5. First use case: annotate a message class with #[NextForwarded(NextMessage::class)], add the phd_pipeline.forward_chain middleware to the pipeline that processes that message, then dispatch the message as usual. The middleware will automatically forward to NextMessage after the current handler completes.

Implementation Patterns

• Attribute-driven chains – Define a chain declaratively by placing #[NextForwarded(...)] on each message class. The middleware resolves the attribute at runtime, so you don’t need to hard-code forwarding logic in your handlers.
• Pipeline middleware stack – Add phd_pipeline.forward_chain to the middleware list of the pipeline that handles your messages. Order matters: place it after any middleware that must run before forwarding (e.g. validation) and before middleware that should see the forwarded message.
• Multiple forwards – If the attribute is repeatable, you can declare several #[NextForwarded] attributes to fan-out to multiple next messages. Check the package source for whether it supports an array or repeated attributes.
• Queued forwarding – When the forwarded message should be processed asynchronously, combine the attribute with a queued handler. The middleware dispatches the next message through the same pipeline, so queue configuration on the next message/handler is respected.
• Testing – Use Laravel’s Pipeline facade fake or the package’s own test helpers (if provided) to assert that a given message forwards to the expected next class without running the entire chain.
• Integration with existing pipelines – The middleware is designed to be additive. You can keep your existing pipeline stages and simply append phd_pipeline.forward_chain at the point where forwarding should occur.

Gotchas and Tips

• Middleware alias registration – Forgetting to register phd_pipeline.forward_chain is the most common cause of “nothing happens”. Double-check Kernel.php or bootstrap/app.php and clear config cache (php artisan config:clear).
• Infinite loops – Chained forwarding can create cycles (A → B → A). The package may not detect cycles automatically; add a max-depth guard or ensure your chain is acyclic.
• Attribute target – #[NextForwarded] is likely intended for classes. Applying it to methods or properties will silently do nothing. Verify the attribute’s #[Attribute] target flags.
• Config cache – If you change the middleware alias or the attribute’s target class, run php artisan config:clear and php artisan cache:clear in development.
• Debugging – Log inside the middleware or use Laravel Telescope to inspect the pipeline payload. The forwarded message class is a good log point to confirm the chain is progressing.
• Extension points – If the default forwarding resolver doesn’t fit your needs (e.g. dynamic next-class resolution based on payload), look for a container binding or config key that lets you swap the resolver. The middleware is usually written against an interface, so you can decorate or replace it.
• Version 1.0.0 stability – As a first stable release, the attribute API is now public. Pin the version in composer.json (^1.0) and review the upgrade guide for any pre-1.0 breaking changes if you were using a dev version.