Add Json and JsonStr types with validation, parsing methods, and tests

- Introduced `Json` class for strict validation of JSON strings with methods for object and array conversion.
- Added `JsonStr` alias for ease of usage and improved code readability.
- Implemented comprehensive unit tests to ensure correct behavior, including exception handling for invalid JSON.
- Refactored `README.md` for better formatting and structure.
- Updated `typeUsageTest.php` with demonstrations of `Json` and `JsonStr` usage.

Author: georgedeploy

README.md

@@ -16,7 +16,6 @@ composer require georgii-web/php-typed-values
 
 ## Usage
 
-
 #### 1. Use existing typed values with validation built in:
 
 ```php
@@ -40,7 +39,7 @@ readonly class Id extends PositiveInt {}
 Id::fromInt(123);
 ```
 
-#### 3. Create a composite value object from other typed values (nullable values example):
+#### 3. Create a composite value object:
 
 ```php
 final class Profile
@@ -77,7 +76,6 @@ $profile = Profile::fromScalars(...[157, 'Tom', null]);
 $profile->getHeight(); // "172.5 \ Undefined" type class
 ```
 
-
 ## Key Features
 
 - **Static analysis** – Designed for tools like Psalm and PHPStan with precise type annotations.
@@ -92,7 +90,6 @@ $profile->getHeight(); // "172.5 \ Undefined" type class
 See [docs/USAGE.md](docs/USAGE.md) for usage examples.  
 See [docs/DEVELOP.md](docs/DEVELOP.md) for development details.
 
-
 ## License
 
 MIT

src/Exception/JsonTypeException.php

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

src/String/Alias/JsonStr.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\String\Alias;
+
+use PhpTypedValues\String\Json;
+
+/**
+ * @psalm-immutable
+ */
+readonly class JsonStr extends Json
+{
+}

src/String/Json.php

@@ -0,0 +1,84 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\String;
+
+use const JSON_THROW_ON_ERROR;
+
+use JsonException;
+use PhpTypedValues\Abstract\String\StrType;
+use PhpTypedValues\Exception\JsonTypeException;
+
+use function json_decode;
+use function sprintf;
+
+/**
+ * Represents a valid JSON text.
+ *
+ * Example '{"a":1}'
+ *
+ * @psalm-immutable
+ */
+readonly class Json extends StrType
+{
+    protected string $value;
+
+    /**
+     * @throws JsonTypeException
+     */
+    public function __construct(string $value)
+    {
+        self::assertJsonString($value);
+
+        $this->value = $value;
+    }
+
+    /**
+     * @throws JsonTypeException
+     */
+    public static function fromString(string $value): static
+    {
+        return new static($value);
+    }
+
+    public function value(): string
+    {
+        return $this->value;
+    }
+
+    /**
+     * @throws JsonException
+     */
+    public function toObject(): object
+    {
+        // Use named arguments and omit depth literal to avoid integer-mutation issues
+        return json_decode(json: $this->value, associative: false, flags: JSON_THROW_ON_ERROR);
+    }
+
+    /**
+     * @throws JsonException
+     */
+    public function toArray(): array
+    {
+        // Use named arguments and omit depth literal to avoid integer-mutation issues
+        return json_decode(json: $this->value, associative: true, flags: JSON_THROW_ON_ERROR);
+    }
+
+    /**
+     * @throws JsonTypeException
+     */
+    protected static function assertJsonString(string $value): void
+    {
+        try {
+            /**
+             * Only validate; ignore the decoded result. Exceptions signal invalid JSON.
+             *
+             * @psalm-suppress UnusedFunctionCall
+             */
+            json_decode(json: $value, flags: JSON_THROW_ON_ERROR);
+        } catch (JsonException $e) {
+            throw new JsonTypeException(sprintf('String "%s" has no valid JSON value', $value), 0, $e);
+        }
+    }
+}

src/typeUsageTest.php

@@ -33,9 +33,11 @@
 use PhpTypedValues\Integer\IntegerStandard;
 use PhpTypedValues\Integer\IntegerWeekDay;
 use PhpTypedValues\Integer\MariaDb\IntTiny;
