[feat] ArrayOf

1.新增 ArrayOf 標註支援陣列屬性的自動實例化功能。
2.調整 Relaxed、Expose 標註廢棄時程從 v2.2.0 延後至 v2.3.0。
3.更新 README 文檔說明新功能使用方式和完整範例。

Author: ReallifeKip

CHANGELOG

@@ -1,5 +1,40 @@
 # CHANGELOG
 
+## [v2.2.0] - 2025-07-31
+
+### 🎉 新功能
+- **新增 `#[ArrayOf]` 標註**：
+  - 支援陣列屬性的自動實例化
+  - 可指定陣列元素的類別類型
+  - 自動將陣列數據轉換為指定類別的實例
+  - 提供錯誤驗證，確保類別名稱不為空
+
+### 📝 更新
+- **調整廢棄時程**：
+  - `#[Relaxed]` - 廢棄時程延後至 v2.3.0
+  - `#[Expose]` - 廢棄時程延後至 v2.3.0
+
+### 📚 範例
+```php
+#[DataTransferObject]
+class UserListDTO extends ImmutableBase
+{
+    #[ArrayOf(UserDTO::class)]
+    public readonly array $users;
+}
+
+// 使用方式
+$userList = new UserListDTO([
+    'users' => [
+        ['name' => 'Alice', 'age' => 30],
+        ['name' => 'Bob', 'age' => 25]
+    ]
+]);
+// 自動將每個陣列元素轉換為 UserDTO 實例
+```
+
+---
+
 ## [v2.1.0] - 2025-08-01
 
 ### 🎉 新功能
@@ -18,8 +53,8 @@
   - 改進型別驗證錯誤訊息
 
 ### 🗑️ 即將棄用標註
-- `#[Relaxed]` - 標記為 @deprecated v2.2.0
-- `#[Expose]` - 標記為 @deprecated v2.2.0
+- `#[Relaxed]` - 標記為 @deprecated v2.3.0
+- `#[Expose]` - 標記為 @deprecated v2.3.0
 
 ### 📚 範例
 ```php

README.md

@@ -15,6 +15,7 @@
 - ✅ **支援 `with([...])` 複製模式，包含嵌套物件更新**
 - ✅ **自動 `toArray()` 與 `jsonSerialize()`**
 - ✅ **架構模式標註：`#[DataTransferObject]`、`#[ValueObject]`、`#[Entity]`**
+- ✅ **陣列自動實例化：`#[ArrayOf]`**
 - ✅ **屬性標註系統：`#[Expose]`、`#[Reason]`、`#[Relaxed]`**
 - ✅ **屬性訪問控制與設計原因強制說明**
 
@@ -147,7 +148,48 @@ class User extends ImmutableBase
 
 > ⚠️ **注意**：以下標註即將於 v2.2.0 棄用，建議使用架構模式標註。
 
-### `#[Expose]` - 輸出控制 (@deprecated v2.2.0)
+````
+
+### `#[ArrayOf]` - 陣列自動實例化
+
+指定陣列屬性中每個元素的類別，自動將陣列數據轉換為指定類別的實例：
+
+```php
+use ReallifeKip\ImmutableBase\ArrayOf;
+use ReallifeKip\ImmutableBase\DataTransferObject;
+
+#[DataTransferObject]
+class UserListDTO extends ImmutableBase
+{
+    #[ArrayOf(UserDTO::class)]
+    public readonly array $users;
+
+    #[ArrayOf(TagDTO::class)]
+    public readonly array $tags;
+}
+
+// 使用方式
+$userList = new UserListDTO([
+    'users' => [
+        ['name' => 'Alice', 'age' => 30],
+        ['name' => 'Bob', 'age' => 25]
+    ],
+    'tags' => [
+        ['name' => 'developer'],
+        ['name' => 'senior']
+    ]
+]);
+
+// users 和 tags 陣列中的每個元素都會自動轉換為對應的 DTO 實例
+````
+
+---
+
+## 屬性標註系統（將於 v2.3.0 棄用）
+
+> ⚠️ **注意**：以下標註將在 v2.3.0 標記為 deprecated，建議使用架構模式標註。
+
+### `#[Expose]` - 輸出控制 (將於 v2.3.0 棄用)
 
 標記可被 `toArray()` 和 `jsonSerialize()` 輸出的屬性：
 
@@ -161,7 +203,7 @@ class UserDTO extends ImmutableBase
 }
 ```
 
-### `#[Reason]` - 設計原因說明 (@deprecated v2.2.0)
+### `#[Reason]` - 設計原因說明 (將於 v2.3.0 棄用)
 
 當屬性不是 `private` 時，必須使用此標註說明設計原因：
 
