[core] v4.3.1 - See CHANGELOG.md for details

Author: ReallifeKip

CHANGELOG.md

@@ -1,5 +1,12 @@
 # CHANGELOG
 
+## [v4.3.1] - 2026-05-04
+
+### Fixed
+
+- **`fromJson()` list-rooted JSON rejection now matches the docblock contract.** Inputs that, after `trim`, begin with `[` and are not exactly `[]` throw `InvalidJsonException` at the start of `fromJson()`. Previously such inputs failed indirectly via downstream `RequiredValueException` during property resolution; catch sites that depended on the old exception type must be updated. The empty literal `[]` is intentionally permitted to preserve `toJson()` → `fromJson()` round-trips when `#[SkipOnNull]` empties an associative DTO (PHP's `json_encode([])` cannot disambiguate empty object from empty array).
+- **Sub-DTO JSON-string parsing symmetry.** Construction-path sub-DTO properties already accepted JSON-like strings via `buildResolver()`; the union dispatch path (`valueDecide()`) now applies the same `is_string && jsonLike => fromJson()` rule, eliminating the inconsistency where `Foo $foo` accepted `'{...}'` but `Foo|Bar $foo` rejected the same input.
+
 ## [v4.3.0] - 2026-04-19
 
 ### Added

README.md

@@ -755,7 +755,7 @@ Thrown during construction (`fromArray`, `fromJson`) or mutation (`with`) when i
 
 `InvalidEnumValueException` - The value cannot be resolved to any case of the target Enum; both name lookup and `tryFrom()` failed.
 
-`InvalidJsonException` - JSON string decoding failed.
+`InvalidJsonException` - The JSON string cannot be parsed into an object: malformed JSON, or non-empty list-rooted JSON (e.g. `[1,2,3]`). The empty literal `[]` is permitted to preserve `toJson()` → `fromJson()` round-trips when `#[SkipOnNull]` empties an associative DTO.
 
 #### ValidationException - Validation Errors
 

README_TW.md

@@ -754,7 +754,7 @@ vendor/bin/ib-writer
 
 `InvalidEnumValueException` - 值無法解析為目標 Enum 的任何 case，名稱查找及 `tryFrom()` 皆失敗。
 
-`InvalidJsonException` - JSON 字串解碼失敗。
+`InvalidJsonException` - JSON 字串無法解析為物件：JSON 格式錯誤，或為非空 list-rooted JSON（如 `[1,2,3]`）。空字面 `[]` 為例外允許，以保留 `#[SkipOnNull]` 將關聯式 DTO 清空後的 `toJson()` → `fromJson()` round-trip。
 
 #### ValidationException - 驗證錯誤
 

src/ImmutableBase.php

@@ -611,10 +611,11 @@ private static function buildResolver(mixed $type, bool $isSub, bool $isSVO): ca
             $type['isUnion']     => static fn(mixed $value)     => self::unionTypeDecide($type, $value),
             !$type['isBuiltin']  => match (true) {
                 $isSub  => static fn(mixed $value): mixed  => match (true) {
-                    \is_array($value)           => $typename::fromArray($value),
-                    $value instanceof $typename => $value,
-                    $isSVO                      => $typename::from($value),
-                    default                     => throw new InvalidValueException($typename, $value)
+                    \is_array($value)                            => $typename::fromArray($value),
+                    $value instanceof $typename                  => $value,
+                    $isSVO                                       => $typename::from($value),
+                    \is_string($value) && self::jsonLike($value) => $typename::fromJson($value),
+                    default                                      => throw new InvalidValueException($typename, $value)
                 },
                 default => static fn(mixed $value): mixed => match (true) {
                     $value instanceof $typename           => $value,
@@ -700,6 +701,7 @@ private static function valueDecide(array $type, mixed $value): mixed
                 (\is_string($value) || \is_int($value)) && $type['isEnum']             => self::analyzeEnum($typename, $value),
                 \is_array($value) && is_a($typename, self::class, true)                => $typename::fromArray($value),
                 is_a($typename, SingleValueObject::class, true) && !\is_object($value) => $typename::from($value),
+                \is_string($value) && self::jsonLike($value) && is_a($typename, self::class, true) => $typename::fromJson($value),
                 default                                                                => throw new InvalidValueException($typename, $value),
             };
         }
@@ -1073,6 +1075,11 @@ final public static function fromArray(array $array): static
      */
     final public static function fromJson(string $data): static
     {
+        $trimmed = trim($data);
+        if (($trimmed[0] ?? '') === '[' && $trimmed !== '[]') {
+            throw new InvalidJsonException();
+        }
+
         return new static(self::jsonParser($data, false));
     }
 

tests/Attacks/AttackTest.php

@@ -448,10 +448,22 @@ public function testFromArrayEmptyWithRequiredProperties(): void
 
     public function testFromJsonWithArrayJsonThrows(): void
     {
-        $this->expectException(RequiredValueException::class);
+        $this->expectException(InvalidJsonException::class);
         AddressDTO::fromJson('[1,2,3]');
     }
 
+    public function testFromJsonWithSingleElementListJsonThrows(): void
+    {
+        $this->expectException(InvalidJsonException::class);
+        AddressDTO::fromJson('[1]');
+    }
+
+    public function testFromJsonWithLeadingWhitespaceListJsonThrows(): void
+    {
+        $this->expectException(InvalidJsonException::class);
+        AddressDTO::fromJson('   [1,2,3]');
+    }
+
     public function testDeepRoundTrip(): void
     {
         $data = [

tests/DefaultTest.php

@@ -559,6 +559,64 @@ public function testInvalidArrayOfNativeBoolException()
         ArrayOfDTO::fromArray(array_merge($this->arrayOfData, ['floats' => [1]]));
     }
 
+    public function testFromArrayWithJsonStringSubDtoSucceeds()
+    {
+        $extra = ExtraDTO::fromArray([
+            'string2'       => 'string2',
+            'dto'           => $this->json,
+            'unionClasses2' => SVO::from('x'),
+        ]);
+        $this->assertEquals(
+            DTO::fromArray($this->array)->toArray(),
+            $extra->dto->toArray(),
+        );
+    }
+
+    public function testFromArrayWithLeadingWhitespaceJsonStringSubDtoSucceeds()
+    {
+        $extra = ExtraDTO::fromArray([
+            'string2'       => 'string2',
+            'dto'           => '   ' . $this->json,
+            'unionClasses2' => SVO::from('x'),
+        ]);
+        $this->assertEquals(
+            DTO::fromArray($this->array)->toArray(),
+            $extra->dto->toArray(),
+        );
+    }
+
+    public function testFromArrayWithListRootedJsonStringSubDtoThrows()
+    {
+        $this->expectException(InvalidJsonException::class);
+        ExtraDTO::fromArray([
+            'string2'       => 'string2',
+            'dto'           => '[1,2,3]',
+            'unionClasses2' => SVO::from('x'),
+        ]);
+    }
+
+    public function testFromArrayWithMalformedJsonStringSubDtoThrows()
+    {
+        $this->expectException(InvalidJsonException::class);
+        ExtraDTO::fromArray([
+            'string2'       => 'string2',
+            'dto'           => '{garbage',
+            'unionClasses2' => SVO::from('x'),
+        ]);
+    }
+
+    public function testFromArrayWithJsonStringForUnionSubDtoSucceeds()
+    {
+        $union = UnionWithImmutableBaseTypeDTO::fromArray([
+            'mixed' => $this->json,
+        ]);
+        $this->assertInstanceOf(DTO::class, $union->mixed);
+        $this->assertEquals(
+            DTO::fromArray($this->array)->toArray(),
+            $union->mixed->toArray(),
+        );
+    }
+
     private static function attributeCoverage(string $class, mixed $argument)
     {
         $ref         = new ReflectionClass($class);