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

Author: ReallifeKip

CHANGELOG.md

@@ -1,5 +1,24 @@
 # CHANGELOG
 
+## [v4.1.0] - 2026-03-07
+
+### Added
+
+- **`defaultValues()` — Static default value declaration.** Override `defaultValues(): array` to declare fallback values for properties absent from input data. Keys must match declared property names; unmatched keys are silently ignored. Supports any type valid for the target property, including subclasses of ImmutableBase and Enum.
+- **`#[Defaults(value)]` — Attribute-based default value.** Apply `#[Defaults(value)]` to individual properties for constant-expression defaults. Constrained by PHP attribute syntax to scalar values, arrays, and class constants.
+- **Default value resolution priority.** During construction (`fromArray` / `fromJson`), property values are resolved in the following order:
+  1. Explicit input value (including explicit `null`)
+  2. `defaultValues()[$propertyName]`
+  3. `#[Defaults(value)]` attribute value
+  4. `null` (if nullable) or `RequiredValueException`
+- **Explicit `null` is respected.** When a key is present in the input with a `null` value, it is treated as an intentional assignment — default values are not applied.
+- **Cache-aware default values.** `ib-cacher` serializes cacheable default values (scalars, arrays) into the cache file. Non-serializable defaults (objects, Closures) are excluded from the cache with a `[Notice]` warning and resolved at runtime via `defaultValues()` on every construction.
+- **SVO `defaultValues()` sealed.** `SingleValueObject::defaultValues()` is declared `final` and returns an empty array. SVOs require explicit values via `from()` by design.
+
+### Changed
+
+- **`__construct()` uses `array_key_exists()` for default resolution.** Replaces `isset()` to correctly distinguish between "key absent" (apply default) and "key present with `null`" (respect explicit null).
+
 ## [v4.0.0] - 2026-03-01
 
 ### Breaking Changes

README.md

@@ -51,6 +51,31 @@ class Order extends DataTransferObject
 new Order('2026-01-01', '00:00:00', ...); // Cannot directly accept external array or JSON data, and risks argument misordering if parameter names are not explicitly specified
 ```
 
+### 🛡️ Declarative Default Values
+```php
+// 🥳 ImmutableBase fills missing properties from defaultValues() or #[Defaults], with clear priority and null-awareness.
+readonly class CreateUserDTO extends DataTransferObject
+{
+    public string $name;
+    #[Defaults('member')]
+    public string $role;
+
+    public static function defaultValues(): array
+    {
+        return ['role' => 'admin']; // Takes precedence over #[Defaults]
+    }
+}
+CreateUserDTO::fromArray(['name' => 'Kip']); // role = 'admin'
+
+// 🫤 The conventional approach requires manual null-coalescing or constructor defaults, with no centralized declaration.
+class CreateUserDTO {
+    public function __construct(
+        public readonly string $name,
+        public readonly string $role = 'member', // Cannot be overridden per-class without rewriting constructors
+    ){}
+}
+```
+
 ### 🔧 Flexible Deep Path Updates
 Update deeply nested properties by path - no Russian nesting dolls.
 ```php
@@ -355,8 +380,107 @@ $age1->equals($age3);  // false
 
 ---
 
+## Default Values
+
+Properties absent from input data can be populated with fallback values via two complementary mechanisms.
+
+### `defaultValues()` — Dynamic Defaults
+
+Override the static method to declare default values as an associative array keyed by property name. Supports any type valid for the target property, including subclasses of ImmutableBase and Enum.
+
+```php
+readonly class CreateUserDTO extends DataTransferObject
+{
+    public string $name;
+    public string $role;
+    public string $locale;
+
+    public static function defaultValues(): array
+    {
+        return [
+            'role'   => 'member',
+            'locale' => 'en',
+        ];
+    }
+}
+CreateUserDTO::fromArray(['name' => 'Kip']); // role = 'member', locale = 'en'
+```
+
+### `#[Defaults]` — Attribute Defaults
+
+Apply `#[Defaults(value)]` to individual properties for inline constant-expression defaults. Constrained by PHP attribute syntax to scalars, arrays, and class constants.
+
+```php
+use ReallifeKip\ImmutableBase\Attributes\Defaults;
+
+readonly class CreateUserDTO extends DataTransferObject
+{
+    public string $name;
+    #[Defaults('member')]
+    public string $role;
+    #[Defaults('en')]
+    public string $locale;
+}
+```
+
+### Resolution Priority
+
+When a property key is absent from the input data, defaults are resolved in this order:
+
+1. `defaultValues()[$propertyName]`
+2. `#[Defaults(value)]` attribute value
+3. `null` (if nullable) or `RequiredValueException`
+
+When both mechanisms define a value for the same property, `defaultValues()` takes precedence.
+
+### Explicit `null` Is Not Absent
+
+When a key is present in the input with a `null` value, it is treated as an intentional assignment — default values are **not** applied.
+
+```php
+readonly class Config extends DataTransferObject
+{
+    public ?string $theme;
+
+    public static function defaultValues(): array
+    {
+        return ['theme' => 'dark'];
+    }
+}
+
+Config::fromArray([]);                   // theme = 'dark' (key absent → default)
+Config::fromArray(['theme' => null]);    // theme = null   (explicit null → respected)
+Config::fromArray(['theme' => 'light']); // theme = 'light' (explicit value → used)
+```
+
+### Caching Behavior
+
+`ib-cacher` serializes cacheable default values (scalars, arrays) into the cache file. Non-serializable values (objects, Closures, resources) are excluded with a `[Notice]` warning and resolved at runtime via `defaultValues()` instead.
+
+### SVO Restriction
+
+`SingleValueObject` does not support default values. SVOs require an explicit value via `from()` by design. The `defaultValues()` method is sealed (`final`) on `SingleValueObject` and always returns an empty array.
+
+---
+
 ## Attributes
 
