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([]));
+ }
+
+}