Update pipeline (#17)

## About

- Adds `Conditionable` trait to the pipeline
- Removes helpers, moves the `run` method to the class
- Renames events to have consistent readable names

Author: michael-rubel

.editorconfig

@@ -2,7 +2,7 @@ root = true
 
 [*]
 charset = utf-8
-indent_size = 2
+indent_size = 4
 indent_style = space
 end_of_line = lf
 trim_trailing_whitespace = true

README.md

@@ -10,7 +10,7 @@
 
 Laravel Pipeline with DB transaction support, events and additional methods.
 
-The package requires `PHP 8` or higher and `Laravel 9` or higher.
+The package requires `PHP 8.1` or higher and `Laravel 10` or higher.
 
 ---
 
@@ -49,14 +49,7 @@ Pipeline::make()
     });
 ```
 
-You can use the `pipeline` helper:
-```php
-pipeline($data, [
-    // pipes
-])->thenReturn();
-```
-
-You can as well instantiate the pipeline using IoC or manually:
+You can as well instantiate the pipeline using the service container or manually:
 ```php
 app(Pipeline::class)
     ...
@@ -69,12 +62,14 @@ app(Pipeline::class)
     ...
 ```
 
-You can use the `run` helper to execute a single pipeline-compatible action:
+You can use the `run` method to execute a single pipe:
 ```php
