Pipeline Laravel Package

Getting Started

Install via composer require league/pipeline. Begin by defining stages as invokable classes or closures, then chain them with Pipeline::pipe(). The core workflow is simple:

1. Create a pipeline: (new Pipeline)
2. Add stages: ->pipe($stage1)->pipe($stage2)
3. Execute: ->process($payload)

Start with the Basic Example in the README – it demonstrates transforming data through sequential stages with zero boilerplate. For Laravel integration, inject stages via the service container and use pipelines in service classes or console commands.

Implementation Patterns

• Laravel Command Bus Alternative: Replace monolithic handle() methods with staged pipelines (e.g., ValidateRequest → Authorize → Execute → FormatResponse). Keeps each concern isolated and testable.
• API Request/response Pipelines: Chain PSR-7/15 converters, HTTP clients, and JSON parsers into reusable sub-pipelines (e.g., $apiRequestPipeline = (new Pipeline)->pipe(new FormatUrl)->pipe(new AddHeaders)->pipe(new ExecuteRequest)). Nest them in higher-level workflows.
• Event-Driven Processing: Use pipelines to structure event listeners where order matters (e.g., NormalizePayload → EnrichData → PersistToDb → NotifyExternal).
• Configuration-Driven Stages: Leverage PipelineBuilder to assemble pipelines dynamically from config (e.g., in config/pipelines.php), enabling environment-specific stage toggling without code changes.

Gotchas and Tips

• Immutability is non-negotiable: pipe() always returns a new pipeline instance. Many devs accidentally forget $pipeline = $pipeline->pipe($stage) and wonder why stages vanish. Add strict types (declare(strict_types=1)) in stage classes to catch method signature mismatches early.
• Exception handling is passive: The package never catches exceptions. Wrap process() calls in try-catch blocks outside the pipeline, or add a TryCatchStage class that rethrows inside a try {} block if needed.
• Callable flexibility ≠ type safety: While any callable works, using typed StageInterface implementations (or PSR-4 autoloading with strict PHPDocs) prevents runtime errors. Avoid closures for complex logic – they’re hard to unit test and mock.
• Pipeline reuse is powerful but subtle: Nesting pipelines (->pipe($subPipeline)) creates a new composite stage. Verify expected payload types change between stages (e.g., OrderDto → Command → Result) to avoid confusion. Use PHPStan/Psalm for deep type checking.
• Testing tip: Test stages in isolation (they’re just __invoke() methods), then test pipelines as integration points. Mock HTTP clients in stages with Prophecy, and assert on payload transformation at each step.