fix: Entity::hasChanged() returns wrong result to mapped property

system/Entity/Cast/BaseCast.php

@@ -19,10 +19,10 @@ abstract class BaseCast implements CastInterface
     /**
      * Get
      *
-     * @param mixed $value  Data
-     * @param array $params Additional param
+     * @param array|bool|float|int|object|string|null $value  Data
+     * @param array                                   $params Additional param
      *
-     * @return mixed
+     * @return array|bool|float|int|object|string|null
      */
     public static function get($value, array $params = [])
     {
@@ -32,10 +32,10 @@ public static function get($value, array $params = [])
     /**
      * Set
      *
-     * @param mixed $value  Data
-     * @param array $params Additional param
+     * @param array|bool|float|int|object|string|null $value  Data
+     * @param array                                   $params Additional param
      *
-     * @return mixed
+     * @return array|bool|float|int|object|string|null
      */
     public static function set($value, array $params = [])
     {

system/Entity/Cast/CastInterface.php

@@ -19,20 +19,20 @@ interface CastInterface
     /**
      * Get
      *
-     * @param mixed $value  Data
-     * @param array $params Additional param
+     * @param array|bool|float|int|object|string|null $value  Data
+     * @param array                                   $params Additional param
      *
-     * @return mixed
+     * @return array|bool|float|int|object|string|null
      */
     public static function get($value, array $params = []);
 
     /**
      * Set
      *
-     * @param mixed $value  Data
-     * @param array $params Additional param
+     * @param array|bool|float|int|object|string|null $value  Data
+     * @param array                                   $params Additional param
      *
-     * @return mixed
+     * @return array|bool|float|int|object|string|null
      */
     public static function set($value, array $params = []);
 }

system/Entity/Cast/DatetimeCast.php

@@ -24,6 +24,8 @@ class DatetimeCast extends BaseCast
      * {@inheritDoc}
      *
      * @throws Exception
+     *
+     * @return Time
      */
     public static function get($value, array $params = [])
     {

system/Entity/Entity.php

@@ -146,7 +146,7 @@ public function fill(?array $data = null)
      * __get() magic method so will have any casts, etc applied to them.
      *
      * @param bool $onlyChanged If true, only return values that have changed since object creation
-     * @param bool $cast        If true, properties will be casted.
+     * @param bool $cast        If true, properties will be cast.
      * @param bool $recursive   If true, inner entities will be casted as array as well.
      */
     public function toArray(bool $onlyChanged = false, bool $cast = true, bool $recursive = false): array
@@ -256,6 +256,8 @@ public function hasChanged(?string $key = null): bool
             return $this->original !== $this->attributes;
         }
 
+        $key = $this->mapProperty($key);
+
         // Key doesn't exist in either
         if (! array_key_exists($key, $this->original) && ! array_key_exists($key, $this->attributes)) {
             return false;
@@ -287,7 +289,7 @@ public function setAttributes(array $data)
      * Checks the datamap to see if this property name is being mapped,
      * and returns the db column name, if any, or the original property name.
      *
-     * @return string
+     * @return string db column name
      */
     protected function mapProperty(string $key)
     {
@@ -480,7 +482,7 @@ public function __get(string $key)
         // Convert to CamelCase for the method
         $method = 'get' . str_replace(' ', '', ucwords(str_replace(['-', '_'], ' ', $key)));
 
-        // if a set* method exists for this key,
+        // if a get* method exists for this key,
         // use that method to insert this value.
         if (method_exists($this, $method)) {
             $result = $this->{$method}();

tests/system/Entity/EntityTest.php

@@ -929,6 +929,24 @@ public function testHasChangedNoChange()
         $this->assertFalse($entity->hasChanged('default'));
     }
 
+    public function testHasChangedMappedNoChange()
+    {
+        $entity = $this->getEntity();
+
+        $entity->createdAt = null;
+
+        $this->assertFalse($entity->hasChanged('createdAt'));
+    }
+
+    public function testHasChangedMappedChanged()
+    {
+        $entity = $this->getEntity();
+
+        $entity->createdAt = '2022-11-11 11:11:11';
+
+        $this->assertTrue($entity->hasChanged('createdAt'));
+    }
+
     public function testHasChangedWholeEntity()
     {
         $entity = $this->getEntity();

user_guide_src/source/models/entities.rst

@@ -144,9 +144,9 @@ As an example, imagine you have the simplified User Entity that is used througho
 .. literalinclude:: entities/008.php
 
 Your boss comes to you and says that no one uses usernames anymore, so you're switching to just use emails for login.
-But they do want to personalize the application a bit, so they want you to change the name field to represent a user's
+But they do want to personalize the application a bit, so they want you to change the ``name`` field to represent a user's
 full name now, not their username like it does currently. To keep things tidy and ensure things continue making sense
-in the database you whip up a migration to rename the `name` field to `full_name` for clarity.
+in the database you whip up a migration to rename the ``name`` field to ``full_name`` for clarity.
 
 Ignoring how contrived this example is, we now have two choices on how to fix the User class. We could modify the class
 property from ``$name`` to ``$full_name``, but that would require changes throughout the application. Instead, we can
@@ -164,6 +164,10 @@ through the original ``$user->full_name``, also, as this is needed for the model
 to the database. However, ``unset()`` and ``isset()`` only work on the mapped property, ``$user->name``, not on the database column name,
 ``$user->full_name``.
 
+.. note:: When you use Data Mapping, you must define ``set*()`` and ``get*()`` method
+    for the database column name. In this example, you must define ``setFullName()`` and
+    ``getFullName()``.
+
 Mutators
 ========
 

user_guide_src/source/models/entities/009.php

@@ -8,14 +8,15 @@ class User extends Entity
 {
     protected $attributes = [
         'id'         => null,
-        'full_name'  => null, // In the $attributes, the key is the column name
+        'full_name'  => null, // In the $attributes, the key is the db column name
         'email'      => null,
         'password'   => null,
         'created_at' => null,
         'updated_at' => null,
     ];
 
     protected $datamap = [
+        // property_name => db_column_name
         'name' => 'full_name',
     ];
 }