Add IfElse and Exists strategies. Refactor Either strategy to extend IfElse. Deprecate IfExists strategy.

Author: Mark Challoner

README.md

@@ -29,9 +29,11 @@ Contents
     1. [Collection](#collection)
     1. [Context](#context)
     1. [Either](#either)
+    1. [Exists](#exists)
     1. [Filter](#filter)
     1. [Flatten](#flatten)
-    1. [IfExists](#ifexists)
+    1. [IfElse](#ifelse)
+    1. [IfExists](#ifexists) (deprecated)
     1. [Join](#join)
     1. [Merge](#merge)
     1. [TakeFirst](#takefirst)
@@ -291,10 +293,12 @@ The following strategies ship with Mapper and provide a suite of commonly used f
  - [Callback](#callback) – Augments data using the specified callback.
  - [Collection](#collection) – Maps a collection of data by applying a transformation to each datum.
  - [Context](#context) – Replaces the context for the specified expression.
+ - [Exists](#exists) – Returns true or false if the resolved value of the strategy or the path exists.
  - [Either](#either) – Either uses the primary strategy, if it returns non-null, otherwise delegates to a fallback expression.
  - [Filter](#filter) – Filters null values or values rejected by the specified callback.
  - [Flatten](#flatten) – Moves all nested values to the top level.
- - [IfExists](#ifexists) – Delegates to one expression or another depending on whether the specified condition maps to null.
+ - [IfElse](#ifelse) – Delegates to one expression or another depending on whether the specified condition loosely evaluates to true.
+ - [IfExists](#ifexists) (deprecated) – Delegates to one expression or another depending on whether the specified condition maps to null.
  - [Join](#join) – Joins sub-string expressions together with a glue string.
  - [Merge](#merge) – Merges two data sets together giving precedence to the latter if keys collide.
  - [TakeFirst](#takefirst) – Takes the first value from a collection one or more times.
@@ -511,6 +515,34 @@ Either(Strategy $strategy, Strategy|Mapping|array|mixed $expression)
 
 > 'bar'
 
+### Exists
+
+Returns true or false if the resolved value of the strategy or the path exists.
+
+#### Signature
+
+```php
+Exists(Strategy|array|mixed $strategyOrPath)
+```
+
+ 1. `$strategyOrPath` –  Strategy, array of path components or string of `->`-delimited components.
+
+#### Example
+
+```php
+$data = ['foo' => 'bar']
+
+(new Mapper)->map($data, new Exists('foo'));
+```
+
+> true
+
+```php
+(new Mapper)->map($data, new Exists('bar'));
+```
+
+> false
+
 ### Filter
 
 Filters null values or values rejected by the specified callback.
@@ -577,10 +609,42 @@ $data = [
 
 > [1, 2, 3, 3, 4, 5]
 
+### IfElse
+
+Delegates to one expression or another depending on whether the specified condition loosely evaluates to true.
+
+#### Signature
+
+```php
+IfElse(Strategy $condition, Strategy|Mapping|array|mixed $if, Strategy|Mapping|array|mixed $else = null)
+```
+
+ 1. `$condition` – Condition.
+ 2. `$if` – Expression used when condition loosely evaluates to true.
+ 3. `$else` – Expression used when condition loosely evaluates to false.
+
+#### Example
+
+```php
+$data = ['foo' => 'bar'];
+
+(new Mapper)->map($data, new IfElse(new Exists('foo'), true, false));
+```
+
+> true
+
+```php
+(new Mapper)->map($data, new IfElse(new Exists('bar'), true, false));
+```
+
+> false
+
 ### IfExists
 
 Delegates to one expression or another depending on whether the specified condition maps to null.
 
+Deprecated. Use IfElse and Exists strategies instead.
+
 #### Signature
 
 ```php

src/Strategy/Either.php

@@ -6,27 +6,14 @@
 /**
  * Either uses the primary strategy, if it returns non-null, otherwise delegates to a fallback expression.
  */
-class Either extends Decorator
+class Either extends IfElse
 {
-    private $expression;
-
     /**
      * @param Strategy $strategy
      * @param Strategy|Mapping|array|mixed $expression
      */
     public function __construct(Strategy $strategy, $expression)
     {
-        parent::__construct($strategy);
-
-        $this->expression = $expression;
-    }
-
-    public function __invoke($data, $context = null)
-    {
-        if (($result = parent::__invoke($data, $context)) !== null) {
-            return $result;
-        }
-
-        return $this->delegate($this->expression, $data, $context);
+        parent::__construct(new Exists($strategy), $strategy, $expression);
     }
 }

src/Strategy/Exists.php

@@ -0,0 +1,31 @@
+<?php
+namespace ScriptFUSION\Mapper\Strategy;
+
+/**
+ * Returns true or false if the resolved value of the strategy or the path exists.
+ */
+class Exists extends Delegate
+{
+    /**
+     * Initializes this instance with the specified strategy or path.
+     *
+     * @param Strategy|array|string $strategyOrPath Strategy, array of path components or string of `->`-delimited components.
+     */
+    public function __construct($strategyOrPath)
+    {
+        parent::__construct($strategyOrPath instanceof Strategy ? $strategyOrPath : new Copy($strategyOrPath));
+    }
+
+    /**
+     * Return true when the strategy resolves to a non-null value, otherwise false.
+     *
+     * @param mixed $data
+     * @param mixed $context
+     *
+     * @return mixed
+     */
+    public function __invoke($data, $context = null)
+    {
+        return parent::__invoke($data, $context) !== null;
+    }
+}

src/Strategy/IfElse.php

@@ -0,0 +1,55 @@
+<?php
+namespace ScriptFUSION\Mapper\Strategy;
+
+use ScriptFUSION\Mapper\Mapping;
+
+/**
+ * Delegates to one expression or another depending on whether the specified condition loosely evaluates to true.
+ */
+class IfElse extends Delegate
+{
+    /** @var Strategy|Mapping|array|mixed */
+    private $if;
+
+    /** @var Strategy|Mapping|array|mixed */
+    private $else;
+
+    /**
+     * Initializes this instance with the specified condition, the specified
+     * strategy or mapping to be resolved when condition is non-null and,
+     * optionally, the specified strategy or mapping to be resolved when
+     * condition is null.
+     *
+     * @param Strategy|Mapping|array|mixed $condition Condition.
+     * @param Strategy|Mapping|array|mixed $if Primary expression.
+     * @param Strategy|Mapping|array|mixed|null $else Optional. Fallback expression.
+     */
+    public function __construct($condition, $if, $else = null)
+    {
+        parent::__construct($condition);
+
+        $this->if = $if;
+        $this->else = $else;
+    }
+
+    /**
+     * Resolves the stored strategy or mapping when the stored condition
+     * resolves to a non-null value, otherwise returns the stored default
+     * value.
+     *
+     * @param mixed $data
+     * @param mixed $context
+     *
+     * @return mixed
+     */
+    public function __invoke($data, $context = null)
+    {
+        if (parent::__invoke($data, $context)) {
+            return $this->delegate($this->if, $data, $context);
+        }
+
+        if ($this->else !== null) {
+            return $this->delegate($this->else, $data, $context);
+        }
+    }
+}

src/Strategy/IfExists.php

@@ -5,6 +5,8 @@
 
 /**
  * Delegates to one expression or another depending on whether the specified condition maps to null.
+ *
+ * @deprecated Use IfElse and Exists strategies instead.
  */
 class IfExists extends Decorator
 {

test/Integration/Mapper/Strategy/ExistsTest.php

@@ -0,0 +1,48 @@
+<?php
+namespace ScriptFUSIONTest\Integration\Mapper\Strategy;
+
+use Mockery\Adapter\Phpunit\MockeryPHPUnitIntegration;
+use ScriptFUSION\Mapper\Mapper;
+use ScriptFUSION\Mapper\Strategy\Exists;
+use ScriptFUSION\Mapper\Strategy\IfElse;
+use ScriptFUSION\Mapper\Strategy\IfExists;
+use ScriptFUSION\Mapper\Strategy\Strategy;
+
+final class ExistsTest extends \PHPUnit_Framework_TestCase
+{
+    use MockeryPHPUnitIntegration;
+
+    public function testPathString()
+    {
+        $exists = (new Exists('0->1'))->setMapper(new Mapper);
+
+        self::assertFalse($exists([]));
+        self::assertFalse($exists(['a']));
+        self::assertFalse($exists([['a']]));
+        self::assertTrue($exists([['a','b']]));
+    }
+
+    public function testPathArray()
+    {
+        $exists = (new Exists(['0', '1']))->setMapper(new Mapper);
+
+        self::assertFalse($exists([]));
+        self::assertFalse($exists(['a']));
+        self::assertFalse($exists([['a']]));
+        self::assertTrue($exists([['a','b']]));
+    }
+
+    public function testPathStrategy()
+    {
+        $exists = (new Exists(
+            \Mockery::mock(Strategy::class)
+                ->shouldReceive('__invoke')
+                ->andReturn(true, false, null)
+                ->getMock()
+        ))->setMapper(new Mapper);
+
+        self::assertTrue($exists([]));
+        self::assertTrue($exists([]));
+        self::assertFalse($exists([]));
+    }
+}

test/Integration/Mapper/Strategy/IfElseTest.php

@@ -0,0 +1,65 @@
+<?php
+namespace ScriptFUSIONTest\Integration\Mapper\Strategy;
+
+use Mockery\Adapter\Phpunit\MockeryPHPUnitIntegration;
+use ScriptFUSION\Mapper\Mapper;
+use ScriptFUSION\Mapper\Strategy\Exists;
+use ScriptFUSION\Mapper\Strategy\IfElse;
+use ScriptFUSION\Mapper\Strategy\Strategy;
+
+final class IfElseTest extends \PHPUnit_Framework_TestCase
+{
+    use MockeryPHPUnitIntegration;
+
+    public function testIfElse()
+    {
+        $ifExists = (
+            new IfElse(
+                \Mockery::mock(Strategy::class)
+                    ->shouldReceive('__invoke')
+                    ->andReturn(true, false, null)
+                    ->getMock(),
+                'foo',
+                'bar'
+            )
+        )->setMapper(new Mapper);
+
+        self::assertSame('foo', $ifExists([]));
+        self::assertSame('bar', $ifExists([]));
+        self::assertSame('bar', $ifExists([]));
+    }
+
+    public function testIfExistsElse()
+    {
+        $ifExists = (
+        new IfElse(
+            new Exists('0->1'),
+            'foo',
+            'bar'
+        )
+        )->setMapper(new Mapper);
+
+        self::assertSame('foo', $ifExists([['a', 'b']]));
+        self::assertSame('bar', $ifExists([['a']]));
+        self::assertSame('bar', $ifExists(['a']));
+        self::assertSame('bar', $ifExists([]));
+    }
+
+    public function testOnlyIf()
+    {
+        $ifElse = (
+            new IfElse(
+                \Mockery::mock(Strategy::class)
+                    ->shouldReceive('__invoke')
+                    ->andReturn(true, false, null)
+                    ->getMock(),
+                'foo'
+            )
+        )->setMapper(new Mapper);
+
+        self::assertSame('foo', $ifElse([]));
+        self::assertNull($ifElse([]));
+        self::assertNull($ifElse([]));
+    }
+
+}