Add UndefinedType support and restructure namespaces with alias classes and tests

- Introduced `UndefinedType` abstract structure and `UndefinedStandard` implementation with an interface and exceptions for "Undefined" states.
- Added alias classes (`NotFound`, `NotSet`, `NotExist`, `Undefined`, `Unknown`) for flexible "Undefined" state representation.
- Relocated `IntTiny` and `StringVarChar255` to `MariaDb` namespace for clarity and database-specific relevance.
- Enhanced `BoolStandard` to accept "1" and "0" strings for boolean parsing, with updated exception messages.
- Removed outdated `INSTALL.md`, simplifying documentation and enhancing examples across `README.md` and `USAGE.md`.
- Added comprehensive tests for `Undefined` state aliases and updated `psalmTest.php` with usage examples.

Author: georgedeploy

README.md

@@ -2,14 +2,14 @@
 
 A PHP 8.2 library of typed value objects for common PHP data types.
 
+Building blocks for a DTO's, ValueObjects, Entities, etc.
+
 [![Latest Version on Packagist](https://img.shields.io/packagist/v/georgii-web/php-typed-values.svg?style=flat-square)](https://packagist.org/packages/georgii-web/php-typed-values)
 [![Tests](https://github.com/georgii-web/php-typed-values/actions/workflows/php.yml/badge.svg)](https://github.com/georgii-web/php-typed-values/actions/workflows/php.yml)
 [![Total Downloads](https://img.shields.io/packagist/dt/georgii-web/php-typed-values.svg?style=flat-square)](https://packagist.org/packages/georgii-web/php-typed-values)
 
 ## Install
 
-Using Composer:
-
 ```
 composer require georgii-web/php-typed-values
 ```
@@ -37,7 +37,7 @@ if ($id <= 0) {
 ```php
 readonly class Id extends PositiveInt {}
 
-Id::fromString('123');
+Id::fromInt(123);
 ```
 
 #### 3. Create a composite value object from other typed values (nullable values example):
@@ -48,27 +48,33 @@ final class Profile
     public function __construct(
         public readonly PositiveInt $id,
         public readonly NonEmptyStr $firstName,
-        public readonly ?NonEmptyStr $lastName,
+        public readonly ?FloatNonNegative $height,
     ) {}
 
     public static function fromScalars(
         int $id,
         string $firstName,
-        ?string $lastName,
+        string|float|int|null $height,
     ): self {
         return new self(
             PositiveInt::fromInt($id),
             NonEmptyStr::fromString($firstName),
-            $lastName !== null ? NonEmptyStr::fromString($lastName) : null,
+            $height !== null ? FloatNonNegative::fromString((string) $height) : null,
         );
     }
+    
+    public function getHeight(): FloatNonNegative|Undefined { // avoid using NULL, which could mean anything
+        return $this->height ?? Undefined::create();
+    }
 }
 
 // Usage
-Profile::fromScalars(id: 101, firstName: 'Alice', lastName: 'Smith');
-Profile::fromScalars(id: 157, firstName: 'Tom', lastName: null);
+Profile::fromScalars(id: 101, firstName: 'Alice', height: '172.5');
+Profile::fromScalars(id: 157, firstName: 'Tom', height: null);
 // From array
 $profile = Profile::fromScalars(...[157, 'Tom', null]);
+// Accessing values
+$profile->getHeight(); // "172.5 \ Undefined" type class
 ```
 
 
@@ -83,7 +89,6 @@ $profile = Profile::fromScalars(...[157, 'Tom', null]);
 
 ## More information
 
-See [docs/INSTALL.md](docs/INSTALL.md) for installation instructions.  
 See [docs/USAGE.md](docs/USAGE.md) for usage examples.  
 See [docs/DEVELOP.md](docs/DEVELOP.md) for development details.
 

docs/INSTALL.md

@@ -1,71 +1,24 @@
 Usage
 =====
 
-This page shows concise examples for all available value objects and how to create your own.
-
-Namespace
----------
-
-All classes live under the base namespace:
-
-```
-PhpTypedValues
-```
-
-Available types
----------------
-
-Integers (PhpTypedValues\Integer):
-
-- IntegerBasic — any PHP integer
-- PositiveInt — positive integer (> 0)
-- NonNegativeInt — zero or positive integer (>= 0)
-- WeekDayInt — integer in range 1..7
-
-Strings (PhpTypedValues\String):
-
-- StringBasic — any PHP string
-- NonEmptyStr — non-empty string
-
-Floats (PhpTypedValues\Float):
-
-- FloatBasic — any PHP float
-- NonNegativeFloat — zero or positive float (>= 0)
-
-DateTime (PhpTypedValues\DateTime):
-
-- DateTimeAtom — immutable DateTime in RFC3339 (ATOM) format
-- DateTimeTimestamp — immutable DateTime represented as a Unix timestamp (seconds since epoch, UTC)
+This page shows concise examples for available value objects and how to create your own.
 
 Static usage examples
 ---------------------
 
 ```php
-use PhpTypedValues\DateTime\DateTimeAtom;use PhpTypedValues\DateTime\Timestamp\TimestampSeconds;use PhpTypedValues\Float\FloatStandard;use PhpTypedValues\Float\FloatNonNegative;use PhpTypedValues\Integer\IntegerStandard;use PhpTypedValues\Integer\IntegerNonNegative;use PhpTypedValues\Integer\IntegerPositive;use PhpTypedValues\Integer\IntegerWeekDay;use PhpTypedValues\String\StringNonEmpty;use PhpTypedValues\String\StringStandard;
-
-// Integers
 $any = IntegerStandard::fromInt(-10);
 $pos = IntegerPositive::fromInt(1);
 $nn  = IntegerNonNegative::fromInt(0);
 $wd  = IntegerWeekDay::fromInt(7);        // 1..7
-
-// From string (integers)
 $posFromString = IntegerPositive::fromString('123');
 $wdFromString  = IntegerWeekDay::fromString('5');
-
-// Strings
 $greeting = StringStandard::fromString('hello');
 $name     = StringNonEmpty::fromString('Alice');
-
-// Floats
 $price = FloatStandard::fromString('19.99');
 $ratio = FloatNonNegative::fromFloat(0.5);  // >= 0
-
-// DateTime (RFC 3339 / ATOM)
-$dt = DateTimeAtom::fromString('2025-01-02T03:04:05+00:00');
-
-// DateTime (Unix timestamp, seconds)
-$unix = TimestampSeconds::fromString('1735787045');
+$dt = DateTimeAtom::fromString('2025-01-02T03:04:05+00:00'); // DateTime (RFC 3339 / ATOM)
+$unix = TimestampSeconds::fromString('1735787045'); // DateTime (Unix timestamp, seconds)
 
 // Accessing value and string form
 $posValue = $pos->value();        // 1 (int)
@@ -81,21 +34,11 @@ Validation errors (static constructors)
 Invalid input throws an exception with a helpful message.
 
 ```php
-use PhpTypedValues\Integer\IntegerPositive;
-use PhpTypedValues\Integer\IntegerWeekDay;
-use PhpTypedValues\String\StringNonEmpty;
-use PhpTypedValues\Float\FloatNonNegative;
-use PhpTypedValues\DateTime\DateTimeAtom;
-
 IntegerPositive::fromInt(0);              // throws: must be > 0
 IntegerPositive::fromString('12.3');      // throws: String has no valid integer
-
 IntegerWeekDay::fromInt(0);               // throws: Value must be between 1 and 7
-
 StringNonEmpty::fromString('');          // throws: Value must be a non-empty string
-
 FloatNonNegative::fromString('abc');  // throws: String has no valid float
-
 DateTimeAtom::fromString('not-a-date'); // throws: String has no valid datetime
 ```
 
@@ -106,12 +49,6 @@ If you want a domain-specific alias (e.g., UserId) that behaves like PositiveInt
 
 ```php
 <?php
-declare(strict_types=1);
-
-namespace App\Domain;
-
-use PhpTypedValues\Integer\IntegerPositive;
-
 final class UserId extends IntegerPositive {}
 
 // Usage
@@ -130,16 +67,16 @@ declare(strict_types=1);
 namespace App\Domain;
 
 use PhpTypedValues\Abstract\Assert\Assert;
-use PhpTypedValues\Exception\FloatTypeException;
+use PhpTypedValues\Exception\IntegerTypeException;
 use PhpTypedValues\Abstract\Integer\IntType;
 
-final class EvenPositiveInt extends IntType
+readonly class EvenPositiveInt extends IntType
 {
     /** @var positive-int */
     protected int $value;
 
     /**
-     * @throws FloatTypeException
+     * @throws IntegerTypeException
      */
     public function __construct(int $value)
     {

docs/USAGE.md

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\Abstract\Undefined;
+
+use PhpTypedValues\Exception\UndefinedTypeException;
+
+/**
+ * Special type for "Undefined" \ "Unknown" state.
+ * Use it to return type hints when you don't know the value.
+ * Use it instead of NULL (could mean anything) to make your code more readable.
+ *
+ * @psalm-immutable
+ */
+abstract readonly class UndefinedType implements UndefinedTypeInterface
+{
+    public static function create(): self
+    {
+        return new static();
+    }
+
+    /**
+     * @throws UndefinedTypeException
+     */
+    public function toString(): void
+    {
+        throw new UndefinedTypeException('Undefined type cannot be converted to string.');
+    }
+
+    /**
+     * @throws UndefinedTypeException
+     */
+    public function value(): void
+    {
+        throw new UndefinedTypeException('Undefined type has no value.');
+    }
+}

src/Abstract/Undefined/UndefinedType.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\Abstract\Undefined;
+
+/**
+ * @psalm-immutable
+ */
+interface UndefinedTypeInterface
+{
+    public static function create(): self;
+
+    public function value(): void;
+
+    public function toString(): void;
+}

src/Abstract/Undefined/UndefinedTypeInterface.php

@@ -32,12 +32,12 @@ public static function fromString(string $value): static
     {
         $lowerCaseValue = strtolower($value);
 
-        if ($lowerCaseValue === 'true') {
+        if ($lowerCaseValue === 'true' || $lowerCaseValue === '1') {
             $boolValue = true;
-        } elseif ($lowerCaseValue === 'false') {
+        } elseif ($lowerCaseValue === 'false' || $lowerCaseValue === '0') {
             $boolValue = false;
         } else {
-            throw new BoolTypeException(sprintf('Expected string "true" or "false", got "%s"', $value));
+            throw new BoolTypeException(sprintf('Expected string "true"\"1" or "false"\"0", got "%s"', $value));
         }
 
         return new static($boolValue);

src/Bool/BoolStandard.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\Exception;
+
+class UndefinedTypeException extends TypeException
+{
+}

src/Exception/UndefinedTypeException.php

@@ -4,7 +4,7 @@
 
 namespace PhpTypedValues\Integer\Alias;
 
-use PhpTypedValues\Integer\DB\IntTiny;
+use PhpTypedValues\Integer\MariaDb\IntTiny;
 
 /**
  * Alias of IntTiny.

src/Integer/Alias/TinyInt.php

@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace PhpTypedValues\Integer\DB;
+namespace PhpTypedValues\Integer\MariaDb;
 
 use PhpTypedValues\Abstract\Integer\IntType;
 use PhpTypedValues\Exception\IntegerTypeException;

src/Integer/DB/IntTiny.php src/Integer/MariaDb/IntTiny.phpsrc/Integer/DB/IntTiny.php renamed to src/Integer/MariaDb/IntTiny.php

@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace PhpTypedValues\String\DB;
+namespace PhpTypedValues\String\MariaDb;
 
 use PhpTypedValues\Abstract\String\StrType;
 use PhpTypedValues\Exception\StringTypeException;