+### `#[Defaults]` - Property Default Value
+
+Declares a fallback value for a single property when the key is absent from input data. Constrained by PHP attribute syntax to scalar values, arrays, and class constants. For dynamic or object defaults, use `defaultValues()` instead.
+
+```php
+use ReallifeKip\ImmutableBase\Attributes\Defaults;
+
+readonly class CreateUserDTO extends DataTransferObject
+{
+    public string $name;
+    #[Defaults('member')]
+    public string $role;
+}
+CreateUserDTO::fromArray(['name' => 'Kip']); // role = 'member'
+```
+
 ### `#[ArrayOf]` - Typed Array
 
 Marks an array property as a typed collection of ImmutableBase instances. Each element is automatically instantiated from arrays, JSON strings, or pre-built objects. The target class must be a subclass of DTO, VO, or SVO.

README_TW.md

@@ -51,6 +51,31 @@ class Order extends DataTransferObject
 new Order('2026-01-01', '00:00:00', ...); // 無法直接接受外部傳入的陣列或 JSON 資料，且若未明確指定參數名稱則有順序錯亂的風險
 ```
 
+### 🛡️ 宣告式預設值
+```php
+// 🥳 ImmutableBase 透過 defaultValues() 或 #[Defaults] 自動填充缺少的屬性，優先順序清晰且能正確區分 null。
+readonly class CreateUserDTO extends DataTransferObject
+{
+    public string $name;
+    #[Defaults('member')]
+    public string $role;
+
+    public static function defaultValues(): array
+    {
+        return ['role' => 'admin']; // 優先於 #[Defaults]
+    }
+}
+CreateUserDTO::fromArray(['name' => 'Kip']); // role = 'admin'
+
+// 🫤 一般常見做法需要手動 null 合併或建構子預設值，無法集中宣告。
+class CreateUserDTO {
+    public function __construct(
+        public readonly string $name,
+        public readonly string $role = 'member', // 無法在子類中覆寫，除非重寫整個建構子
+    ){}
+}
+```
+
 ### 🔧靈活便利的深層更新
 支援直接指定物件深層路徑，拒絕俄羅斯套娃。
 ```php
@@ -355,8 +380,107 @@ $age1->equals($age3);  // false
 
 ---
 
