Allow initial value casting

Author: gmazzap

README.md

@@ -112,7 +112,7 @@ echo $pipeline->applyTo('foo '); // 'foo I am the context I am the context'
 
 ## DTO "freshness"
 
-Everytime `Pipeline::applyTo()` is called on same Pipeline instance, DTO instance passed to callbacks
+Every time `Pipeline::applyTo()` is called on same Pipeline instance, DTO instance passed to callbacks
 is a *fresh* one, i.e. DTO state is not maintained across `applyTo()` calls.
 
 Only `DTO::context()` returns the same value because it is set at Pipeline level.
@@ -169,7 +169,21 @@ $pipeline = (new Pipeline(null, Pipeline::TO_ARRAY))
 return $pipeline->applyTo('foo'); // ['foo', 'bar']
 ```
 
-Note that value received by 1st callback is not returned by any callback, so it is not type casted.
+Note that, by default, initial value *passed to* 1st callback, is **not** type casted (but its *returning value* is).
+
+However, it's also possible to type cast even the initial value before it is passed to first callback.
+That can be done by passing `true` as 3rd argument to Pipeline constructor.
+
+```php
+use Toobo\PipePie\Pipeline;
+
+$pipeline = (new Pipeline(null, Pipeline::TO_ARRAY, true))
+    ->pipe(function (array $carry) {  // Even 1st callback receives type-casted value
+        return $carry;
+    });
+
+return $pipeline->applyTo('foo'); // ['foo']
+```
 
 
 ### Type Casting via Custom Callback
@@ -321,8 +335,8 @@ return $pipeline->info();
 
 Note that:
 
- - informations on various `applyTo()` calls, are shown in inverse chronological order: later calls are shown first;
- - an `info()` call *flushes* informations, so on subsequent calls the method returns only data for `applyTo()` calls
+ - information on various `applyTo()` calls, are shown in inverse chronological order: later calls are shown first;
+ - an `info()` call *flushes* information, so on subsequent calls the method returns only data for `applyTo()` calls
  happened since last `info()` call.
 
 ## Requirements

src/Pipeline.php

@@ -42,6 +42,11 @@ class Pipeline
      */
     private $caster;
 
+    /**
+     * @var bool
+     */
+    private $castFirst;
+
     /**
      * @var bool
      */
@@ -58,18 +63,20 @@ class Pipeline
     private $DTOs;
 
     /**
-     * @param mixed             $context Something that can be accessed with $dto->context()
-     *                                   acting as context for all the callbacks
-     * @param int|callable|null $caster  Values returned by any of pipeline callbacks can be
-     *                                   casted using a class constants or a custom callback
+     * @param mixed             $context   Something that can be accessed with $dto->context()
+     *                                     acting as context for all the callbacks
+     * @param int|callable|null $caster    Values returned by any of pipeline callbacks can be
+     *                                     casted using a class constants or a custom callback
+     * @param bool              $castFirst Should initial value should be casted?
      */
-    public function __construct($context = null, $caster = null)
+    public function __construct($context = null, $caster = null, $castFirst = false)
     {
         $this->pipeline = new SplObjectStorage();
         if (is_int($caster) && array_key_exists($caster, self::$casters_map)) {
             $caster = [$this, self::$casters_map[$caster]];
         }
         $this->caster = is_callable($caster) ? $caster : null;
+        $this->castFirst = $this->toBool($castFirst);
         $this->context = $context;
         $this->DTOs = new SplStack();
         $this->locked = false;
@@ -121,7 +128,7 @@ public function applyTo($initial, DTO $dto = null, $cursor = null)
             return $initial;
         }
         $this->DTOs->push($this->init($dto, $initial));
-        $carry = is_null($cursor) ? $initial : $this->maybeCast($cursor);
+        $carry = $this->initialValue($initial, $cursor);
         while ($this->pipeline->valid()) {
             $carry = $this->run($initial, $carry);
             $this->pipeline->next();
@@ -198,6 +205,22 @@ private function init(DTO $dto = null, $initial = null)
         return $dto;
     }
 
+    /**
+     * Setup initial value for Pipeline based on caster settings.
+     *
+     * @param  mixed $initial
+     * @param  mixed $cursor
+     * @return mixed
+     */
+    private function initialValue($initial, $cursor)
+    {
+        if (! is_null($cursor)) {
+            return $this->maybeCast($cursor);
+        }
+
+        return $this->castFirst ? $this->maybeCast($initial) : $initial;
+    }
+
     /**
      * Run current callback in the pipeline.
      *
@@ -223,6 +246,12 @@ private function run($initial, $carry)
      *
      * @param  mixed $data
      * @return mixed
+     * @uses \Toobo\PipePie\Pipeline::toArray()
+     * @uses \Toobo\PipePie\Pipeline::toObject()
+     * @uses \Toobo\PipePie\Pipeline::toString()
+     * @uses \Toobo\PipePie\Pipeline::toInt()
+     * @uses \Toobo\PipePie\Pipeline::toBool()
+     * @uses \Toobo\PipePie\Pipeline::toFloat()
      */
     private function maybeCast($data)
     {

tests/PHPUnit/PipelineTest.php

@@ -7,7 +7,7 @@
 class PipelineTest extends PHPUnit_Framework_TestCase
 {
     /**
-     * @expectedException LogicException
+     * @expectedException \LogicException
      */
     public function testPipeFailsIfWorking()
     {
@@ -22,7 +22,7 @@ public function testPipeFailsIfWorking()
     }
 
     /**
-     * @expectedException LogicException
+     * @expectedException \LogicException
      */
     public function testPipeFailsIfLocked()
     {
@@ -44,7 +44,7 @@ public function testApplyDoNothingIfNoCallbacks()
     }
 
     /**
-     * @expectedException LogicException
+     * @expectedException \LogicException
      */
     public function testApplyFailsIfWorking()
     {
@@ -161,6 +161,15 @@ public function testApplyCustomCaster()
         assertSame([0, 1, 2, 3, 4], $pipeline->applyTo(['foo' => 0, 'bar' => 'baz']));
     }
 
+    public function testApplyCasterFirstItem()
+    {
+        $pipeline = new Pipeline(null, Pipeline::TO_OBJECT, true);
+        $pipeline->pipe(function (\stdClass $carry) {
+            return $carry;
+        });
+        assertEquals((object) ['baz' => 'baz'], $pipeline->applyTo(['baz' => 'baz']));
+    }
+
     public function testApplyMoreArgs()
     {
         $pipeline = new Pipeline();
@@ -186,7 +195,7 @@ public function testApplyCustomDTO()
     }
 
     /**
-     * @expectedException LogicException
+     * @expectedException \LogicException
      */
     public function testApplyCustomDTOFailsIfWrongInput()
     {
@@ -249,7 +258,7 @@ public function testDTOisSharedInNestedPipelines()
     }
 
     /**
-     * @expectedException LogicException
+     * @expectedException \LogicException
      */
     public function testInfoFailsIfWorking()
     {
@@ -264,7 +273,7 @@ public function testInfoFailsIfWorking()
     public function testInfo()
     {
         $pipeline = new Pipeline('I am the context');
-        $pipeline->pipe(function ($carry, $initial, $dto) {
+        $pipeline->pipe(function ($carry, $initial, DTO $dto) {
             $dto['called'] = 1;
 
             return $carry.$initial.$dto->context();