@@ -177,7 +219,7 @@ class UserDTO extends ImmutableBase
 }
 ```
 
-### `#[Relaxed]` - 鬆散模式 (@deprecated v2.2.0)
+### `#[Relaxed]` - 鬆散模式 (將於 v2.3.0 棄用)
 
 標記在 class 上，允許不強制要求 `#[Reason]` 標註：
 
@@ -264,7 +306,8 @@ $user = $user->with([
 3. **不支援 constructor injection**：請以 `$data` array 傳入
 4. **屬性標註規則**：
    - **推薦**：使用架構模式標註 `#[DataTransferObject]`、`#[ValueObject]`、`#[Entity]`
-   - **已棄用**：`#[Expose]`、`#[Reason]`、`#[Relaxed]` 標註（v2.2.0 將移除）
+   - **陣列處理**：使用 `#[ArrayOf(ClassName::class)]` 進行陣列自動實例化
+   - **將棄用**：`#[Expose]`、`#[Reason]`、`#[Relaxed]` 標註（v2.3.0 將棄用）
    - DataTransferObject 要求所有屬性為 `public readonly`
    - ValueObject 和 Entity 要求所有屬性為 `private`
 
@@ -278,6 +321,7 @@ $user = $user->with([
 use ReallifeKip\ImmutableBase\ImmutableBase;
 use ReallifeKip\ImmutableBase\DataTransferObject;
 use ReallifeKip\ImmutableBase\ValueObject;
+use ReallifeKip\ImmutableBase\ArrayOf;
 
 #[DataTransferObject]
 class AddressDTO extends ImmutableBase
@@ -286,11 +330,21 @@ class AddressDTO extends ImmutableBase
     public readonly string $zipCode;
 }
 
+#[DataTransferObject]
+class TagDTO extends ImmutableBase
+{
+    public readonly string $name;
+    public readonly ?string $color = null;
+}
+
 #[DataTransferObject]
 class ProfileDTO extends ImmutableBase
 {
     public readonly AddressDTO $address;
     public readonly ?string $phone = null;
+
+    #[ArrayOf(TagDTO::class)]
+    public readonly array $tags;
 }
 
 #[ValueObject]
@@ -323,7 +377,11 @@ $user = new UserDTO([
             'city' => '台北市',
             'zipCode' => '10001'
         ],
-        'phone' => '0912-345-678'
+        'phone' => '0912-345-678',
+        'tags' => [
+            ['name' => 'developer', 'color' => 'blue'],
+            ['name' => 'senior', 'color' => 'gold']
+        ]
     ]
 ]);
 

src/ImmutableBase.php

@@ -36,6 +36,7 @@ final class Expose
  *
  * 所有屬性必須為 public readonly
  */
+#[\Attribute(\Attribute::TARGET_CLASS)]
 final class DataTransferObject
 {
 }
@@ -45,6 +46,7 @@ final class DataTransferObject
  *
  * 所有屬性必須為 private
  */
+#[\Attribute(\Attribute::TARGET_CLASS)]
 final class ValueObject
 {
 }
@@ -54,10 +56,24 @@ final class ValueObject
  *
  * 所有屬性必須為 private
  */
+#[\Attribute(\Attribute::TARGET_CLASS)]
 final class Entity
 {
 }
 
+#[\Attribute(\Attribute::TARGET_PROPERTY)]
+final class ArrayOf
+{
+    public bool $error = false;
+    public function __construct(
+        public string $class = '',
+    ) {
+        if (trim($this->class) === '') {
+            $this->error = true;
+        }
+    }
+}
+
 /**
  * 設計原因
  *
@@ -94,8 +110,17 @@ public function __construct(array $data = [])
                 $exists = array_key_exists($key, $data);
                 $nullable = $type->allowsNull();
                 $hasDefault = $property->hasDefaultValue();
+                $arrayOf = $property->getAttributes(ArrayOf::class);
+                $class = null;
+                if ($arrayOf) {
+                    if ($arrayOf[0]->newInstance()->error) {
+                        throw new Exception("ArrayOf class 不能為空");
+                    }
+                    $class = $arrayOf[0]->getArguments()[0];
+                }
                 $value = match(true) {
                     !$exists && !$nullable => throw new Exception("$key 必須傳入 $type"),
+                    $arrayOf && $class => array_map(fn ($item) => new $class($item), $data[$key]),
                     !$exists && $nullable && !$hasDefault => null,
                     !$exists && $nullable && $hasDefault => $property->getDefaultValue(),
                     $exists => $this->valueDecide($type, $data[$key]),
@@ -142,7 +167,7 @@ private function walkProperties(callable $callback): void
     /**
      * 更新並返回新的實例
      * @param array $data
-     * @return ImmutableBase
+     * @return static
      */
     final public function with(array $data): static
     {