feat: Add to NULL converters

Author: pl-github

src/TypeGuard.php

@@ -154,6 +154,70 @@ public function asDateTimeString(mixed $value): string|null
         return $value->format($this->dateTimeFormat());
     }
 
+    /**
+     * @param T $value
+     *
+     * @return T|null
+     *
+     * @template T
+     */
+    public function blankAsNull(mixed $value): mixed
+    {
+        if ($value === '') {
+            return null;
+        }
+
+        return $value;
+    }
+
+    /**
+     * @param T $value
+     *
+     * @return T|null
+     *
+     * @template T
+     */
+    public function falseAsNull(mixed $value): mixed
+    {
+        if ($value === false) {
+            return null;
+        }
+
+        return $value;
+    }
+
+    /**
+     * @param T $value
+     *
+     * @return T|null
+     *
+     * @template T
+     */
+    public function zeroAsNull(mixed $value): mixed
+    {
+        if ($value === 0 || $value === 0.0) {
+            return null;
+        }
+
+        return $value;
+    }
+
+    /**
+     * @param T $value
+     *
+     * @return T|null
+     *
+     * @template T
+     */
+    public function falsyAsNull(mixed $value): mixed
+    {
+        if (! (bool) $value) {
+            return null;
+        }
+
+        return $value;
+    }
+
     public function timeZone(DateTimeZone|string|null $timeZone = null): DateTimeZone
     {
         if (is_string($timeZone)) {

src/functions.php

@@ -64,6 +64,66 @@ function asDateTimeString(mixed $value): string|null
     }
 }
 
