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

Author: ReallifeKip

CHANGELOG.md

@@ -1,5 +1,14 @@
 # CHANGELOG
 
+## [4.3.0] - 2026-04-19
+
+### Added
+
+- **`#[InputKeyTo(KeyCase::X)]`** — Input key case conversion. Apply at class level to remap all incoming array keys before hydration, or at property level to override for a specific property. Conversion splits on camelCase/PascalCase boundaries, underscores, hyphens, and whitespace, then rejoins in the target case.
+- **`#[OutputKeyTo(KeyCase::X)]`** — Output key case conversion. Apply at class level to remap all serialized keys during `toArray(true)` / `toJson(true)`, or at property level to override for a specific property.
+- **`KeyCase` enum** — 8 naming conventions: `Snake` (`nick_name`), `PascalSnake` (`Nick_Name`), `Macro` (`NICK_NAME`), `Camel` (`nickName`), `Pascal` (`NickName`), `Kebab` (`nick-name`), `CamelKebab` (`nick-Name`), `Train` (`Nick-Name`).
+- **`InvalidKeyCaseException`** — Thrown at definition time when `#[InputKeyTo]` or `#[OutputKeyTo]` receives a value that is not a `KeyCase` enum instance (e.g. a plain string).
+
 ## [4.2.2] - 2026-03-14
 
 ### Fixed

README.md

