feat: add toDatabase()/fromDatabase() to Entity

Author: kenjis

system/Entity/Entity.php

@@ -205,6 +205,8 @@ public function toArray(bool $onlyChanged = false, bool $cast = true, bool $recu
      *
      * @param bool $onlyChanged If true, only return values that have changed since object creation
      * @param bool $recursive   If true, inner entities will be cast as array as well.
+     *
+     * @deprecated 4.5.0 Use toDatabase() instead.
      */
     public function toRawArray(bool $onlyChanged = false, bool $recursive = false): array
     {
@@ -245,6 +247,71 @@ public function toRawArray(bool $onlyChanged = false, bool $recursive = false):
         return $return;
     }
 
+    /**
+     * Returns the values for database of the current attributes.
+     *
+     * @param bool $onlyChanged If true, only return values that have changed since object creation
+     * @param bool $recursive   If true, inner entities will be cast as array as well.
+     */
+    public function toDatabase(bool $onlyChanged = false, bool $recursive = false): array
+    {
+        $return = [];
+
+        if (! $onlyChanged) {
+            $data = $this->attributes;
+
+            // Cast values
+            if ($this->_cast) {
+                foreach (array_keys($this->casts) as $field) {
+                    if (isset($data[$field])) {
+                        $data[$field] = $this->castAs($data[$field], $field, 'toDatabase');
+                    }
+                }
+            }
+
+            if ($recursive) {
+                return array_map(static function ($value) use ($onlyChanged, $recursive) {
+                    if ($value instanceof self) {
+                        $value = $value->toDatabase($onlyChanged, $recursive);
+                    } elseif (is_callable([$value, 'toDatabase'])) {
+                        // @TODO Should define Interface or Class.
+                        $value = $value->toDatabase();
+                    }
+
+                    return $value;
+                }, $data);
+            }
+
+            return $data;
+        }
+
+        foreach ($this->attributes as $key => $value) {
+            if (! $this->hasChanged($key)) {
+                continue;
+            }
+
+            // Cast values
+            if ($this->_cast) {
+                if (isset($this->casts[$key])) {
+                    $value = $this->castAs($value, $key, 'toDatabase');
+                }
+            }
+
+            if ($recursive) {
+                if ($value instanceof self) {
+                    $value = $value->toDatabase($onlyChanged, $recursive);
+                } elseif (is_callable([$value, 'toDatabase'])) {
+                    // @TODO Should define Interface or Class.
+                    $value = $value->toDatabase();
+                }
+            }
+
+            $return[$key] = $value;
+        }
+
+        return $return;
+    }
+
     /**
      * Ensures our "original" values match the current values.
      *
@@ -290,6 +357,8 @@ public function hasChanged(?string $key = null): bool
      * Set raw data array without any mutations
      *
      * @return $this
+     *
+     * @deprecated 4.5.0 No longer used. `fromDatabase()` is used.
      */
     public function injectRawData(array $data)
     {
@@ -300,6 +369,35 @@ public function injectRawData(array $data)
         return $this;
     }
 
+    /**
+     * Set data from database
+     *
+     * @return $this
+     */
+    public function fromDatabase(array $data)
+    {
+        // Mutate dates
+        foreach ($this->dates as $field) {
+            if (isset($data[$field])) {
+                $data[$field] = $this->mutateDate($data[$field]);
+            }
+        }
+
+        // Cast values
+        if ($this->_cast) {
+            foreach (array_keys($this->casts) as $field) {
+                if (isset($data[$field])) {
+                    $data[$field] = $this->castAs($data[$field], $field, 'fromDatabase');
+                }
+            }
+        }
+
+        $this->attributes = $data;
+        $this->syncOriginal();
+
+        return $this;
+    }
+
     /**
      * Set raw data array without any mutations
      *
@@ -353,7 +451,8 @@ protected function mutateDate($value)
      *
      * @param bool|float|int|string|null $value     Attribute value
      * @param string                     $attribute Attribute name
-     * @param string                     $method    Allowed to "get" and "set"
+     * @param string                     $method    Method name to run in the cast handler
+     * @phpstan-param 'get'|'set'|'toDatabase'|'fromDatabase' $method
      *
      * @return array|bool|float|int|object|string|null
      *
@@ -383,7 +482,7 @@ protected function castAs($value, string $attribute, string $method = 'get')
         // json-array type, we transform the required one.
         $type = $type === 'json-array' ? 'json[array]' : $type;
 
-        if (! in_array($method, ['get', 'set'], true)) {
+        if (! in_array($method, ['get', 'set', 'toDatabase', 'fromDatabase'], true)) {
             throw CastException::forInvalidMethod($method);
         }