Expanded element export & custom date fields

CHANGELOG-WIP.md

@@ -5,7 +5,10 @@
 
 ### Extensibility
 - Global nav items and breadcrumbs can now have `aria-label` attributes via an `ariaLabel` property.
+- Added `craft\base\ElementInterface::getSerializedFieldValuesForDb()`.
+- Added `craft\base\FieldInterface::serializeValueForDb()`.
 
 ### System
 - The `changedattributes` and `changedfields` tables are now cleaned up during garbage collection. ([#16531](https://github.com/craftcms/cms/pull/16531))
 - The `resourcepaths` table is now truncated when clearing control panel resources, via the Caches utility or the `clear-caches/cp-resources` command. ([#16514](https://github.com/craftcms/cms/issues/16514))
+- Date values for custom fields are now represented as ISO-8601 date strings (with time zones) within element exports. ([#16629](https://github.com/craftcms/cms/pull/16629))

src/base/Element.php

@@ -74,6 +74,7 @@
 use craft\validators\SlugValidator;
 use craft\validators\StringValidator;
 use craft\web\UploadedFile;
+use DateTime;
 use Illuminate\Support\Collection;
 use Throwable;
 use Traversable;
@@ -2538,7 +2539,7 @@ public function afterValidate(): void
 
                 if ($field::hasContentColumn()) {
                     $columnType = $field->getContentColumnType();
-                    $value = $field->serializeValue($this->getFieldValue($field->handle), $this);
+                    $value = $field->serializeValueForDb($this->getFieldValue($field->handle), $this);
 
                     if (is_array($columnType)) {
                         foreach ($columnType as $key => $type) {
@@ -4189,6 +4190,23 @@ public function getSerializedFieldValues(?array $fieldHandles = null): array
         return $serializedValues;
     }
 
+    /**
+     * @inheritdoc
+     */
+    public function getSerializedFieldValuesForDb(?array $fieldHandles = null): array
+    {
+        $serializedValues = [];
+
+        foreach ($this->fieldLayoutFields() as $field) {
+            if ($fieldHandles === null || in_array($field->handle, $fieldHandles, true)) {
+                $value = $this->getFieldValue($field->handle);
+                $serializedValues[$field->handle] = $field->serializeValueForDb($value, $this);
+            }
+        }
+
+        return $serializedValues;
+    }
+
     /**
      * @inheritdoc
      */

src/base/ElementInterface.php

@@ -1379,6 +1379,18 @@ public function getFieldValues(?array $fieldHandles = null): array;
      */
     public function getSerializedFieldValues(?array $fieldHandles = null): array;
 
+    /**
+     * Returns an array of the element’s serialized custom field values, indexed by their handles,
+     * for database storage.
+     *
+     * @param string[]|null $fieldHandles The list of field handles whose values
+     * need to be returned. Defaults to null, meaning all fields’ values will be
+     * returned. If it is an array, only the fields in the array will be returned.
+     * @return array
+     * @since 4.15.0
+     */
+    public function getSerializedFieldValuesForDb(?array $fieldHandles = null): array;
+
     /**
      * Sets the element’s custom field values.
      *

src/base/Field.php

@@ -643,12 +643,25 @@ public function serializeValue(mixed $value, ?ElementInterface $element = null):
 
         // Only DateTime objects and ISO-8601 strings should automatically be detected as dates
         if ($value instanceof DateTime || DateTimeHelper::isIso8601($value)) {
-            return Db::prepareDateForDb($value);
+            return DateTimeHelper::toIso8601($value);
         }
 
         return $value;
     }
 
+    /**
+     * @inheritdoc
+     */
+    public function serializeValueForDb(mixed $value, ?ElementInterface $element = null): mixed
+    {
+        // Dates should be stored in UTC w/o the time zone
+        if ($value instanceof DateTime || DateTimeHelper::isIso8601($value)) {
+            return Db::prepareDateForDb($value);
+        }
+
+        return $this->serializeValue($value, $element);
+    }
+
     /**
      * @inheritdoc
      */

src/base/FieldInterface.php

@@ -393,9 +393,8 @@ public function normalizeValue(mixed $value, ?ElementInterface $element = null):
     public function normalizeValueFromRequest(mixed $value, ?ElementInterface $element = null): mixed;
 
     /**
-     * Prepares the field’s value to be stored somewhere, like the content table.
+     * Serializes the field’s value into a transportable format (either a scalar value or array of scalar values).
      *
-     * Data types that are JSON-encodable are safe (arrays, integers, strings, booleans, etc).
      * Whatever this returns should be something [[normalizeValue()]] can handle.
      *
      * @param mixed $value The raw field value
@@ -404,6 +403,19 @@ public function normalizeValueFromRequest(mixed $value, ?ElementInterface $eleme
      */
     public function serializeValue(mixed $value, ?ElementInterface $element = null): mixed;
 
+    /**
+     * Serializes the field’s value into a transportable format (either a scalar value or array of scalar values),
+     * for database storage.
+     *
+     * Whatever this returns should be something [[normalizeValue()]] can handle.
+     *
+     * @param mixed $value
+     * @param ElementInterface|null $element
+     * @return mixed
+     * @since 4.15.0
+     */
+    public function serializeValueForDb(mixed $value, ?ElementInterface $element = null): mixed;
+
     /**
      * Copies the field’s value from one element to another.
      *

src/fields/Date.php

@@ -394,7 +394,7 @@ public function normalizeValue(mixed $value, ?ElementInterface $element = null):
     /**
      * @inheritdoc
      */
-    public function serializeValue(mixed $value, ?ElementInterface $element = null): mixed
+    public function serializeValueForDb(mixed $value, ?ElementInterface $element = null): mixed
     {
         if (!$value) {
             return null;

src/fields/Matrix.php

@@ -582,6 +582,28 @@ public function serializeValue(mixed $value, ?ElementInterface $element = null):
         return $serialized;
     }
 
+    /**
+     * @inheritdoc
+     */
+    public function serializeValueForDb(mixed $value, ?ElementInterface $element = null): mixed
+    {
+        /** @var MatrixBlockQuery|Collection $value */
+        $serialized = [];
+        $new = 0;
+
+        foreach ($value->all() as $block) {
+            $blockId = $block->id ?? 'new' . ++$new;
+            $serialized[$blockId] = [
+                'type' => $block->getType()->handle,
+                'enabled' => $block->enabled,
+                'collapsed' => $block->collapsed,
+                'fields' => $block->getSerializedFieldValuesForDb(),
+            ];
+        }
+
+        return $serialized;
+    }
+
     /**
      * @inheritdoc
      */

src/fields/Table.php

@@ -532,6 +532,39 @@ public function serializeValue(mixed $value, ?ElementInterface $element = null):
         return $serialized;
     }
 
+    /**
+     * @inheritdoc
+     */
+    public function serializeValueForDb(mixed $value, ?ElementInterface $element = null): mixed
+    {
+        if (!is_array($value) || empty($this->columns)) {
+            return null;
+        }
+
+        $serialized = [];
+        $supportsMb4 = Craft::$app->getDb()->getSupportsMb4();
+
+        foreach ($value as $row) {
+            $serializedRow = [];
+            foreach ($this->columns as $colId => $column) {
+                if ($column['type'] === 'heading') {
+                    continue;
+                }
+
+                $value = $row[$colId];
+
+                if (is_string($value) && !$supportsMb4) {
+                    $value = StringHelper::emojiToShortcodes(StringHelper::escapeShortcodes($value));
+                }
+
+                $serializedRow[$colId] = parent::serializeValueForDb($value ?? null);
+            }
+            $serialized[] = $serializedRow;
+        }
+
+        return $serialized;
+    }
+
     /**
      * @inheritdoc
      */

src/services/Content.php

@@ -93,7 +93,7 @@ public function saveContent(ElementInterface $element): bool
                     (!$element->contentId || $element->isFieldDirty($field->handle)) &&
                     $field::hasContentColumn()
                 ) {
-                    $serializedFieldValues[$field->uid] = $field->serializeValue($element->getFieldValue($field->handle), $element);
+                    $serializedFieldValues[$field->uid] = $field->serializeValueForDb($element->getFieldValue($field->handle), $element);
                     $fields[$field->uid] = $field;
                 }
             }