Add converters to convert values to NULL

composer.json

@@ -18,12 +18,12 @@
         "ergebnis/phpstan-rules": "^2.2.0",
         "thecodingmachine/phpstan-safe-rule": "^1.2.0",
         "thecodingmachine/phpstan-strict-rules": "^1.0.0",
-        "phpstan/phpstan-phpunit": "^1.3.16",
-        "squizlabs/php_codesniffer": "^3.9.0",
-        "phpstan/phpstan": "^1.10.59",
-        "phpstan/phpstan-strict-rules": "^1.5.2",
-        "phpunit/phpunit": "^11.0.3",
-        "rector/rector": "^1.0.1"
+        "phpstan/phpstan-phpunit": "^1.4.0",
+        "squizlabs/php_codesniffer": "^3.10.3",
+        "phpstan/phpstan": "^1.12.7",
+        "phpstan/phpstan-strict-rules": "^1.6.1",
+        "phpunit/phpunit": "^11.4.3",
+        "rector/rector": "^1.2.9"
     },
     "autoload": {
         "psr-4": {

rector.php

@@ -5,8 +5,8 @@
 use Rector\Config\RectorConfig;
 use Rector\Naming\Rector\Class_\RenamePropertyToMatchTypeRector;
 use Rector\Php74\Rector\LNumber\AddLiteralSeparatorToNumberRector;
+use Rector\PHPUnit\CodeQuality\Rector\Class_\PreferPHPUnitSelfCallRector;
 use Rector\PHPUnit\CodeQuality\Rector\Class_\PreferPHPUnitThisCallRector;
-use Rector\PHPUnit\Rector\Class_\PreferPHPUnitSelfCallRector;
 use Rector\PHPUnit\Set\PHPUnitSetList;
 use Rector\Set\ValueObject\LevelSetList;
 use Rector\Set\ValueObject\SetList;

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