Pipeline Laravel Package

Getting Started

1. Install via Composer: composer require sanmai/pipeline
2. Import the core class: use Sanmai\Pipeline\Pipeline;
3. Start with a simple chain of operations — for example, transforming an order object through validation → discount application → formatting:

   $result = (new Pipeline())
       ->pipe(fn ($order) => $order->validate())
       ->pipe(fn ($order) => $order->applyDiscounts())
       ->pipe(fn ($order) => $order->formatForOutput())
       ->run($initialOrder);
   

4. First use case: replace a monolithic service method with clearly separated, testable steps.

Implementation Patterns

• Use with value objects or DTOs: Each stage modifies immutable state or returns a new object/array.
• Type hints and PHPDoc: Annotate pipeline payloads with @var or generic types (e.g., Pipeline<Order, FormattedOrder>) for IDE and static analysis support.
• Dependency injection: Register reusable pipeline stages as services (e.g., ValidateOrderStage::class) and inject into pipelines or pipeline builders.
• Conditional branching via pipeIf(): Insert conditional logic:

  $pipeline->pipeIf($isPremium, fn ($user) => $user->upgrade());
  

• Integration with Laravel: Use in App\Actions, job middleware, or as part of form request handling (format() and authorize() chains). Wrap logic around $request->all() or custom DTOs.
• Testing: Mock each stage with a simple callable and assert payload at each pipe() boundary or at the end. Use debug() to peek into intermediate states.

Gotchas and Tips

• Pitfall: Passing by reference in stages may cause unexpected mutation — prefer immutability or explicit cloning.
• Pitfall: Over-chaining leads to deep nesting — break large pipelines into smaller ones composed via compose():

  $validation = (new Pipeline())->pipe(...)->pipe(...);
  $processing = (new Pipeline())->pipe(...)->pipe(...);
  $full = $validation->compose($processing);
  

• Tip: Use debug() to inspect the payload mid-pipeline without breaking flow:

  $pipeline->pipe(fn ($x) => $x + 1)
           ->debug('After increment') // logs or yields payload
           ->pipe(fn ($x) => $x * 2);
  

• Tip: For error handling, wrap stages in try/catch or use pipe(fn () => throw ...) — but prefer graceful return of error objects (e.g., Result DTO) to keep pipeline state explicit.
• Extension point: Create custom Stage classes implementing __invoke() to share complex logic (e.g., rate limiting, transaction wrapping).
• Performance: Each pipe() adds negligible overhead — avoid dynamic stage injection inside loops; build and reuse pipelines instead.