Understanding Laravel pipelines

1.ProcessClass.php

<?php
namespace App\Features;

use App\Features\FirstTask;
use App\Features\SecondTask;
use Illuminate\Pipeline\Pipeline;

// *Naming things is hard* ... So, this is a class called `ProcessClass` that `run()` some text ¯\_(ツ)_/¯

class ProcessClass
{
    protected $pipes;

    public function __construct()
    {
        $this->pipes = $this->loadPipes();
    }

    public function loadPipes()
    {
        return [
            FirstTask::class,
            SecondTask::class
        ];
    }

    public function run($text)
    {
        return app(Pipeline::class)
            ->send($text)
            ->through($this->pipes)
            ->then(function ($text) {
                return $text . "finally";
            });
    }
}

2.FirstTask.php

<?php

namespace App\Features;

use Closure;

class FirstTask
{
    /**
     * Changes the given text and return the result
     **/
    public function handle($text, Closure $next)
    {
        return $next($text . ' [first task] ');
    }
}

3.SecondTask.php

<?php

namespace App\Features;

use Closure;

class SecondTask
{
    /**
     * Changes the given text and return the result
     **/
    public function handle($text, Closure $next)
    {
        return $next($text . ' [second task] ');
    }
}

4.PipelineTest.php

<?php

namespace Tests\Feature;

use Tests\TestCase;
use App\Features\ProcessClass;

class PipelineTest extends TestCase
{

    public function testExample()
    {
        $text = 'Initial test';
        $object = new ProcessClass($text);
        $result = $object->run($text);
        $this->assertEquals('Initial test [first task]  [second task] finally', $result);
    }
}

5.RESULT.md

PHPUnit 6.2.4 by Sebastian Bergmann and contributors.

...                                                                 3 / 3 (100%)

Time: 136 ms, Memory: 14.00MB

OK (3 tests, 3 assertions)

Quick question: jumping out of a pipeline midway through - is that only possible by throwing an exception? For example, how does the Laravel middleware auth provider break the chain and issue a redirect if an auth task finds the user is not authenticated?

When you call $next($text); you basically call the next function. If you don't call it the chain is broken.

Yes, I realised you can return anything other than the next closure, and the chain will break out immediately, returning that value you returned. Looking at the code, that seems to be the way it is designed to work, but does not seem to be explicitly mentioned in the documentation or any tutorials I have found.

A (possibly) simpler, more native approach:

Extend ProcessClass (or rather ProcessPipeline for readability) with Illuminate\Pipeline\Pipeline and then simply provide a protected array of pipes:

class ProcessPipeline extends Pipeline {
    protected $pipes = [
        FirstTask::class,
        SecondTask::class,
    ];
}

Then when calling it:

$result = app(ProcessPipeline::class)
    ->send($content)
    ->thenReturn(); // or then()

Apart from the simplicity, it also would then go through Laravel's service provider -- pass any dependencies into the pipe's constructor for automatic DI for example.

Quick question: jumping out of a pipeline midway through - is that only possible by throwing an exception? For example, how does the Laravel middleware auth provider break the chain and issue a redirect if an auth task finds the user is not authenticated?

@judgej found anything? I was struggling with the same and found this to be good enough:

Registered a global exception handler for any exception a pipe might throw (bootstrap/app.php, ->withExceptions(function (Exceptions $exceptions) { in newer Laravel versions).

Example:

->withExceptions(function (Exceptions $exceptions) {
        $exceptions->render(function (\App\Exceptions\BusinessRuleViolationException $e, Request $request) {
             // return back() with errors

Each individual pipe would then of course throw new BusinessRuleViolationException when applicable, break the chain, and the user would see the error message I set.