-run(MyAction::class, $data);
+$pipeline = Pipeline::make();
+
+$pipeline->run(Pipe::class, $data);
 ```
 
-By default, `run` uses the `handle` method in your action classes, but if you use a different method name in your pipelines, you can fix that by adding code to your ServiceProvider:
+By default, `run` uses the `handle` method in your class as an entry point, but if you use a different method name in your pipelines, you can fix that by adding code to your ServiceProvider:
 ```php
 $this->app->resolving(Pipeline::class, function ($pipeline) {
     return $pipeline->via('execute');
@@ -93,8 +88,8 @@ Usage of `withTransaction` method will enable a [`manual DB transaction`](https:
 Usage of `withEvents` method will enable [`Laravel Events`](https://laravel.com/docs/9.x/events#introduction) throughout the pipeline execution.
 
 #### Available events
-- [`PipeStarted`](https://github.com/michael-rubel/laravel-enhanced-pipeline/blob/main/src/Events/PipeStarted.php) - fired **before** execution of pipe;
-- [`PipePassed`](https://github.com/michael-rubel/laravel-enhanced-pipeline/blob/main/src/Events/PipePassed.php) - fired **after** execution of pipe.
+- [`PipeExecutionStarted`](https://github.com/michael-rubel/laravel-enhanced-pipeline/blob/main/src/Events/PipeExecutionStarted.php) - fired **before** execution of the pipe;
+- [`PipeExecutionFinished`](https://github.com/michael-rubel/laravel-enhanced-pipeline/blob/main/src/Events/PipeExecutionFinished.php) - fired **after** execution of the pipe.
 
 ## Testing
 ```bash

composer.json

@@ -30,10 +30,7 @@
     "autoload": {
         "psr-4": {
             "MichaelRubel\\EnhancedPipeline\\": "src"
-        },
-        "files": [
-            "src/Helpers/helpers.php"
-        ]
+        }
     },
     "autoload-dev": {
         "psr-4": {

src/Events/PipeStarted.php src/Events/PipeExecutionFinished.phpsrc/Events/PipeStarted.php renamed to src/Events/PipeExecutionFinished.php

@@ -4,7 +4,7 @@
 
 namespace MichaelRubel\EnhancedPipeline\Events;
 
-class PipeStarted
+class PipeExecutionFinished
 {
     /**
      * @param  mixed  $pipe

src/Events/PipePassed.php src/Events/PipeExecutionStarted.phpsrc/Events/PipePassed.php renamed to src/Events/PipeExecutionStarted.php

@@ -4,7 +4,7 @@
 
 namespace MichaelRubel\EnhancedPipeline\Events;
 
-class PipePassed
+class PipeExecutionStarted
 {
     /**
      * @param  mixed  $pipe

src/Helpers/helpers.php

@@ -8,16 +8,17 @@
 use Illuminate\Container\Container as ContainerConcrete;
 use Illuminate\Contracts\Container\Container;
 use Illuminate\Contracts\Pipeline\Pipeline as PipelineContract;
-use MichaelRubel\EnhancedPipeline\Events\PipePassed;
-use MichaelRubel\EnhancedPipeline\Events\PipeStarted;
+use Illuminate\Support\Traits\Conditionable;
+use MichaelRubel\EnhancedPipeline\Events\PipeExecutionFinished;
+use MichaelRubel\EnhancedPipeline\Events\PipeExecutionStarted;
 use MichaelRubel\EnhancedPipeline\Traits\HasDatabaseTransactions;
 use MichaelRubel\EnhancedPipeline\Traits\HasEvents;
 use RuntimeException;
 use Throwable;
 
 class Pipeline implements PipelineContract
 {
-    use HasDatabaseTransactions, HasEvents;
+    use Conditionable, HasDatabaseTransactions, HasEvents;
 
     /**
      * The container implementation.
@@ -73,7 +74,7 @@ public static function make(?Container $container = null): Pipeline
             $container = ContainerConcrete::getInstance();
         }
 
-        return new Pipeline($container);
+        return $container->make(static::class);
     }
 
     /**
@@ -189,15 +190,15 @@ protected function carry()
     {
         return function ($stack, $pipe) {
             return function ($passable) use ($stack, $pipe) {
-                $this->fireEvent(PipeStarted::class, $pipe, $passable);
+                $this->fireEvent(PipeExecutionStarted::class, $pipe, $passable);
 
                 if (is_callable($pipe)) {
                     // If the pipe is a callable, then we will call it directly, but otherwise we
                     // will resolve the pipes out of the dependency container and call it with
                     // the appropriate method and arguments, returning the results back out.
                     $result = $pipe($passable, $stack);
 
-                    $this->fireEvent(PipePassed::class, $pipe, $passable);
+                    $this->fireEvent(PipeExecutionFinished::class, $pipe, $passable);
 
                     return $result;
                 } elseif (! is_object($pipe)) {
@@ -220,7 +221,7 @@ protected function carry()
                                 ? $pipe->{$this->method}(...$parameters)
                                 : $pipe(...$parameters);
 
-                $this->fireEvent(PipePassed::class, $pipe, $passable);
+                $this->fireEvent(PipeExecutionFinished::class, $pipe, $passable);
 
                 return $this->handleCarry($carry);
             };
@@ -302,6 +303,17 @@ public function onFailure(Closure $callback)
         return $this;
     }
 
+    /**
+     * Run a single pipe.
+     */
+    public function run(string $pipe, mixed $data = true): mixed
+    {
+        return $this
+            ->send($data)
+            ->through([$pipe])
+            ->thenReturn();
+    }
+
     /**
      * Handle the value returned from each pipe before passing it to the next.
      *

src/Pipeline.php

@@ -245,6 +245,36 @@ public function testPipelineThenReturnMethodRunsPipelineThenReturnsPassable()
 
         unset($_SERVER['__test.pipe.one']);
     }
+
+    public function testPipelineConditionable()
+    {
+        $result = (new Pipeline(new Container))
+            ->send('foo')
+            ->when(true, function (Pipeline $pipeline) {
+                $pipeline->pipe([PipelineTestPipeOne::class]);
+            })
+            ->then(function ($piped) {
+                return $piped;
+            });
+
+        $this->assertSame('foo', $result);
+        $this->assertSame('foo', $_SERVER['__test.pipe.one']);
+        unset($_SERVER['__test.pipe.one']);
+
+        $_SERVER['__test.pipe.one'] = null;
+        $result = (new Pipeline(new Container))
+            ->send('foo')
+            ->when(false, function (Pipeline $pipeline) {
+                $pipeline->pipe([PipelineTestPipeOne::class]);
+            })
+            ->then(function ($piped) {
+                return $piped;
+            });
+
+        $this->assertSame('foo', $result);
+        $this->assertNull($_SERVER['__test.pipe.one']);
+        unset($_SERVER['__test.pipe.one']);
+    }
 }
 
 class PipelineTestPipeOne

tests/OriginalPipelineTest.php

@@ -6,8 +6,8 @@
 
 use Illuminate\Support\Facades\Event;
 use MichaelRubel\EnhancedPipeline\EnhancedPipelineServiceProvider;
-use MichaelRubel\EnhancedPipeline\Events\PipePassed;
-use MichaelRubel\EnhancedPipeline\Events\PipeStarted;
+use MichaelRubel\EnhancedPipeline\Events\PipeExecutionFinished;
+use MichaelRubel\EnhancedPipeline\Events\PipeExecutionStarted;
 use MichaelRubel\EnhancedPipeline\Pipeline;
 
 class PipelineEventsTest extends TestCase
@@ -41,7 +41,7 @@ public function testFiresPipeStartedEvents()
             ])
             ->thenReturn();
 
-        Event::assertDispatched(function (PipeStarted $event) {
+        Event::assertDispatched(function (PipeExecutionStarted $event) {
             $this->assertInstanceOf(TestPipe::class, app($event->pipe));
             $this->assertSame('data', $event->passable);
 
@@ -59,14 +59,14 @@ public function testFiresPipeStartedEventsButFailsToPass()
             ->onFailure(fn () => true)
             ->thenReturn();
 
-        Event::assertDispatched(function (PipeStarted $event) {
+        Event::assertDispatched(function (PipeExecutionStarted $event) {
             $this->assertInstanceOf(PipelineWithException::class, app($event->pipe));
             $this->assertSame('data', $event->passable);
 
             return true;
         });
 
-        Event::assertNotDispatched(PipePassed::class);
+        Event::assertNotDispatched(PipeExecutionFinished::class);
     }
 
     /** @test */
@@ -81,7 +81,7 @@ public function testFiresPipePassedEvents()
             ])
             ->thenReturn();
 
-        Event::assertDispatched(function (PipePassed $event) {
+        Event::assertDispatched(function (PipeExecutionFinished $event) {
             $this->assertInstanceOf(TestPipe::class, app($event->pipe));
             $this->assertSame('data', $event->passable);
 

tests/PipelineEventsTest.php

@@ -6,31 +6,40 @@
 
 use MichaelRubel\EnhancedPipeline\Pipeline;
 
-class PipelineRunHelperTest extends TestCase
+class PipelineRunTest extends TestCase
 {
-    public function testRunHelperWithoutParams()
+    public function testRunWithoutParams()
     {
-        $executed = run(Action::class);
+        $executed = Pipeline::make()->run(Action::class);
 
         $this->assertTrue($executed);
     }
 
-    public function testRunHelperActionReturnsPassedData()
+    public function testRunReturnsPassedData()
     {
         $data = ['test' => 'yeah'];
 
-        $executed = run(Action::class, with($data));
+        $executed = Pipeline::make()->run(Action::class, with($data));
 
         $this->assertSame('yeah', $executed['test']);
     }
 
-    public function testRunHelperHasCustomizableMethod()
+    public function testRunHasCustomizableMethod()
+    {
+        $executed = Pipeline::make()
+            ->via('execute')
+            ->run(ActionExecute::class);
+
+        $this->assertTrue($executed);
+    }
+
+    public function testRunHasCustomizableMethodViaContainer()
     {
         $this->app->resolving(Pipeline::class, function ($pipeline) {
             return $pipeline->via('execute');
         });
 
-        $executed = run(ActionExecute::class);
+        $executed = Pipeline::make()->run(ActionExecute::class);
 
         $this->assertTrue($executed);
     }