+if (!function_exists('\Plook\TypeGuard\blankAsNull')) { // @codeCoverageIgnore
+
+    /**
+     * @param T $value
+     *
+     * @return T|null
+     *
+     * @template T
+     */
+    function blankAsNull(mixed $value): mixed
+    {
+        return TypeGuard::instance()->blankAsNull($value);
+    }
+}
+
+if (!function_exists('\Plook\TypeGuard\falseAsNull')) { // @codeCoverageIgnore
+
+    /**
+     * @param T $value
+     *
+     * @return T|null
+     *
+     * @template T
+     */
+    function falseAsNull(mixed $value): mixed
+    {
+        return TypeGuard::instance()->falseAsNull($value);
+    }
+}
+
+if (!function_exists('\Plook\TypeGuard\zeroAsNull')) { // @codeCoverageIgnore
+
+    /**
+     * @param T $value
+     *
+     * @return T|null
+     *
+     * @template T
+     */
+    function zeroAsNull(mixed $value): mixed
+    {
+        return TypeGuard::instance()->zeroAsNull($value);
+    }
+}
+
+if (!function_exists('\Plook\TypeGuard\falsyAsNull')) { // @codeCoverageIgnore
+
+    /**
+     * @param T $value
+     *
+     * @return T|null
+     *
+     * @template T
+     */
+    function falsyAsNull(mixed $value): mixed
+    {
+        return TypeGuard::instance()->falsyAsNull($value);
+    }
+}
+
 if (!function_exists('\Plook\TypeGuard\notNull')) { // @codeCoverageIgnore
 
     /**

tests/BlankAsNullTest.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Plook\Tests\TypeGuard;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\CoversFunction;
+use PHPUnit\Framework\TestCase;
+use Plook\TypeGuard\NotConvertable;
+use Plook\TypeGuard\TypeGuard;
+use stdClass;
+
+use function Plook\TypeGuard\blankAsNull;
+
+#[CoversClass(TypeGuard::class)]
+#[CoversClass(NotConvertable::class)]
+#[CoversFunction('\Plook\TypeGuard\blankAsNull')]
+final class BlankAsNullTest extends TestCase
+{
+    public function testConvertsBlankToNull(): void
+    {
+        self::assertNull(blankAsNull(''));
+    }
+
+    public function testDoesNotTouchStrings(): void
+    {
+        self::assertSame('String', blankAsNull('String'));
+    }
+
+    public function testDoesNotTouchInts(): void
+    {
+        self::assertSame(1000, blankAsNull(1000));
+    }
+
+    public function testDoesNotTouchZero(): void
+    {
+        self::assertSame(0, blankAsNull(0));
+    }
+
+    public function testDoesTouchTrue(): void
+    {
+        self::assertTrue(blankAsNull(true));
+    }
+
+    public function testDoesTouchFalse(): void
+    {
+        self::assertFalse(blankAsNull(false));
+    }
+
+    public function testDoesNotTouchObjects(): void
+    {
+        $object = new stdClass();
+
+        self::assertSame($object, blankAsNull($object));
+    }
+}

tests/FalseAsNullTest.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Plook\Tests\TypeGuard;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\CoversFunction;
+use PHPUnit\Framework\TestCase;
+use Plook\TypeGuard\NotConvertable;
+use Plook\TypeGuard\TypeGuard;
+use stdClass;
+
+use function Plook\TypeGuard\falseAsNull;
+
+#[CoversClass(TypeGuard::class)]
+#[CoversClass(NotConvertable::class)]
+#[CoversFunction('\Plook\TypeGuard\falseAsNull')]
+final class FalseAsNullTest extends TestCase
+{
+    public function testConvertsFalseToNull(): void
+    {
+        self::assertNull(falseAsNull(false));
+    }
+
+    public function testDoesTouchTrue(): void
+    {
+        self::assertTrue(falseAsNull(true));
+    }
+
+    public function testDoesNotTouchStrings(): void
+    {
+        self::assertSame('String', falseAsNull('String'));
+    }
+
+    public function testDoesNotTouchBlanks(): void
+    {
+        self::assertSame('', falseAsNull(''));
+    }
+
+    public function testDoesNotTouchInts(): void
+    {
+        self::assertSame(1000, falseAsNull(1000));
+    }
+
+    public function testDoesNotTouchZero(): void
+    {
+        self::assertSame(0, falseAsNull(0));
+    }
+
+    public function testDoesNotTouchObjects(): void
+    {
+        $object = new stdClass();
+
+        self::assertSame($object, falseAsNull($object));
+    }
+}

tests/FalsyAsNullTest.php

@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Plook\Tests\TypeGuard;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\CoversFunction;
+use PHPUnit\Framework\TestCase;
+use Plook\TypeGuard\NotConvertable;
+use Plook\TypeGuard\TypeGuard;
+use stdClass;
+
+use function Plook\TypeGuard\falsyAsNull;
+
+#[CoversClass(TypeGuard::class)]
+#[CoversClass(NotConvertable::class)]
+#[CoversFunction('\Plook\TypeGuard\falsyAsNull')]
+final class FalsyAsNullTest extends TestCase
+{
+    public function testConvertsBlankToNull(): void
+    {
+        self::assertNull(falsyAsNull(''));
+    }
+
+    public function testDoesNotTouchStrings(): void
+    {
+        self::assertSame('String', falsyAsNull('String'));
+    }
+
+    public function testConvertsZeroIntToNUll(): void
+    {
+        self::assertNull(falsyAsNull(0));
+    }
+
+    public function testConvertsZeroFloatToNull(): void
+    {
+        self::assertNull(falsyAsNull(0.0));
+    }
+
+    public function testDoesNotTouchInts(): void
+    {
+        self::assertSame(1000, falsyAsNull(1000));
+    }
+
+    public function testDoesNotTouchFloats(): void
+    {
+        self::assertSame(1234.56, falsyAsNull(1234.56));
+    }
+
+    public function testConvertsFalseToNull(): void
+    {
+        self::assertNull(falsyAsNull(false));
+    }
+
+    public function testDoesTouchTrue(): void
+    {
+        self::assertTrue(falsyAsNull(true));
+    }
+
+    public function testDoesNotTouchObjects(): void
+    {
+        $object = new stdClass();
+
+        self::assertSame($object, falsyAsNull($object));
+    }
+}

tests/ZeroAsNullTest.php

@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Plook\Tests\TypeGuard;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\CoversFunction;
+use PHPUnit\Framework\TestCase;
+use Plook\TypeGuard\NotConvertable;
+use Plook\TypeGuard\TypeGuard;
+use stdClass;
+
+use function Plook\TypeGuard\zeroAsNull;
+
+#[CoversClass(TypeGuard::class)]
+#[CoversClass(NotConvertable::class)]
+#[CoversFunction('\Plook\TypeGuard\zeroAsNull')]
+final class ZeroAsNullTest extends TestCase
+{
+    public function testConvertsZeroIntToNull(): void
+    {
+        self::assertNull(zeroAsNull(0));
+    }
+
+    public function testConvertsZeroFloatToNull(): void
+    {
+        self::assertNull(zeroAsNull(0.0));
+    }
+
+    public function testDoesNotTouchInts(): void
+    {
+        self::assertSame(1000, zeroAsNull(1000));
+    }
+
+    public function testDoesNotTouchFloats(): void
+    {
+        self::assertSame(1234.567, zeroAsNull(1234.567));
+    }
+
+    public function testDoesNotTouchStrings(): void
+    {
+        self::assertSame('String', zeroAsNull('String'));
+    }
+
+    public function testDoesNotTouchBlanks(): void
+    {
+        self::assertSame('', zeroAsNull(''));
+    }
+
+    public function testDoesTouchTrue(): void
+    {
+        self::assertTrue(zeroAsNull(true));
+    }
+
+    public function testDoesTouchFalse(): void
+    {
+        self::assertFalse(zeroAsNull(false));
+    }
+
+    public function testDoesNotTouchObjects(): void
+    {
+        $object = new stdClass();
+
+        self::assertSame($object, zeroAsNull($object));
+    }
+}