[fix] core

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

Author: ReallifeKip

CHANGELOG.md

@@ -1,43 +1,49 @@
 # CHANGELOG
 
+## [v3.1.1] - 2025-11-05
+
+### Fixed
+
+- Prevented fatal error caused by invalid enum value assignment in property resolution.
+
 ## [v3.1.0] - 2025-10-29
 
-###  ⚠️Note
+### ⚠️Note
+
 > Starting from this release, the CHANGELOG will be maintained in English only.<br>
 > 自本版本後僅提供英文版 CHANGELOG，不再提供中文版內容。
 
 ### Added
 
-* Added `fromArray()` and `fromJson()` as new object construction entry points.
+- 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):
+- 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.
+- `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.
+- 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.
+- 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**.
+- 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**.
+- `#[DataTransferObject]`, `#[ValueObject]`, and `#[Entity]` **will be deprecated in v4.0.0**.
   Use the **class-based API** (`Objects\*`) going forward.
 
-
 ## [v3.0.3] - 2025-10-17
 
 - 修復 PHP 8.2 取得反射屬性名稱失敗 bug

src/ImmutableBase.php

@@ -568,7 +568,9 @@ private function unionTypeDecide(ReflectionUnionType $type, mixed $value)
      * - If the value is an array and the target type extends {@see ImmutableBase}, a new instance is constructed.
      * - If the value is already an object, it is returned as-is.
      * - If the type allows null and the value is null, null is returned.
-     * - If the type represents an enum, the method attempts to resolve it via `::tryFrom()` or constant lookup.
+     * - If the type represents an enum, the method first attempts to resolve it by matching the case name
+     *   via constant lookup (e.g. `MyEnum::CASE`), and if that fails and the enum implements {@see BackedEnum},
+     *   it will attempt resolution via `::tryFrom($value)`.
      *
      * Any mismatch between the provided value and the expected class or enum type will result
      * in an {@see InvalidTypeException}.
@@ -588,11 +590,13 @@ private function namedTypeDecide(ReflectionNamedType $type, mixed $value)
             is_object($value) => $value,
             $this->validNullValue($type, $value) => null,
             is_string($value) && enum_exists($class) => (function () use ($class, $value) {
-                try {
-                    return $class::tryFrom($value) ?? constant("$class::$value");
-                } catch (Throwable) {
-                    throw new InvalidTypeException("is $class and does not include '$value'.");
+                if (defined($case = "$class::$value")) {
+                    return constant($case);
                 }
+                if (is_subclass_of($class, \BackedEnum::class) && $case = $class::tryFrom($value)) {
+                    return $case;
+                }
+                throw new InvalidTypeException("is $class and does not include '$value'.");
             })(),
             default => throw new InvalidTypeException(
                 "expected types: $class, got " .