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

Author: ReallifeKip

CHANGELOG.md

@@ -1,5 +1,27 @@
 # CHANGELOG
 
+## [v4.4.0] - 2026-05-12
+
+### Added
+
+- **`#[ArrayOf]` now supports multiple types (polymorphic typed arrays).** Pass two or more class-strings or `Native` cases; each element is resolved against the declared types in declaration order — first successful match wins. Single-type usage is fully backwards compatible.
+
+  ```php
+  #[ArrayOf(ShippingDTO::class, PickupDTO::class)]
+  public array $deliveries;
+
+  #[ArrayOf(DTO1::class, Native::int)]
+  public array $mixed;
+  ```
+
+  > **Note:** The `ArrayOf` attribute's internal property has been renamed from `$class` (`string`) to `$classes` (`array`). If you inspect `ArrayOf` via `ReflectionAttribute::newInstance()`, update `->class` to `->classes[0]`.
+
+### Fixed
+
+- **`with()` silently ignored updates to nullable properties currently holding `null`.** The `isset($values[$path])` check in the flat-path loop returned `false` when an existing property value was `null`, causing the update to be skipped entirely. Replaced with `array_key_exists($path, $values)` so updates to null-valued properties are applied correctly.
+
+- **`#[ArrayOf()]` with no arguments now throws `InvalidArrayOfTargetException` at scan time.** Previously, the empty-argument case was silently ignored because `getAttributeArgument` collapsed empty attribute arguments to `null` via a truthiness check. The check has been corrected to distinguish "attribute absent" (`null`) from "attribute present with no arguments" (`[]`).
+
 ## [v4.3.2] - 2026-05-04
 
 ### Fixed

README.md

@@ -487,6 +487,8 @@ CreateUserDTO::fromArray(['name' => 'Kip']); // role = 'member'
 
 Marks an array property as a typed collection of ImmutableBase instances or primitive scalar values. Each element is automatically validated or instantiated. The target must be a subclass of DTO, VO, or SVO, or a `Native` enum case for scalar arrays.
 
+Pass multiple types for polymorphic arrays — each element is resolved in declaration order, first match wins.
+
 **Primitive scalar arrays** can be declared using `Native` enum cases instead of a class name:
 
 | Case             | PHP type |
@@ -501,7 +503,6 @@ use ReallifeKip\ImmutableBase\Attributes\ArrayOf;
 
 readonly class SignUpUsersDTO extends DataTransferObject
 {
-
     // ImmutableBase subclass
     #[ArrayOf(User::class)]
     public array $users;
@@ -511,6 +512,10 @@ readonly class SignUpUsersDTO extends DataTransferObject
     public array $tags;
     #[ArrayOf(Native::int)]
     public array $scores;
+
+    // Polymorphic — first match wins
+    #[ArrayOf(ShippingDTO::class, Native::string, PickupDTO::class, Native::int)]
+    public array $deliveries;
 }
 ```
 

README_TW.md

@@ -487,6 +487,8 @@ CreateUserDTO::fromArray(['name' => 'Kip']); // role = 'member'
 
 將陣列屬性標記為 ImmutableBase 實例或純量值的型別集合。每個元素會自動驗證或實例化。目標必須是 DTO、VO 或 SVO 的子類，或純量陣列可使用 `Native` enum case。
 
+傳入多個型別可宣告多型陣列——每個元素依宣告順序逐一嘗試，首個成功配對的型別勝出。
+
 **純量型別陣列**可使用 `Native` enum case 取代類別名稱：
 
 | Case             | PHP 型別 |
@@ -510,6 +512,10 @@ readonly class SignUpUsersDTO extends DataTransferObject
     public array $tags;
     #[ArrayOf(Native::int)]
     public array $scores;
+
+    // 多型——首個成功配對的型別勝出
+    #[ArrayOf(ShippingDTO::class, Native::string, PickupDTO::class, Native::int)]
+    public array $deliveries;
 }
 ```
 

