Add jsonSerialize support across all typed value classes

- Implemented `jsonSerialize` method in `BoolStandard`, `TrueStandard`, `FalseStandard`, `FloatNonNegative`, `FloatPositive`, `FloatStandard`, `IntegerPositive`, `IntegerNonNegative`, `IntegerStandard`, `IntegerWeekDay`, `StringStandard`, `StringNonEmpty`, `StringCountryCode`, `StringEmail`, `StringJson`, `StringUrl`, `StringUuidV4`, `StringUuidV7`, `StringDecimal`, `StringText`, `StringVarChar255`, and respective MariaDB String classes to return native values.
- Updated unit tests to validate `jsonSerialize` behavior for all modified classes.
- Updated PHPUnit configuration to exclude legacy `src/Usage` directories.

Author: georgedeploy

README.md

@@ -27,7 +27,7 @@ composer require georgii-web/php-typed-values:^1.0
 #### 1. Use existing typed values with validation built in:
 
 ```php
-$id = PositiveInt::fromString('123');
+$id = IntegerPositive::fromString('123');
 ```
 
 instead of duplicating this logic across your application like:
@@ -42,15 +42,15 @@ if ($id <= 0) {
 #### 2. Create aliases:
 
 ```php
-readonly class Id extends PositiveInt {}
+readonly class Id extends IntegerPositive {}
 
 Id::fromInt(123);
 ```
 
 #### 3. Create a composite value object:
 
 ```php
-final class Profile
+final readonly class Profile
 {
     public function __construct(
         public readonly IntegerPositive $id,
@@ -65,21 +65,21 @@ final class Profile
     ): static {
         return new static(
             IntegerPositive::fromInt($id),
-            StringNonEmpty::fromString($firstName),
+            StringNonEmpty::fromString($firstName), // Early fail
             $height !== null ? FloatNonNegative::fromString((string) $height) : null,
         );
     }
 
     public function getHeight(): FloatNonNegative|Undefined { // avoid using NULL, which could mean anything
-        return $this->height ?? Undefined::create();
+        return $this->height ?? Undefined::create(); // Late fail
     }
 }
 
 // Usage
-Profile::fromScalars(id: 101, firstName: 'Alice', height: '172.5');
-Profile::fromScalars(id: 157, firstName: 'Tom', height: null);
+\PhpTypedValues\Usage\Composite::fromScalars(id: 101, firstName: 'Alice', height: '172.5');
+\PhpTypedValues\Usage\Composite::fromScalars(id: 157, firstName: 'Tom', height: null);
 // From array
-$profile = Profile::fromScalars(...[157, 'Tom', null]);
+$profile = \PhpTypedValues\Usage\Composite::fromScalars(...[157, 'Tom', null]);
 // Accessing values
 $profile->getHeight(); // "172.5" OR "Undefined" type class (will throw an exception on trying to get value)
 ```

composer.json

@@ -59,10 +59,10 @@
       "./vendor/bin/pest"
     ],
     "performance": [
-      "php ./src/Usage/Performance.php 1000 && php ./src/Usage/Performance.php 10000 && php ./src/Usage/Performance.php 100000 && php ./src/Usage/Performance.php 1000000"
+      "php ./src/Usage/Util/Performance.php 1000 && php ./src/Usage/Util/Performance.php 10000 && php ./src/Usage/Util/Performance.php 100000 && php ./src/Usage/Util/Performance.php 1000000"
     ],
     "usage": [
-      "php ./src/Usage/AllTypes.php"
+      "php ./src/Usage/Composite/Composite.php && php ./src/Usage/Primitive/Boolean.php && php ./src/Usage/Primitive/DateTime.php && php ./src/Usage/Primitive/Float.php && php ./src/Usage/Primitive/Integer.php && php ./src/Usage/Primitive/String.php && php ./src/Usage/Primitive/Undefined.php"
     ],
     "type": [
       "./vendor/bin/pest --type-coverage --min=100 --do-not-cache-result"

phpunit.xml

@@ -20,7 +20,9 @@
             <directory>src</directory>
         </include>
         <exclude>
-            <directory>src/Usage</directory>
+            <directory>src/Usage/Composite</directory>
+            <directory>src/Usage/Primitive</directory>
+            <directory>src/Usage/Util</directory>
         </exclude>
     </source>
 </phpunit>

src/Abstract/AbstractType.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\Abstract;
+
+use JsonSerializable;
+use PhpTypedValues\Exception\TypeException;
+use Stringable;
+
+use function is_scalar;
+
+/**
+ * Base class for immutable typed values.
+ *
+ * Responsibilities
+ *  - Define a common root for value objects in this library.
+ *  - Enforce immutability and a unified interface via {@see AbstractTypeInterface}.
+ *  - Mark all descendants as implementing {@see JsonSerializable} — concrete
+ *    classes SHOULD implement `jsonSerialize()` consistently with their
+ *    `toString()`/`value()` representation.
+ *
+ * Notes
+ *  - This class does not provide storage or behavior by itself; concrete
+ *    subclasses define validation, factories (e.g. `fromString()`), and accessors
+ *    (e.g. `value()` and formatting helpers).
+ *
+ * @internal
+ *
+ * @psalm-internal PhpTypedValues
+ *
+ * @psalm-immutable
+ */
+abstract readonly class AbstractType implements AbstractTypeInterface, JsonSerializable
+{
+    /**
+     * Safely attempts to convert a mixed value to a string.
+     * Returns null if conversion is impossible (array, resource, non-stringable object).
+     *
+     * @throws TypeException
+     */
+    public static function convertMixedToString(mixed $value): string
+    {
+        if (is_scalar($value) || $value === null) {
+            return (string) $value;
+        }
+
+        if ($value instanceof Stringable) {
+            return (string) $value;
+        }
+
+        throw new TypeException('Value cannot be cast to string');
+    }
+}

src/Abstract/AbstractTypeInterface.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\Abstract;
+
+use PhpTypedValues\Exception\TypeException;
+use PhpTypedValues\Undefined\Alias\Undefined;
+
+/**
+ * Base contract for all immutable typed values in this library.
+ *
+ * Responsibilities
+ *  - Provide strict construction from a validated string via {@see fromString}.
+ *  - Provide a lossless string representation via {@see toString} and {@see __toString}.
+ *  - Concrete implementations may also provide tolerant factories like
+ *    `tryFromMixed(mixed): static|Undefined` that return {@see Undefined} on failure.
+ *
+ * Notes
+ *  - All implementations MUST be immutable.
+ *
+ * @psalm-immutable
+ */
+interface AbstractTypeInterface
+{
+    /**
+     * Create an instance from a validated string representation.
+     *
+     * Implementations should perform strict validation and may throw a
+     * domain-specific subtype of {@see TypeException}
+     * when the provided value is invalid.
+     *
+     * @throws TypeException
+     */
+    public static function fromString(string $value): static;
+
+    //    public static function tryFromMixed(mixed $value): static|Undefined;
+
+    /**
+     * Returns a normalized string representation of the underlying value.
+     */
+    public function toString(): string;
+
+    /**
+     * Alias of {@see toString} for convenient casting.
+     */
+    public function __toString(): string;
+}

src/Abstract/Bool/BoolType.php

@@ -4,7 +4,7 @@
 
 namespace PhpTypedValues\Abstract\Bool;
 
-use PhpTypedValues\Abstract\TypeInterface;
+use PhpTypedValues\Abstract\AbstractType;
 
 /**
  * Base implementation for boolean typed values.
@@ -17,9 +17,13 @@
  *  - $v = MyBoolean::fromBool(true);
  *  - $v->toString(); // "true"
  *
+ * @internal
+ *
+ * @psalm-internal PhpTypedValues
+ *
  * @psalm-immutable
  */
-abstract readonly class BoolType implements TypeInterface, BoolTypeInterface
+abstract readonly class BoolType extends AbstractType implements BoolTypeInterface
 {
     abstract protected function __construct(bool $value);
 

src/Abstract/Bool/BoolTypeInterface.php

@@ -27,11 +27,5 @@ public static function tryFromString(string $value): static|Undefined;
 
     public static function tryFromInt(int $value): static|Undefined;
 
-    public static function fromString(string $value): static;
-
     public static function fromBool(bool $value): static;
-
-    public function toString(): string;
-
-    public function __toString(): string;
 }

src/Abstract/DateTime/DateTimeType.php

@@ -8,7 +8,7 @@
 
 use DateTimeImmutable;
 use DateTimeZone;
-use PhpTypedValues\Abstract\TypeInterface;
+use PhpTypedValues\Abstract\AbstractType;
 use PhpTypedValues\Exception\DateTimeTypeException;
 use PhpTypedValues\Exception\ReasonableRangeDateTimeTypeException;
 
@@ -19,16 +19,20 @@
  * Base implementation for DateTime typed values.
  *
  * Provides strict parsing with detailed error aggregation, round-trip
- * validation against the format, timezone normalization and reasonable
+ * validation against the format, timezone normalization, and reasonable
  * timestamp range checks.
  *
  * Example
  *  - $v = MyDateTime::fromString('2025-01-02T03:04:05+00:00');
  *  - $v->toString(); // '2025-01-02T03:04:05+00:00'
  *
+ * @internal
+ *
+ * @psalm-internal PhpTypedValues
+ *
  * @psalm-immutable
  */
-abstract readonly class DateTimeType implements TypeInterface, DateTimeTypeInterface
+abstract readonly class DateTimeType extends AbstractType implements DateTimeTypeInterface
 {
     protected const FORMAT = '';
     protected const ZONE = 'UTC';

src/Abstract/DateTime/DateTimeTypeInterface.php

@@ -27,10 +27,4 @@ public function value(): DateTimeImmutable;
     public static function fromDateTime(DateTimeImmutable $value): static;
 
     public static function tryFromString(string $value): static|Undefined;
-
-    public function toString(): string;
-
-    public static function fromString(string $value): static;
-
-    public function __toString(): string;
 }

src/Abstract/Float/FloatType.php

@@ -4,7 +4,7 @@
 
 namespace PhpTypedValues\Abstract\Float;
 
-use PhpTypedValues\Abstract\TypeInterface;
+use PhpTypedValues\Abstract\AbstractType;
 use PhpTypedValues\Exception\FloatTypeException;
 
 use function sprintf;
@@ -20,9 +20,13 @@
  *  - $v->value(); // 3.14 (float)
  *  - (string) $v; // "3.14"
  *
+ * @internal
+ *
+ * @psalm-internal PhpTypedValues
+ *
  * @psalm-immutable
  */
-abstract readonly class FloatType implements TypeInterface, FloatTypeInterface
+abstract readonly class FloatType extends AbstractType implements FloatTypeInterface
 {
     /**
      * @throws FloatTypeException