refactor: Use only one class for providing helper methods

BREAKING CHANGE: Merge Convert and Assert to one TypeGuard class

Author: pl-github

README.md

@@ -4,11 +4,22 @@
 
 A PHP library to ensure correctness of types providing a readable interface.
 
-The library is helpfull to
+## Installation
+
+```shell
+$ composer require plook/type-guard
+```
 
 ## Example
 
 ```php
+use function Plook\TypeGuard\asBool;
+use function Plook\TypeGuard\asDateTimeImmutable;
+use function Plook\TypeGuard\asFloat;
+use function Plook\TypeGuard\asInt;
+use function Plook\TypeGuard\asString;
+use function Plook\TypeGuard\notNull;
+
 $row = $this->fetchProjectRow(123);
 
 $project = new Project(
@@ -23,7 +34,7 @@ $project = new Project(
 
 ## Provided helper functions
 
-### Type Conversion
+### Ensure Types
 * `asBool($value)` Converts input value to a boolean, but passes `null`.
 * `asFloat($value)` Converts input value to a float, but passes `null`.
 * `asInt($value)` Converts input value to a int, but passes `null`.
@@ -34,21 +45,19 @@ $project = new Project(
 ### Assertions
 * `notNull($value)` Throws an exception if the value is `null` otherwise it passes the original value.
 
-## Installation
-
-```shell
-$ composer require plook/type-guard
-```
-
 ## Configuration
 
 ### Setting the default target time zone of `DateTimeImmutable` objects
 ```php
-Convert::instance()->timeZone('Australia/Adelaide');
-Convert::instance()->timeZone(new DateTimeZone('Australia/Adelaide'));
+use Plook\TypeGuard\TypeGuard;
+
+TypeGuard::instance()->timeZone('Australia/Adelaide');
+TypeGuard::instance()->timeZone(new DateTimeZone('Australia/Adelaide'));
 ```
 
 ### Setting the default format of date time strings
 ```php
