|
1 | 1 | # CHANGELOG |
2 | 2 |
|
| 3 | +## [v4.0.0] - 2026-03-01 |
| 4 | + |
| 5 | +### Breaking Changes |
| 6 | + |
| 7 | +- **Architecture: Attribute annotation replaced by class inheritance.** Objects are now defined by extending `DataTransferObject`, `ValueObject`, or `SingleValueObject` instead of annotating with `#[DataTransferObject]`, `#[ValueObject]`, or `#[Entity]`. |
| 8 | +- **Entity removed.** The `Entity` object type has been removed entirely. |
| 9 | +- **All properties must be `public`.** In v3, `ValueObject` and `Entity` properties were `private` with getter methods. All properties now require `public` visibility, enforced at scan time. Classes should be declared as `readonly class`, which handles immutability at the PHP level. |
| 10 | +- **Exception system rebuilt.** All v3 exceptions have been removed and replaced with a structured hierarchy under `ImmutableBaseException`, categorized into `LogicException` > `DefinitionException` (design errors) and `RuntimeException` > `InitializationException` (input type violations) / `ValidationException` (domain constraint violations). See [README](./README.md) for details. |
| 11 | +- **`object`, `iterable`, and non-IB/non-Enum class types forbidden.** Properties typed as `object`, `iterable`, or unsupported classes (e.g. `DateTime`, `Closure`) now throw `InvalidPropertyTypeException` at scan time. |
| 12 | + |
| 13 | +### Added |
| 14 | + |
| 15 | +- **`SingleValueObject` (SVO).** New object type for semantically meaningful single values. Provides `from()`, `__toString()`, `__invoke()`, and `jsonSerialize()`. Child classes can freely define the type of `$value` via interface + hooked property design. |
| 16 | +- **`equals()`.** Deep structural equality comparison for all ImmutableBase subclasses, with recursive comparison of nested objects and arrays. |
| 17 | +- **`#[Strict]` / `#[Lax]`.** Control whether undeclared input keys are rejected or accepted. |
| 18 | +- **`#[SkipOnNull]` / `#[KeepOnNull]`.** Control whether null-valued properties appear in `toArray()` / `toJson()` output. |
| 19 | +- **`#[Spec]`.** Attach a domain-specific validation message to VO/SVO, retrievable via `ValidationChainException::getSpec()`. |
| 20 | +- **`#[ValidateFromSelf]`.** Reverse the validation chain direction to bottom-up (default is top-down). |
| 21 | +- **Automatic validation chain.** VO and SVO automatically traverse the entire inheritance hierarchy during construction. Each class in the chain is invoked if it defines `validate(): bool`, but defining it is optional -- classes without it are simply skipped without breaking the chain. |
| 22 | +- **Hierarchical error path tracing.** Nested construction errors include the full property path in the exception message (e.g. `OrderDTO > $customer > $email > {error message}`). |
| 23 | +- **`ImmutableBase::strict()`.** Global strict mode. |
| 24 | +- **`ImmutableBase::debug()`.** Debug logging for redundant input keys. |
| 25 | +- **`ImmutableBase::loadCache()`.** Load pre-generated metadata cache to bypass runtime reflection. |
| 26 | +- **CLI: `ib-cacher`.** Metadata cache generator. Supports `--scan-dir` for targeted scanning and `--clear` for cache removal. |
| 27 | +- **CLI: `ib-writer`.** Documentation generator producing Mermaid class diagrams and Markdown property tables. |
| 28 | +- **Benchmark suite.** Dedicated benchmarks for `with()` and hydration covering flat scalar updates, dot-notation deep paths, bracket notation, chained calls, and batch operations. |
| 29 | + |
| 30 | +### Changed |
| 31 | + |
| 32 | +- **`with()` selective resolution.** Only changed properties are resolved; unchanged properties are carried over by reference, yielding a 44–68% performance improvement depending on nesting depth. |
| 33 | +- **`with()` deep path syntax now supports bracket notation** (`items[0].sku`) and custom separators, in addition to existing dot notation. |
| 34 | + |
| 35 | +### Deprecated |
| 36 | + |
| 37 | +- `#[DataTransferObject]` attribute — use `extends DataTransferObject`. |
| 38 | +- `#[ValueObject]` attribute — use `extends ValueObject`. |
| 39 | +- `#[Entity]` attribute — removed entirely. |
| 40 | + |
3 | 41 | ## [v3.1.3] - 2025-12-14 |
4 | 42 |
|
5 | 43 | ### Changed |
|
23 | 61 |
|
24 | 62 | - Prevented fatal error caused by invalid enum value assignment in property resolution. |
25 | 63 |
|
| 64 | +## [v3.2.0-alpha.1] - 2025-10-31 |
| 65 | + |
| 66 | +* Added HasValidate interface defining the validate method. |
| 67 | +* Introduced abstract classes SingleValueObject, extending ValueObject and implementing HasValidate. |
| 68 | +* Changed the visibility of the constructInitialize method to final protected. |
| 69 | +* Enhanced walkProperties for better stability by ensuring reflection reinitializes when missing. |
| 70 | +* Added toJson method to support JSON encoding. |
| 71 | + |
26 | 72 | ## [v3.1.0] - 2025-10-29 |
27 | 73 |
|
28 | 74 | ### ⚠️Note |
|
0 commit comments