+## 預設值
+
+輸入資料中缺少的屬性可透過兩種互補機制自動填充預設值。
+
+### `defaultValues()` — 動態預設值
+
+覆寫靜態方法，以屬性名稱為索引的關聯陣列宣告預設值，支援任何符合目標屬性型別的值，包含 ImmutableBase 的子物件及 Enum。
+
+```php
+readonly class CreateUserDTO extends DataTransferObject
+{
+    public string $name;
+    public string $role;
+    public string $locale;
+
+    public static function defaultValues(): array
+    {
+        return [
+            'role'   => 'member',
+            'locale' => 'en',
+        ];
+    }
+}
+CreateUserDTO::fromArray(['name' => 'Kip']); // role = 'member', locale = 'en'
+```
+
+### `#[Defaults]` — 標註預設值
+
+對個別屬性套用 `#[Defaults(value)]`，以行內常量表達式宣告預設值，受 PHP 標註語法限制，僅支援純量值、陣列及類別常數。
+
+```php
+use ReallifeKip\ImmutableBase\Attributes\Defaults;
+
+readonly class CreateUserDTO extends DataTransferObject
+{
+    public string $name;
+    #[Defaults('member')]
+    public string $role;
+    #[Defaults('en')]
+    public string $locale;
+}
+```
+
+### 解析優先順序
+
+當屬性的 key 不存在於輸入資料中時，預設值依以下順序解析：
+
+1. `defaultValues()[$propertyName]`
+2. `#[Defaults(value)]` 標註值
+3. `null`（若為 nullable）或 `RequiredValueException`
+
+當兩種機制同時為同一屬性定義預設值時，`defaultValues()` 優先。
+
+### 明確傳入 `null` 不等於缺少
+
+當 key 存在於輸入資料中但值為 `null` 時，視為使用者明確指定——**不會**套用預設值。
+
+```php
+readonly class Config extends DataTransferObject
+{
+    public ?string $theme;
+
+    public static function defaultValues(): array
+    {
+        return ['theme' => 'dark'];
+    }
+}
+
+Config::fromArray([]);                   // theme = 'dark'  （key 缺少 → 套用預設值）
+Config::fromArray(['theme' => null]);    // theme = null    （明確傳入 null → 維持 null）
+Config::fromArray(['theme' => 'light']); // theme = 'light' （明確傳入值 → 使用傳入值）
+```
+
+### 快取行為
+
+`ib-cacher` 會將可序列化的預設值（純量、陣列）寫入快取檔案，不可序列化的值（物件、Closure、resource）會以 `[Notice]` 警告排除，改為每次建構時透過 `defaultValues()` 在執行期解析。
+
+### SVO 限制
+
+`SingleValueObject` 不支援預設值，SVO 在設計上要求透過 `from()` 明確傳入值，`defaultValues()` 在 `SingleValueObject` 上以 `final` 封閉，始終回傳空陣列。
+
+---
+
 ## Attributes
 
+### `#[Defaults]` - 屬性預設值
+
+當 key 不存在於輸入資料中時，為單一屬性宣告預設值，受 PHP 標註語法限制，僅支援純量值、陣列及類別常數，若需動態或物件預設值，請改用 `defaultValues()`。
+
+```php
+use ReallifeKip\ImmutableBase\Attributes\Defaults;
+
+readonly class CreateUserDTO extends DataTransferObject
+{
+    public string $name;
+    #[Defaults('member')]
+    public string $role;
+}
+CreateUserDTO::fromArray(['name' => 'Kip']); // role = 'member'
+```
+
 ### `#[ArrayOf]` - 型別陣列
 
 將陣列屬性標記為 ImmutableBase 實例的型別集合。每個元素會自動從陣列、JSON 字串或已建構物件進行實例化，目標類必須是 DTO、VO 或 SVO 的子類。

src/Attributes/Defaults.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace ReallifeKip\ImmutableBase\Attributes;
+
+/**
+ * Declares a per-property fallback value used when the input payload
+ * does not contain that property key.
+ *
+ * Resolution precedence is:
+ *   1. Explicit input value
+ *   2. ImmutableBase::defaultValues()
+ *   3. #[Defaults(...)]
+ *
+ * This attribute is ignored when the key is explicitly present with `null`.
+ *
+ * Note: the attribute name is `#[Defaults]` (plural). `#[Default]` is not
+ * supported and will not be recognized.
+ */
+#[\Attribute(\Attribute::TARGET_PROPERTY)]
+final class Defaults
+{
+    /**
+     * @param mixed $value Fallback value to apply when the property key is absent.
+     */
+    public function __construct(
+        public mixed $value
+    ) {}
+}

src/BasicTrait.php

@@ -0,0 +1,43 @@
+<?php
+
+declare (strict_types = 1);
+
+namespace ReallifeKip\ImmutableBase;
+
+use ReflectionClass;
+use ReflectionProperty;
+
+trait BasicTrait
+{
+    /**
+     * Reads constructor arguments from a reflected PHP attribute.
+     *
+     * Used as a lightweight helper during metadata scanning to avoid
+     * repetitive boilerplate around `getAttributes()` + `getArguments()`.
+     *
+     * When `$getFirst` is true (default), returns only the first argument
+     * 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.
+     *
+     * @param ReflectionClass|ReflectionProperty $target Reflection target to inspect.
+     * @param class-string $name Fully-qualified attribute class name.
+     * @param bool $getFirst Whether to return only the first argument.
+     * @return mixed|null
+     */
+    public static function getAttributeArgument(ReflectionClass | ReflectionProperty $target, string $name, bool $getFirst = true)
+    {
+        if ($value = $target->getAttributes($name)) {
+            $value = $value[0];
+            if ($value = $value->getArguments()) {
+                return $getFirst ? $value[0] : $value;
+            }
+
+            return null;
+        }
+
+        return null;
+    }
+}