-Convert::instance()->dateTimeFormat(DateTimeInterface::ATOM);
+use Plook\TypeGuard\TypeGuard;
+
+TypeGuard::instance()->dateTimeFormat(DateTimeInterface::ATOM);
 ```

composer.json

@@ -28,8 +28,7 @@
             "Plook\\TypeGuard\\": "src/"
         },
         "files": [
-            "src/Assert/functions.php",
-            "src/Convert/functions.php"
+            "src/functions.php"
         ]
     },
     "autoload-dev": {

src/Assert/Assert.php

@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace Plook\TypeGuard\Assert;
+namespace Plook\TypeGuard;
 
 use InvalidArgumentException;
 

src/Assert/functions.php

@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace Plook\TypeGuard\Convert;
+namespace Plook\TypeGuard;
 
 use InvalidArgumentException;
 

src/Assert/InvalidValue.php src/InvalidValue.phpsrc/Assert/InvalidValue.php renamed to src/InvalidValue.php

@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace Plook\TypeGuard\Convert;
+namespace Plook\TypeGuard;
 
 use DateTimeImmutable;
 use DateTimeZone;
@@ -15,7 +15,7 @@
 use function is_scalar;
 use function is_string;
 
-final class Convert
+final class TypeGuard
 {
     private DateTimeZone|null $dateTimeZone = null;
 
@@ -116,7 +116,7 @@ public function asString(mixed $value): string|null
         return (string) $value;
     }
 
-    /** @return ($value is null ? null : DateTimeImmutable) */
+    /** @return DateTimeImmutable */
     public function asDateTimeImmutable(mixed $value): DateTimeImmutable|null
     {
         if ($value === null) {
@@ -175,4 +175,20 @@ public function dateTimeFormat(string|null $dateTimeFormat = null): string
 
         return $this->dateTimeFormat;
     }
+
+    /**
+     * @param ?T $value
+     *
+     * @return T
+     *
+     * @template T
+     */
+    public function notNull(mixed $value): mixed
+    {
+        if ($value === null) {
+            throw InvalidValue::null();
+        }
+
+        return $value;
+    }
 }

src/Convert/NotConvertable.php src/NotConvertable.phpsrc/Convert/NotConvertable.php renamed to src/NotConvertable.php

@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace Plook\TypeGuard\Convert;
+namespace Plook\TypeGuard;
 
 use DateTimeImmutable;
 
@@ -15,7 +15,7 @@
     /** @return ($value is null ? null : bool) */
     function asBool(mixed $value): bool|null
     {
-        return Convert::instance()->asBool($value);
+        return TypeGuard::instance()->asBool($value);
     }
 }
 
@@ -24,7 +24,7 @@ function asBool(mixed $value): bool|null
     /** @return ($value is null ? null : float) */
     function asFloat(mixed $value): float|null
     {
-        return Convert::instance()->asFloat($value);
+        return TypeGuard::instance()->asFloat($value);
     }
 }
 
@@ -33,7 +33,7 @@ function asFloat(mixed $value): float|null
     /** @return ($value is null ? null : int) */
     function asInt(mixed $value): int|null
     {
-        return Convert::instance()->asInt($value);
+        return TypeGuard::instance()->asInt($value);
     }
 }
 
@@ -42,7 +42,7 @@ function asInt(mixed $value): int|null
     /** @return ($value is null ? null : string) */
     function asString(mixed $value): string|null
     {
-        return Convert::instance()->asString($value);
+        return TypeGuard::instance()->asString($value);
     }
 }
 
@@ -51,7 +51,7 @@ function asString(mixed $value): string|null
     /** @return ($value is null ? null : DateTimeImmutable) */
     function asDateTimeImmutable(mixed $value): DateTimeImmutable|null
     {
-        return Convert::instance()->asDateTimeImmutable($value);
+        return TypeGuard::instance()->asDateTimeImmutable($value);
     }
 }
 
@@ -60,6 +60,21 @@ function asDateTimeImmutable(mixed $value): DateTimeImmutable|null
     /** @return ($value is null ? null : string) */
     function asDateTimeString(mixed $value): string|null
     {
-        return Convert::instance()->asDateTimeString($value);
+        return TypeGuard::instance()->asDateTimeString($value);
+    }
+}
+
+if (!function_exists('\Plook\TypeGuard\notNull')) { // @codeCoverageIgnore
+
+    /**
+     * @param ?T $value
+     *
+     * @return T
+     *
+     * @template T
+     */
+    function notNull(mixed $value): mixed
+    {
+        return TypeGuard::instance()->notNull($value);
     }
 }

src/Convert/Convert.php src/TypeGuard.phpsrc/Convert/Convert.php renamed to src/TypeGuard.php

@@ -2,23 +2,23 @@
 
 declare(strict_types=1);
 
-namespace Plook\Tests\TypeGuard\Convert;
+namespace Plook\Tests\TypeGuard;
 
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\CoversFunction;
 use PHPUnit\Framework\TestCase;
-use Plook\Tests\TypeGuard\StringableInt;
-use Plook\Tests\TypeGuard\StringableString;
-use Plook\TypeGuard\Convert\Convert;
-use Plook\TypeGuard\Convert\NotConvertable;
+use Plook\Tests\TypeGuard\Helper\StringableInt;
+use Plook\Tests\TypeGuard\Helper\StringableString;
+use Plook\TypeGuard\NotConvertable;
+use Plook\TypeGuard\TypeGuard;
 
 use function basename;
-use function Plook\TypeGuard\Convert\asBool;
+use function Plook\TypeGuard\asBool;
 use function sprintf;
 
-#[CoversClass(Convert::class)]
+#[CoversClass(TypeGuard::class)]
 #[CoversClass(NotConvertable::class)]
-#[CoversFunction('\Plook\TypeGuard\Convert\asBool')]
+#[CoversFunction('\Plook\TypeGuard\asBool')]
 final class AsBoolTest extends TestCase
 {
     public function testDoesNotTouchBools(): void

src/Convert/functions.php src/functions.phpsrc/Convert/functions.php renamed to src/functions.php

@@ -2,37 +2,37 @@
 
 declare(strict_types=1);
 
-namespace Plook\Tests\TypeGuard\Convert;
+namespace Plook\Tests\TypeGuard;
 
 use DateTimeImmutable;
 use DateTimeZone;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\CoversFunction;
 use PHPUnit\Framework\TestCase;
-use Plook\Tests\TypeGuard\StringableString;
-use Plook\TypeGuard\Convert\Convert;
-use Plook\TypeGuard\Convert\NotConvertable;
+use Plook\Tests\TypeGuard\Helper\StringableString;
+use Plook\TypeGuard\NotConvertable;
+use Plook\TypeGuard\TypeGuard;
 
 use function basename;
-use function Plook\TypeGuard\Convert\asDateTimeImmutable;
+use function Plook\TypeGuard\asDateTimeImmutable;
 use function sprintf;
 
-#[CoversClass(Convert::class)]
+#[CoversClass(TypeGuard::class)]
 #[CoversClass(NotConvertable::class)]
-#[CoversFunction('\Plook\TypeGuard\Convert\asDateTimeImmutable')]
-#[CoversFunction('\Plook\TypeGuard\Convert\asString')]
+#[CoversFunction('\Plook\TypeGuard\asDateTimeImmutable')]
+#[CoversFunction('\Plook\TypeGuard\asString')]
 final class AsDateTimeImmutableTest extends TestCase
 {
     private readonly DateTimeZone $originalTimeZone;
 
     protected function setUp(): void
     {
-        $this->originalTimeZone = Convert::instance()->timeZone();
+        $this->originalTimeZone = TypeGuard::instance()->timeZone();
     }
 
     protected function tearDown(): void
     {
-        Convert::instance()->timeZone($this->originalTimeZone);
+        TypeGuard::instance()->timeZone($this->originalTimeZone);
     }
 
     public function testConvertsStrings(): void
@@ -53,7 +53,7 @@ public function testConvertsStringables(): void
 
     public function testConvertsDateTimeImmutableWithSameTimeZone(): void
     {
-        $result = asDateTimeImmutable(new DateTimeImmutable('2010-09-08T07:06:05', Convert::instance()->timeZone()));
+        $result = asDateTimeImmutable(new DateTimeImmutable('2010-09-08T07:06:05', TypeGuard::instance()->timeZone()));
 
         self::assertInstanceOf(DateTimeImmutable::class, $result);
         self::assertSame('2010-09-08T07:06:05+00:00', $result->format('c'));
@@ -71,7 +71,7 @@ public function testConvertsDateTimeImmutableWithDifferentTimeZone(): void
 
     public function testConvertsDateTimeImmutableDefaultTimeZoneCanBeChangedByDateTimeZone(): void
     {
-        Convert::instance()->timeZone(new DateTimeZone('Australia/Adelaide'));
+        TypeGuard::instance()->timeZone(new DateTimeZone('Australia/Adelaide'));
 
         $result = asDateTimeImmutable(new DateTimeImmutable('2010-09-08T07:06:05+00:00'));
 
@@ -81,7 +81,7 @@ public function testConvertsDateTimeImmutableDefaultTimeZoneCanBeChangedByDateTi
 
     public function testConvertsDateTimeImmutableDefaultTimeZoneCanBeChangedByTimeZoneName(): void
     {
-        Convert::instance()->timeZone('Australia/Adelaide');
+        TypeGuard::instance()->timeZone('Australia/Adelaide');
 
         $result = asDateTimeImmutable(new DateTimeImmutable('2010-09-08T07:06:05+00:00'));