handle value objects with __toString()

Author: michalsn

system/Entity/Entity.php

@@ -385,6 +385,15 @@ private function normalizeValue(mixed $data): mixed
                 ];
             } else {
                 $objectData = get_object_vars($data);
+
+                // Fallback for value objects with __toString()
+                // when properties are not accessible
+                if ($objectData === [] && method_exists($data, '__toString')) {
+                    return [
+                        '__class'  => $data::class,
+                        '__string' => (string) $data,
+                    ];
+                }
             }
 
             return [

tests/system/Entity/EntityTest.php

@@ -2244,4 +2244,42 @@ public function testHasChangedWithTraversable(): void
         $entity->items = new ArrayObject([$obj3, $obj2]);
         $this->assertTrue($entity->hasChanged('items'));
     }
+
+    public function testHasChangedWithValueObjectsUsingToString(): void
+    {
+        // Define a value object class
+        $emailClass = new class () {
+            public static function create(string $email): object
+            {
+                return new class ($email) {
+                    public function __construct(private readonly string $email)
+                    {
+                    }
+
+                    public function __toString(): string
+                    {
+                        return $this->email;
+                    }
+                };
+            }
+        };
+
+        $entity = new class () extends Entity {
+            protected $attributes = [
+                'email' => null,
+            ];
+        };
+
+        $entity->email = $emailClass::create('[email protected]');
+        $entity->syncOriginal();
+
+        $this->assertFalse($entity->hasChanged('email'));
+
+        $entity->email = $emailClass::create('[email protected]');
+        $this->assertTrue($entity->hasChanged('email'));
+
+        $entity->syncOriginal();
+        $entity->email = $emailClass::create('[email protected]');
+        $this->assertFalse($entity->hasChanged('email'));
+    }
 }

user_guide_src/source/changelogs/v4.7.0.rst

@@ -54,6 +54,8 @@ for objects and arrays instead of shallow comparison. This means:
   including timezone information.
 - **Collections** (``Traversable``) such as ``ArrayObject`` and ``ArrayIterator`` are converted
   to arrays for comparison.
+- **Value objects** with ``__toString()`` method are compared by their string representation when
+  properties are not accessible (fallback for objects with private properties).
 - **Nested entities** (using ``toRawArray()``), ``JsonSerializable`` objects, and objects with
   ``toArray()`` methods are recursively normalized for accurate change detection.
 - **Scalar values** (strings, integers, floats, booleans, null) continue to use direct comparison

user_guide_src/source/models/entities.rst

@@ -382,5 +382,5 @@ Objects and Arrays
 
 For objects and arrays, the Entity JSON-encodes and normalizes the values for comparison. This means that modifications
 to nested structures, object properties, array elements, nested entities (using ``toRawArray()``), enums (``BackedEnum``
-and ``UnitEnum``), datetime objects (``DateTimeInterface``), collections (``Traversable``), and objects implementing
-``JsonSerializable`` or ``toArray()`` will be properly detected.
+and ``UnitEnum``), datetime objects (``DateTimeInterface``), collections (``Traversable``), value objects with
+``__toString()``, and objects implementing ``JsonSerializable`` or ``toArray()`` will be properly detected.