v3.1.2

• Fixed a bug where Immutable Objects implementing a custom constructor skipped the normal initialization flow, causing toArray() to consistently throw errors. The initialization step is now guaranteed before property traversal, ensuring toArray() works correctly even with custom constructors.

v3.1.1

• Prevented fatal error caused by invalid enum value assignment in property resolution.

v3.2.0-alpha.1

• Added HasValidate interface defining the validate method.
• Introduced abstract classes SingleValueObject, extending ValueObject and implementing HasValidate.
• Changed the visibility of the constructInitialize method to final protected.
• Enhanced walkProperties for better stability by ensuring reflection reinitializes when missing.
• Added toJson method to support JSON encoding.

v3.1.0

⚠️Note

Starting from this release, the CHANGELOG will be maintained in English only.

自本版本後僅提供英文版 CHANGELOG，不再提供中文版內容。

Added

• Added fromArray() and fromJson() as new object construction entry points.
  Direct instantiation via new is no longer recommended.
• Added Traditional Chinese documentation README_TW.md, providing bilingual documentation and badges.
• Added class-based object APIs: ReallifeKip\ImmutableBase\Objects\{DataTransferObject, ValueObject, Entity}, allowing direct inheritance via extends.
• Added Attributes namespace: ReallifeKip\ImmutableBase\Attributes\{DataTransferObject, ValueObject, Entity, ArrayOf}.
• Added a set of granular exception classes (main ones listed):
  ImmutableBaseException, RuntimeException, LogicException,
  InvalidTypeException, InvalidJsonException,
  InvalidArrayException, InvalidArrayItemException, InvalidArrayValueException,
  InvalidArrayOfClassException, InvalidPropertyVisibilityException,
  AttributeException, InheritanceException, NonNullablePropertyException.
• with() and ArrayOf now support automatic instantiation of array elements into specified classes.
  They accept JSON strings, plain arrays, or existing instances as input.
• Completed PHPDoc for the toArrayOrValue() core method.

Changed

• Refactored and simplified parts of the core logic in src/ImmutableBase.php.
• Extracted Attributes and Objects into separate namespaces to improve project structure and code readability.
• with() now supports modifying nested properties that are themselves subclasses of ImmutableBase, without requiring re-instantiation.
• Updated composer.json to include relevant keywords for better package discovery.

Deprecated

• Direct instantiation (e.g., new Example()) will be removed in v4.0.0.
  Please use Example::fromArray() or Example::fromJson() instead.
• #[DataTransferObject], #[ValueObject], and #[Entity] will be deprecated in v4.0.0.
  Use the class-based API (Objects\*) going forward.

v3.0.3

• 修復 PHP 8.2 取得反射屬性名稱失敗 bug

v3.0.2

• 重構核心邏輯優化性能
• 提高代碼可讀性

---

Subject	Description	Δ Memory	Δ Time (↓ Faster)	Δ StdDev
benchConstructDeepAdvancedFromArray	Deep object construction from array	0.00%	−15.56%	−0.06%
benchConstructDeepAdvancedFromInstance	Deep object construction from instance	0.00%	−28.79%	−15.15%
benchToArrayDeepAdvanced	Deep to-array conversion	0.00%	−23.95%	+63.67%
benchWithDeepAdvanced	Deep “with()” cloning	0.00%	−22.72%	+8.97%
benchConstructBasicFromArray	Basic construction from array	0.00%	−20.00%	+1.87%
benchConstructAdvancedFromArray	Advanced construction from array	0.00%	−27.11%	+10.12%
benchConstructAdvancedFromInstance	Advanced construction from instance	0.00%	−20.67%	+27.55%
benchToArrayBasic	Basic to-array conversion	0.00%	−25.27%	+35.60%
benchToArrayAdvancedByArray	Advanced to-array (array-based)	0.00%	−25.02%	+23.27%
benchToArrayAdvancedByInstance	Advanced to-array (instance-based)	0.00%	−24.86%	−15.24%
benchWithBasic	Basic “with()” cloning	0.00%	−16.77%	−40.98%
benchWithAdvancedByArray	Advanced “with()” cloning (array)	0.00%	−14.77%	+46.32%
benchWithAdvancedByInstance	Advanced “with()” cloning (instance)	0.00%	−13.56%	−16.14%

v3.0.1

• 新增測試情境
• 簡化底層代碼

v3.0.0

⚠️ 重大變更

• 最低 PHP 支援版本提升從 8.0 提高至 8.1

🐞 修正

• 修復 with 寫入 null 時 valueDecide 仍返回原始值的問題

✨ 功能改進

• 移除 construct Enum 檢查邏輯，移至 valueDecide
• 優化 walkProperties 物件判斷條件
• 新增多層繼承屬性鏈巡覽與宣告層級過濾機制
• 擴展 Enum 支援度：現允許以 Enum 實例、key、value 方式傳入

📜 測試

• 新增 defaultBench，涵蓋 Basic、Advanced、Enum 相關性能場景
• 新增 phpbench 設定檔，統一自動載入與輸出格式
• 確立核心建構、序列化、巢狀結構與 with 操作效能基線
• 新增 Basic、Advanced、Initialized、Enum 等測試物件
• 建立完整測試（覆蓋率 100%），覆蓋所有核心行為與例外情境

🧰 開發與持續整合

• 新增 phpunit 自動化測試及產出報告 #範圍涵蓋 PHP 8.1 ~ 8.4
• 新增 FOSSA 相依與安全性檢測
• 新增 SONAR 品質檢測

🔧 重構

• 簡化 toArray 代碼結構
• 提升整體可讀性

v2.4.5

• 修復 toArray() 時將 0/null/false/'' 等值誤判為不存在並捨棄狀況。