new constructor: optional()

Author: mle86

CHANGELOG.md

@@ -1,5 +1,6 @@
 v2.1.0 (2019-11)
 
+ * New `optional()` constructor for nullable values
  * Better `wrap...` function names
 
 v2.0.0 (2019-10-23)

README.md

@@ -41,6 +41,10 @@ $odd1 = new OddNumber(61);       // works as expected, $odd1->value() will retur
 $odd2 = new OddNumber(40);       // throws an InvalidArgumentException
 $odd3 = new OddNumber("string"); // throws an InvalidArgumentException
 $odd4 = new OddNumber(null);     // throws an InvalidArgumentException
+
+$odd5   = OddNumber::optional(33);   // works as expected, $odd5->value() will return 33
+$nonodd = OddNumber::optional(null); // $nonodd is now null
+$odd6   = OddNumber::optional(40);   // throws an InvalidArgumentException
 ```
 
 
@@ -95,6 +99,11 @@ of external values without wrapping them in an instance.
   Valid values are stored in the new instance, invalid values cause an `InvalidArgumentException` to be thrown.
   Other instances of the same class are always considered valid (*re-wrapping*).
 
+* <code>public static function <b>optional</b>($raw\_value): ?static</code>
+
+  Same as the default constructor,
+  but also accepts `null` values (which will be returned unchanged).
+
 * <code>abstract public static function <b>isValid</b>($test\_value): bool</code>
 
   Checks the validity of a raw value.

src/AbstractValue.php

@@ -113,6 +113,22 @@ public function __construct($rawValue)
         }
     }
 
+    /**
+     * Same as the default constructor,
+     * but also accepts `null` values (which will be returned unchanged).
+     *
+     * @param $rawValue
+     * @return static|null
+     */
+    public static function optional($rawValue)
+    {
+        if ($rawValue === null) {
+            return null;
+        }
+
+        return new static($rawValue);
+    }
+
 
     /**
      * Equality test.

test/10-ValueTest.php

@@ -477,4 +477,26 @@ public function testExtendedBuiltinEqualsZero($additional_property, ExtTestWrapp
             "Extended wrapper object is considered equal to zero by builtin== !");
     }
 
+    /**
+     * @depends testConstructor
+     * @depends testConstructorWithInstance
+     * @depends testInvalidInitializer
+     * @depends testValue
+     * @depends testRewrap
+     */
+    public function testOptionalConstructor()
+    {
+        $tw1 = TestWrapper4::optional('43001');
+        $this->assertSame('43001', $tw1->value());
+
+        $tw2 = TestWrapper4::optional($tw1);
+        $this->assertSame($tw1->value(), $tw2->value());
+
+        $tw3 = TestWrapper4::optional(null);
+        $this->assertNull($tw3);
+
+        $this->expectException(\InvalidArgumentException::class);
+        TestWrapper4::optional('x1x1x1x1x');
+    }
+
 }