[feat] object/validation

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

Author: Administrator

CHANGELOG.md

@@ -1,5 +1,13 @@
 # CHANGELOG
 
+## [v3.2.0-alpha.1] - 2025-10-31
+
+* 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] - 2025-10-29
 
 ###  ⚠️Note

README.md

@@ -123,6 +123,18 @@ $user = User::fromArray([
 $user = Money::fromJson('{"value": 1000}');
 ```
 
+### Exporting — `toArray()`, `toJson()`
+
+```php
+// ['name' => 'Kip', 'age' => 18]
+$user->toArray();
+```
+
+```php
+// {"name":"Kip","age":18}
+$user->toJson();
+```
+
 ### Updating — `with()`
 
 > ⚠️ This does **not** mutate the original object. A new instance is returned with partial updates, by design. For the underlying rationale, see [Objects and references](https://www.php.net/manual/en/language.oop5.references.php).<br>
@@ -143,11 +155,25 @@ $userWithNewAddress = $user->with([
 ]);
 ```
 
-### Exporting — `toArray()`
+## API for SingleValueObject only
 
+### Constructing - `from()`
 ```php
-// ['name' => 'Kip', 'age' => 18]
-$user->toArray();
+$email = Gmail::from('[email protected]');
+```
+
+### Comparing - `equals()`
+Compares the current object with another instance of the same class.
+If the provided value is not an instance of the same class, an exception will be thrown.
+This method returns true only when both objects contain an identical $value.
+```php
+$email2 = Gmail::from('[email protected]');
+$email3 = Gmail::from('[email protected]');
+$email4 = Hotmail::from('[email protected]');
+
+$email->equals($email2); // true
+$email->equals($email3); // false
+$email->equals($email4); // Exception thrown
 ```
 
 ## Architecture: Attributes
@@ -289,6 +315,51 @@ class Money extends ValueObject
 }
 ```
 
+### `SingleValueObject`
+
+Designed **exclusively for single-value inheritance** — do **not** extend it for multi-property value objects.
+Classes extending `SingleValueObject` are **required** to declare exactly one property:
+`private readonly {type} $value`.
+
+```php
+use ReallifeKip\ImmutableBase\Objects\SingleValueObject;
+
+class Email extends SingleValueObject
+{
+    protected readonly string $value;
+    public function validate(): bool
+    {
+        return str_contains($this->value, '@');
+    }
+}
+
+class Gmail extends Email
+{
+    public function validate(): bool
+    {
+        return str_contains($this->value, 'gmail.com');
+    }
+}
+```
+
+> The `validate()` method defines validation rules automatically executed during initialization.
+> If the class hierarchy includes multiple levels of inheritance, all `validate()` methods in the chain will be called upward until every one passes before construction completes.
+
+### Output
+
+```php
+$email = Email::from('[email protected]');
+
+// [email protected] ⚠️ Works only if $value is a string
+echo $email;
+// [email protected]
+echo $email();
+// [email protected]
+echo $email->value;
+```
+
+All of the above expressions produce the same result.
+
 ## Notes
 
 1. **Property types** must be explicitly declared; `mixed` is not allowed.

README_TW.md

@@ -109,7 +109,7 @@ final class Money extends ValueObject
 
 ## API
 
-### 建構物件 - fromArray(), fromJson()
+### 建構物件 - `fromArray()`, `fromJson()`
 
 > 傳入參數掃描時，若發現參數內容非物件宣告的屬性，該參數將被自動忽略而不會存在於返回的實例。
 
@@ -124,7 +124,19 @@ $user = User::fromArray([
 $user = Money::fromJson('{"value": 1000}');
 ```
 
-### 修改屬性 - with()
+### 輸出陣列 - `toArray()` , `toJson()`
+
+```php
+// ['name' => 'Kip', 'age' => 18]
+$user->toArray();
+```
+
+```php
+// {"name":"Kip","age":18}
+$user->toJson();
+```
+
+### 修改屬性 - `with()`
 
 > ⚠️ 注意：非修改原始物件，而是基於原始物件進行部分修改後返回 `新實例`，採用此設計的原因及底層原理請參考 [Objects and references](https://www.php.net/manual/en/language.oop5.references.php)。<br>
 > ⚠️ 注意：當 with() 指定修改 #[ArrayOf] 屬性時會直接重建陣列。<br>
@@ -144,11 +156,26 @@ $userWithNewAddress = $user->with([
 ]);
 ```
 
-### 輸出陣列 - toArray()
+## 僅適用於 SingleValueObject 的 API
+
+### 建構物件 - `from()`
+
+```php
+$email = Gmail::from('[email protected]');
+```
+
+### 比較方法 - `equals()`
+
+比較當前物件與**相同類別**的另一個實例，若傳入的值不是相同類別的實例將會拋出例外，當兩個物件內部的 `$value` 值相同時，才會回傳 `true`。
 
 ```php
-// ['name' => 'Kip', 'age' => 18]
-$user->toArray();
+$email2 = Gmail::from('[email protected]');
+$email3 = Gmail::from('[email protected]');
+$email4 = Hotmail::from('[email protected]');
+
+$email->equals($email2); // true
+$email->equals($email3); // false
+$email->equals($email4); // 拋出例外
 ```
 
 ## 架構模式標註
@@ -291,6 +318,51 @@ class Money extends ValueObject
 }
 ```
 
+### `SingleValueObject`
+
+專為**單一值（single-value）繼承**而設計 —— **不要**在此基礎上建立多屬性的 Value Object。
+
+繼承 `SingleValueObject` 的類別**必須**宣告：`private readonly {type} $value`。
+
+```php
+use ReallifeKip\ImmutableBase\Objects\SingleValueObject;
+
+class Email extends SingleValueObject
+{
+    protected readonly string $value;
+    public function validate(): bool
+    {
+        return str_contains($this->value, '@');
+    }
+}
+
+class Gmail extends Email
+{
+    public function validate(): bool
+    {
+        return str_contains($this->value, 'gmail.com');
+    }
+}
+```
+
+> `validate()` 方法用於定義驗證規則，會在初始化時自動執行。
+> 若類別存在多層繼承關係，所有父類與子類中的 `validate()` 都會依序被呼叫，直到全部驗證通過後，物件才會完成建構。
+
+### 輸出結果
+
+```php
+$email = Email::from('[email protected]');
+
+// [email protected] ⚠️ 透過 __toString() 包裝，僅 $value 宣告 type 為字串時可用
+echo $email;
+// [email protected]
+echo $email();
+// [email protected]
+echo $email->value;
+```
+
+以上幾種寫法的輸出結果都相同。
+
 ## ⚠️ 注意事項
 
 1. **屬性型別**：必須宣告屬性型別，且不允許為 mixed，需明確宣告。

src/ImmutableBase.php

@@ -10,6 +10,8 @@
 use ReflectionProperty;
 use ReflectionNamedType;
 use ReflectionUnionType;
+use ReallifeKip\ImmutableBase\Objects\ValueObject;
+use ReallifeKip\ImmutableBase\Objects\SingleValueObject;
 use ReallifeKip\ImmutableBase\Exceptions\AttributeException;
 use ReallifeKip\ImmutableBase\Exceptions\InvalidJsonException;
 use ReallifeKip\ImmutableBase\Exceptions\InvalidTypeException;
@@ -292,7 +294,7 @@ private static function extendsValidate()
      *
      * @throws AttributeException When the subclass does not extend any supported immutable base type.
      */
-    private function constructInitialize()
+    final protected function constructInitialize()
     {
         $attrNamespace = "$this->namespace\\Attributes";
         $this->ref ??= self::getReflection($this);
@@ -361,8 +363,15 @@ private static function getReflection(object $obj): ReflectionClass
     private function walkProperties(callable $callback): void
     {
         $properties = [];
-        for ($c = $this->ref; $c && $c->name !== self::class; $c = $c->getParentClass()) {
-            array_unshift($properties, ...$c->getProperties());
+        if (!$this->ref) {
+            $this->ref = new ReflectionClass($this);
+        }
+        $c = $this->ref;
+        while ($c) {
+            if ($c->name !== self::class) {
+                array_unshift($properties, ...$c->getProperties());
+            }
+            $c = $c->getParentClass();
         }
         foreach ($properties as $p) {
             /** @var ReflectionProperty $p */
@@ -457,12 +466,22 @@ final public function toArray(): array
     {
         $properties = [];
         $this->walkProperties(function (ReflectionProperty $property) use (&$properties) {
-            $properties[$property->name] = is_array($value = $property->getValue($this)) ?
-                array_map([$this, 'toArrayOrValue'], $value) :
-                $this->toArrayOrValue($value);
+            $type = $property->getType()->getName();
+            $value = $property->getValue($this);
+            if (is_subclass_of($type, SingleValueObject::class)) {
+                $properties[$property->name] = $value();
+            } else {
+                $properties[$property->name] = is_array($value) ?
+                    array_map([$this, 'toArrayOrValue'], $value) :
+                    $this->toArrayOrValue($value);
+            }
         });
         return $properties;
     }
+    final public function toJson()
+    {
+        return json_encode($this->toArray());
+    }
     /**
      * Converts an object to an array if possible, otherwise returns the original value.
      *
@@ -482,6 +501,10 @@ private function toArrayOrValue(mixed $value)
         if (is_object($value)) {
             if (method_exists($value, 'toArray')) {
                 return $value->toArray();
+            } elseif (property_exists($value, 'value')) {
+                return $value->value;
+            } elseif (property_exists($value, 'name')) {
+                return $value->name;
             }
         }
         return $value;
@@ -587,19 +610,27 @@ private function namedTypeDecide(ReflectionNamedType $type, mixed $value)
             is_array($value) && is_subclass_of($class, self::class) => $class::fromArray($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'.");
-                }
-            })(),
+            $this->isBuiltin($value) => $this->singleValueDecide($class, $value),
             default => throw new InvalidTypeException(
                 "expected types: $class, got " .
                 (is_object($value) ? $value::class : gettype($value)) . '.'
             )
         };
     }
+    private function singleValueDecide($class, $value)
+    {
+        if (enum_exists($class)) {
+            try {
+                return (is_subclass_of($class, \BackedEnum::class) && $case = $class::tryFrom($value)) ? $case : constant("$class::$value");
+            } catch (Throwable) {
+                throw new InvalidTypeException("is $class and does not include '$value'.");
+            }
+        } elseif (is_subclass_of($class, ValueObject::class)) {
+            if (is_subclass_of($class, SingleValueObject::class)) {
+                return $class::from($value);
+            }
+        }
+    }
     /**
      * Determines whether the given value is a valid null according to the property's type definition.
      *
@@ -632,4 +663,11 @@ private function builtinTypeValidate(mixed $value, string $type): bool
             default             => false,
         };
     }
+    private function isBuiltin(mixed $value)
+    {
+        return in_array(gettype($value), [
+            'integer', 'double', 'string', 'boolean',
+            'array', 'object', 'resource', 'NULL'
+        ], true);
+    }
 }

src/Interfaces/HasValidate.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace ReallifeKip\ImmutableBase\Interfaces;
+
+interface HasValidate
+{
+    public function validate(): bool;
+}