+use PhpTypedValues\String\Alias\JsonStr;
 use PhpTypedValues\String\Alias\NonEmptyStr;
 use PhpTypedValues\String\Alias\Str;
 use PhpTypedValues\String\Alias\StrType;
+use PhpTypedValues\String\Json;
 use PhpTypedValues\String\StringNonEmpty;
 use PhpTypedValues\String\StringStandard;
 use PhpTypedValues\Undefined\Alias\NotExist;
@@ -119,6 +121,10 @@
 $tsVo = TimestampMilliseconds::fromString('1735787045123');
 echo TimestampMilliseconds::fromDateTime($tsVo->value())->toString() . \PHP_EOL;
 
+// JSON
+echo json_encode(JsonStr::fromString('{"a": 1, "b": "hi"}')->toArray(), \JSON_THROW_ON_ERROR);
+echo json_encode(Json::fromString('{"a": 1, "b": "hi"}')->toObject(), \JSON_THROW_ON_ERROR);
+
 // Undefined
 try {
     UndefinedStandard::create()->toString();

tests/Unit/String/JsonTest.php

@@ -0,0 +1,81 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpTypedValues\Exception\JsonTypeException;
+use PhpTypedValues\String\Json;
+
+it('constructs valid JSON via constructor', function (): void {
+    $json = new Json('{"a":1,"b":[true,null,3.14]}');
+    expect($json->value())->toBe('{"a":1,"b":[true,null,3.14]}')
+        ->and($json->toString())->toBe('{"a":1,"b":[true,null,3.14]}');
+});
+
+it('creates from string factory with valid JSON', function (): void {
+    $json = Json::fromString('"hello"');
+    expect($json->value())->toBe('"hello"');
+});
+
+it('accepts top-level number/boolean/null JSON', function (): void {
+    $n = Json::fromString('123');
+    $t = Json::fromString('true');
+    $nul = Json::fromString('null');
+    expect($n->toString())->toBe('123')
+        ->and($t->value())->toBe('true')
+        ->and($nul->toString())->toBe('null');
+});
+
+it('throws on empty string', function (): void {
+    expect(fn() => new Json(''))
+        ->toThrow(JsonTypeException::class, 'String "" has no valid JSON value');
+});
+
+it('throws on invalid JSON string via constructor', function (): void {
+    expect(fn() => new Json('{a:1}'))
+        ->toThrow(JsonTypeException::class, 'String "{a:1}" has no valid JSON value');
+});
+
+it('throws on invalid JSON string via fromString', function (): void {
+    expect(fn() => Json::fromString('{"a": }'))
+        ->toThrow(JsonTypeException::class, 'String "{"a": }" has no valid JSON value');
+});
+
+it('decodes to stdClass via toObject', function (): void {
+    $json = Json::fromString('{"name":"Alice","age":30,"flags":[true,false]}');
+    $obj = $json->toObject();
+
+    expect($obj)->toBeObject()
+        ->and($obj->name)->toBe('Alice')
+        ->and($obj->age)->toBe(30)
+        ->and($obj->flags)->toBeArray()
+        ->and($obj->flags)->toEqual([true, false]);
+});
+
+it('decodes to associative array via toArray', function (): void {
+    $json = Json::fromString('{"a":1,"b":{"c":[1,2,3]},"d":null}');
+    $arr = $json->toArray();
+
+    expect($arr)->toBeArray()
+        ->and($arr['a'])->toBe(1)
+        ->and($arr['b'])->toBeArray()
+        ->and($arr['b']['c'])->toEqual([1, 2, 3])
+        ->and($arr['d'])->toBeNull();
+});
+
+it('exception code is 0 for invalid JSON via constructor', function (): void {
+    try {
+        new Json('{a:1}');
+        expect()->fail('Expected exception not thrown');
+    } catch (JsonTypeException $e) {
+        expect($e->getCode())->toBe(0);
+    }
+});
+
+it('exception code is 0 for invalid JSON via fromString', function (): void {
+    try {
+        Json::fromString('{"a": }');
+        expect()->fail('Expected exception not thrown');
+    } catch (JsonTypeException $e) {
+        expect($e->getCode())->toBe(0);
+    }
+});