src/Attributes/ArrayOf.php

@@ -1,33 +1,39 @@
-<?php
-
-declare (strict_types = 1);
-
-namespace ReallifeKip\ImmutableBase\Attributes;
-
-use ReallifeKip\ImmutableBase\Enums\Native;
-
-/**
- * Declares that an array property contains typed elements of a specific
- * ImmutableBase subclass, or validated PHP scalar values via Native.
- *
- * Accepts either a class-string of an ImmutableBase subclass, or a
- * Native enum case (Native::string, Native::int, Native::float, Native::bool)
- * for primitive typed arrays.
- *
- * Must be applied to properties typed exactly as `array`. Union types
- * or non-array types will trigger InvalidArrayOfUsageException at scan time.
- *
- * @example #[ArrayOf(OrderItemDTO::class)] public array $items
- * @example #[ArrayOf(Native::string)]      public array $tags
- * @example #[ArrayOf(Native::int)]         public array $scores
- */
-#[\Attribute(\Attribute::TARGET_PROPERTY)]
-final class ArrayOf
-{
-    /**
-     * @param class-string|Native $class FQCN of an ImmutableBase subclass, or a Native enum case for primitive typed arrays.
-     */
-    private function __construct(
-        public string $class
-    ) {}
-}
+<?php
+
+declare (strict_types = 1);
+
+namespace ReallifeKip\ImmutableBase\Attributes;
+
+use ReallifeKip\ImmutableBase\Enums\Native;
+
+/**
+ * Declares that an array property contains typed elements of one or more
+ * ImmutableBase subclasses, or validated PHP scalar values via Native.
+ *
+ * Accepts one or more class-strings of ImmutableBase subclasses, or Native
+ * enum cases (Native::string, Native::int, Native::float, Native::bool)
+ * for primitive typed arrays. When multiple types are given, each element
+ * is resolved against the declared types in order (first match wins).
+ *
+ * Must be applied to properties typed exactly as `array`. Union types
+ * or non-array types will trigger InvalidArrayOfUsageException at scan time.
+ *
+ * @example #[ArrayOf(OrderItemDTO::class)]              public array $items
+ * @example #[ArrayOf(Native::string)]                   public array $tags
+ * @example #[ArrayOf(Native::int)]                      public array $scores
+ * @example #[ArrayOf(ShippingDTO::class, PickupDTO::class)] public array $deliveries
+ */
+#[\Attribute(\Attribute::TARGET_PROPERTY)]
+final class ArrayOf
+{
+    /** @var list<string> */
+    public readonly array $classes;
+
+    /**
+     * @param class-string|Native ...$classes One or more FQCNs of ImmutableBase subclasses, or Native enum cases.
+     */
+    private function __construct(string | Native ...$classes)
+    {
+        $this->classes = array_values($classes);
+    }
+}

src/BasicTrait.php

@@ -19,8 +19,9 @@ trait BasicTrait
      * of the first matching attribute instance. When false, returns the
      * full argument array of the first matching instance.
      *
-     * If the attribute is not present, or present without constructor
-     * arguments, `null` is returned.
+     * If the attribute is not present, `null` is returned.
+     * When `$getFirst` is true and the attribute has no arguments, `null` is returned.
+     * When `$getFirst` is false and the attribute has no arguments, `[]` is returned.
      *
      * @param ReflectionClass|ReflectionProperty $target Reflection target to inspect.
      * @param class-string $name Fully-qualified attribute class name.
@@ -30,12 +31,9 @@ trait BasicTrait
     public static function getAttributeArgument(ReflectionClass | ReflectionProperty $target, string $name, bool $getFirst = true): mixed
     {
         if ($value = $target->getAttributes($name)) {
-            $value = $value[0];
-            if ($value = $value->getArguments()) {
-                return $getFirst ? $value[0] : $value;
-            }
+            $value = $value[0]->getArguments();
 
-            return null;
+            return $getFirst ? ($value[0] ?? null) : $value;
         }
 
         return null;