@@ -603,6 +603,60 @@ try {
 
 By default, the VO and SVO validation chain walks from the top of the inheritance chain down to the current class. With `#[ValidateFromSelf]` applied, the chain is reversed to start from the current class and walk upward.
 
+### `#[InputKeyTo]` - Input Key Case Conversion
+
+Converts incoming array keys to the specified `KeyCase` naming convention before hydration. Applied at class level, it remaps all keys; applied at property level, it overrides the class-level conversion for that property only.
+
+```php
+use ReallifeKip\ImmutableBase\Attributes\InputKeyTo;
+use ReallifeKip\ImmutableBase\Enums\KeyCase;
+
+// Class-level: accepts snake_case input keys (nick_name → nickName)
+#[InputKeyTo(KeyCase::Camel)]
+readonly class UserDTO extends DataTransferObject
+{
+    public string $nickName;
+}
+
+UserDTO::fromArray(['nick_name' => 'Kip']); // nickName = 'Kip'
+```
+
+### `#[OutputKeyTo]` - Output Key Case Conversion
+
+Converts property names to the specified `KeyCase` naming convention during serialization. Applied at class level, it remaps all serialized keys; applied at property level, it overrides the class-level conversion for that property only.
+
+The argument passed to `toArray()` / `toJson()` controls the conversion behavior:
+- `false` (default): no key conversion — property names are output as-is
+- `true`: applies the `#[OutputKeyTo]`-defined conversion for the current level only — nested objects use their own `#[OutputKeyTo]` declarations independently and are not affected
+- `KeyCase::*`: ignores `#[OutputKeyTo]` and forces the specified case globally
+
+```php
+use ReallifeKip\ImmutableBase\Attributes\OutputKeyTo;
+use ReallifeKip\ImmutableBase\Enums\KeyCase;
+
+// Class-level: serializes nickName → nick_name
+#[OutputKeyTo(KeyCase::Snake)]
+readonly class UserDTO extends DataTransferObject
+{
+    public string $nickName;
+}
+
+UserDTO::fromArray(['nickName' => 'Kip'])->toArray(true); // ['nick_name' => 'Kip']
+```
+
+Available `KeyCase` values:
+
+| Case | Example |
+|---|---|
+| `KeyCase::Snake` | `nick_name` |
+| `KeyCase::PascalSnake` | `Nick_Name` |
+| `KeyCase::Macro` | `NICK_NAME` |
+| `KeyCase::Camel` | `nickName` |
+| `KeyCase::Pascal` | `NickName` |
+| `KeyCase::Kebab` | `nick-name` |
+| `KeyCase::CamelKebab` | `nick-Name` |
+| `KeyCase::Train` | `Nick-Name` |
+
 ---
 
 ## Configuration
@@ -681,6 +735,8 @@ Thrown when class structure or attribute configuration is incorrect. These are p
 
 `InvalidSpecException` - `#[Spec]` is used without an argument or with an empty argument.
 
+`InvalidKeyCaseException` - `#[InputKeyTo]` or `#[OutputKeyTo]` received a value that is not a `KeyCase` enum instance (e.g. a plain string instead of `KeyCase::Camel`).
+
 `InvalidCompareTargetException` - The `equals()` comparison target is not the same class, or an array contains a non-ImmutableBase object that cannot be compared.
 
 `InvalidWithPathException` - A `with()` deep path targets a scalar property that cannot be traversed further.

README_TW.md

@@ -602,6 +602,60 @@ try {
 
 VO、SVO 驗證鏈預設由繼承鏈頂層向下驗證到當前類，套用 `#[ValidateFromSelf]` 後，驗證鏈將改為從當前類開始向上驗證。
 
+### `#[InputKeyTo]` - 輸入 Key 命名轉換
+
+在注入前將輸入陣列的 key 轉換為指定的 `KeyCase` 命名規則。套用於類層級時，轉換所有 key；套用於屬性層級時，僅覆蓋該屬性的類層級設定。
+
+```php
+use ReallifeKip\ImmutableBase\Attributes\InputKeyTo;
+use ReallifeKip\ImmutableBase\Enums\KeyCase;
+
+// 類層級：接受 snake_case 輸入 key（nick_name → nickName）
+#[InputKeyTo(KeyCase::Camel)]
+readonly class UserDTO extends DataTransferObject
+{
+    public string $nickName;
+}
+
+UserDTO::fromArray(['nick_name' => 'Kip']); // nickName = 'Kip'
+```
+
+### `#[OutputKeyTo]` - 輸出 Key 命名轉換
+
+序列化時，將屬性名稱轉換為指定的 `KeyCase` 命名規則。套用於類層級時，轉換所有序列化 key；套用於屬性層級時，僅覆蓋該屬性的類層級設定。
+
+`toArray()` / `toJson()` 的引數決定轉換行為：
+- `false`（預設）：不套用任何 key 轉換，屬性名稱原樣輸出
+- `true`：套用 `#[OutputKeyTo]` 定義的轉換，僅作用於當前層級，不向下滲透至巢狀物件（巢狀物件依各自的 `#[OutputKeyTo]` 宣告獨立運作）
+- `KeyCase::*`：忽略 `#[OutputKeyTo]`，以指定的 `KeyCase` 強制覆蓋所有 key
+
+```php
+use ReallifeKip\ImmutableBase\Attributes\OutputKeyTo;
+use ReallifeKip\ImmutableBase\Enums\KeyCase;
+
+// 類層級：將 nickName 序列化為 nick_name
+#[OutputKeyTo(KeyCase::Snake)]
+readonly class UserDTO extends DataTransferObject
+{
+    public string $nickName;
+}
+
+UserDTO::fromArray(['nickName' => 'Kip'])->toArray(true); // ['nick_name' => 'Kip']
+```
+
+可用的 `KeyCase` 值：
+
+| 命名規則 | 範例 |
+|---|---|
+| `KeyCase::Snake` | `nick_name` |
+| `KeyCase::PascalSnake` | `Nick_Name` |
+| `KeyCase::Macro` | `NICK_NAME` |
+| `KeyCase::Camel` | `nickName` |
+| `KeyCase::Pascal` | `NickName` |
+| `KeyCase::Kebab` | `nick-name` |
+| `KeyCase::CamelKebab` | `nick-Name` |
+| `KeyCase::Train` | `Nick-Name` |
+
 ---
 
 ## 設定
@@ -680,6 +734,8 @@ vendor/bin/ib-writer
 
 `InvalidSpecException` - `#[Spec]` 未提供引數或引數為空。
 
+`InvalidKeyCaseException` - `#[InputKeyTo]` 或 `#[OutputKeyTo]` 接收到非 `KeyCase` enum 實例的值（例如傳入純字串而非 `KeyCase::Camel`）。
+
 `InvalidCompareTargetException` - `equals()` 的比較對象與自身類不同，或陣列中包含無法比較的非 ImmutableBase 物件。
 
 `InvalidWithPathException` - `with()` 的深層路徑指向純量屬性，無法向下展開。

benchmarks/DataTransferObjects/InputKeyDTO.php

@@ -0,0 +1,20 @@
+<?php
+
+declare (strict_types = 1);
+namespace Benchmarks\DataTransferObjects;
+
+use ReallifeKip\ImmutableBase\Attributes\InputKeyTo;
+use ReallifeKip\ImmutableBase\Enums\KeyCase;
+use ReallifeKip\ImmutableBase\Objects\DataTransferObject;
+
+#[InputKeyTo(KeyCase::Camel)]
+readonly class InputKeyDTO extends DataTransferObject
+{
+    public string $firstName;
+    public string $lastName;
+    public string $emailAddress;
+    public int $accountId;
+    public bool $isActive;
+    public string $createdAt;
+    public string $updatedAt;
+}

benchmarks/DataTransferObjects/OutputKeyDTO.php

@@ -0,0 +1,20 @@
+<?php
+
+declare (strict_types = 1);
+namespace Benchmarks\DataTransferObjects;
+
+use ReallifeKip\ImmutableBase\Attributes\OutputKeyTo;
+use ReallifeKip\ImmutableBase\Enums\KeyCase;
+use ReallifeKip\ImmutableBase\Objects\DataTransferObject;
+
+#[OutputKeyTo(KeyCase::Snake)]
+readonly class OutputKeyDTO extends DataTransferObject
+{
+    public string $firstName;
+    public string $lastName;
+    public string $emailAddress;
+    public int $accountId;
+    public bool $isActive;
+    public string $createdAt;
+    public string $updatedAt;
+}

benchmarks/DefaultBench.php

@@ -7,9 +7,8 @@
 use Benchmarks\DataTransferObjects\Order;
 use Benchmarks\DataTransferObjects\SimpleDTO;
 use ReallifeKip\ImmutableBase\ImmutableBase;
-use ReallifeKip\ImmutableBase\StaticStatus;
 
-if (StaticStatus::$cachedMeta === []) {
+if (ImmutableBase::state()['cachedMeta'] === []) {
     ImmutableBase::loadCache();
 }
 

benchmarks/KeyCaseBench.php

@@ -0,0 +1,66 @@
+<?php
+
+declare (strict_types = 1);
+namespace Benchmarks;
+
+use Benchmarks\DataTransferObjects\InputKeyDTO;
+use Benchmarks\DataTransferObjects\OutputKeyDTO;
+use ReallifeKip\ImmutableBase\ImmutableBase;
+
+if (ImmutableBase::state()['cachedMeta'] === []) {
+    ImmutableBase::loadCache();
+}
+
+/**
+ * @Warmup(5)
+ * @BeforeMethods("setUp")
+ * @Revs(1000)
+ * @Iterations(15)
+ * @OutputTimeUnit("milliseconds")
+ */
+class KeyCaseBench
+{
+    private array $snakePayload;
+    private array $camelPayload;
+    private OutputKeyDTO $outputKeyDTO;
+
+    public function setUp()
+    {
+        $this->snakePayload = [
+            'first_name'    => 'Kip',
+            'last_name'     => 'The Architect',
+            'email_address' => 'kip@example.com',
+            'account_id'    => 42,
+            'is_active'     => true,
+            'created_at'    => '2026-01-01T00:00:00Z',
+            'updated_at'    => '2026-04-19T00:00:00Z',
+        ];
+
+        $this->camelPayload = [
+            'firstName'    => 'Kip',
+            'lastName'     => 'The Architect',
+            'emailAddress' => 'kip@example.com',
+            'accountId'    => 42,
+            'isActive'     => true,
+            'createdAt'    => '2026-01-01T00:00:00Z',
+            'updatedAt'    => '2026-04-19T00:00:00Z',
+        ];
+
+        $this->outputKeyDTO = OutputKeyDTO::fromArray($this->camelPayload);
+    }
+
+    public function benchInputKeyHydration(): void
+    {
+        InputKeyDTO::fromArray($this->snakePayload);
+    }
+
+    public function benchOutputKeySerialization(): void
+    {
+        $this->outputKeyDTO->toArray(true);
+    }
+
+    public function benchRoundTrip(): void
+    {
+        OutputKeyDTO::fromArray($this->camelPayload)->toArray(true);
+    }
+}

benchmarks/WidePayloadBench.php

@@ -6,9 +6,8 @@
 use Benchmarks\DataTransferObjects\TargetDTO;
 use Benchmarks\DataTransferObjects\WideFlatDTO;
 use ReallifeKip\ImmutableBase\ImmutableBase;
-use ReallifeKip\ImmutableBase\StaticStatus;
 
-if (StaticStatus::$cachedMeta === []) {
+if (ImmutableBase::state()['cachedMeta'] === []) {
     ImmutableBase::loadCache();
 }
 

benchmarks/With.php benchmarks/WithBench.phpbenchmarks/With.php renamed to benchmarks/WithBench.php

@@ -10,9 +10,8 @@
 use Benchmarks\Enums\OrderStatus;
 use PhpBench\Attributes\BeforeMethods;
 use ReallifeKip\ImmutableBase\ImmutableBase;
-use ReallifeKip\ImmutableBase\StaticStatus;
 
-if (StaticStatus::$cachedMeta === []) {
+if (ImmutableBase::state()['cachedMeta'] === []) {
     ImmutableBase::loadCache();
 }
 

src/Attributes/InputKeyTo.php

@@ -0,0 +1,31 @@
+<?php
+
+declare (strict_types = 1);
+
+namespace ReallifeKip\ImmutableBase\Attributes;
+
+use ReallifeKip\ImmutableBase\Enums\KeyCase;
+
+/**
+ * Converts input array keys to a specified naming convention before hydration.
+ *
+ * When applied to a class, all input keys are converted to the target case
+ * before being matched against property names.
+ *
+ * When applied to a property, overrides any class-level conversion for that
+ * specific property only.
+ *
+ * Conversion splits words on camelCase/PascalCase boundaries, underscores,
+ * hyphens, and whitespace, then rejoins in the target case.
+ *
+ * @example #[InputKeyTo(KeyCase::Camel)]  — accepts snake_case input keys
+ * @example #[InputKeyTo(KeyCase::Snake)]  — accepts camelCase input keys
+ */
+#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_PROPERTY)]
+final class InputKeyTo
+{
+    private function __construct(KeyCase $keyCase)
+    {
+        // Prevents manual instantiation of the attribute.
+    }
+}