Merge pull request #87 from Crell/mixed-serialize

Allow serialization/unserialization of objects on mixed properties

Author: Crell

CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to `Serde` will be documented in this file.
 
 Updates should follow the [Keep a CHANGELOG](http://keepachangelog.com/) principles.
 
+## 1.4.0 - DATE
+
+### Added
+- A new `MixedField` type field is available for use on `mixed` properties. If specified, it allows specifying a preferred object type that an array-ish value will be cast into when deserializing.  If the object deserialiation fails, the whole deserialization will fail.
+
+### Deprecated
+- Nothing
+
+### Fixed
+- Serializing an object that is assigned to a `mixed` field will no longer generate a circular reference error.
+
+### Removed
+- Nothing
+
+### Security
+- Nothing
+
 ## 1.3.2 - 2024-12-06
 
 ### Added

README.md

@@ -696,6 +696,27 @@ The serialized integer should be read as "this many seconds since the epoc" or "
 
 Note that the permissible range of milliseconds and microseconds is considerably smaller than that for seconds, since there is a limit on the size of an integer that we can represent.  For timestamps in the early 21st century there should be no issue, but trying to record the microseconds since the epoc for the setting of Dune (somewhere in the 10,000s) won't work.
 
+### Mixed values
+
+`mixed` values pose an interesting challenge, as their data type is by definition not specified.
+
+On serialization, Serde will make a good faith effort to derive the type to serialize to from the value itself.  So if a `mixed` property has a value of `"beep"`, it will try to serialize as a string.  If it has a value `[1, 2, 3]`, it will try to serialize as an array.
+
+On deserialization, primitive types (`int`, `float`, `string`) will be read successfully and written to the property.  If no additional information is provided, then sequences and dictionaries will also be read into the property as an `array`, but objects are not supported.  (They'll be treated like a dictionary.)
+
+Alternatively, you may specify the field as a `#[MixedField(Point::class)]`, which has one required argument, `suggestedType`.  If that is specified, any incoming array-ish value will be deserialized to the specified class.  If the value is not compatible with that class, an exception will be thrown.  That means it is not possible to support both array deserialization and object deserialization at the same time.
+
+```php
+class Message
+{
+    public string $message;
+    #[MixedField(SomeClass::class)]
+    public mixed $result;
+}
+```
+
+If you are only ever serializing an object with a `mixed` property, these concerns should not apply and no additional effort should be required.
+
 ### Generators, Iterables, and Traversables
 
 PHP has a number of "lazy list" options.  Generally, they are all objects that implement the `\Traversable` interface.  However, there are several syntax options available with their own subtleties.  Serde supports them in different ways.

src/Attributes/Field.php

@@ -371,6 +371,9 @@ public function validate(mixed $value): bool
 
         if ($this->phpType === $valueType) {
             $valid = true;
+        } elseif ($this->phpType === 'mixed') {
+            // From a type perspective, mixed accepts anything.
+            $valid = true;
         } elseif ($this->nullable && $valueType === 'null') {
             $valid = true;
         } elseif (is_object($value) || class_exists($this->phpType) || interface_exists($this->phpType)) {

src/Attributes/MixedField.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Crell\Serde\Attributes;
+
+use Attribute;
+use Crell\AttributeUtils\SupportsScopes;
+use Crell\Serde\TypeField;
+
+/**
+ * Specifies how a mixed field should be deserialized.
+ *
+ * In particular, it allows specifying a class type to which an array-ish
+ * value should be deserialized.
+ */
+#[Attribute(Attribute::TARGET_PROPERTY)]
+class MixedField implements TypeField, SupportsScopes
+{
+    /**
+     * @param string $suggestedType
+     *   The class name that an array-ish value should be deserialized into.
+     *   Primitive values will be left as is when deserializing.
+     * @param array<string|null> $scopes
+     *   The scopes in which this attribute should apply.
+     */
+    public function __construct(
+        public readonly string $suggestedType,
+        protected readonly array $scopes = [null],
+    ) {}
+
+    public function scopes(): array
+    {
+        return $this->scopes;
+    }
+
+    public function acceptsType(string $type): bool
+    {
+        return $type === 'mixed';
+    }
+
+    public function validate(mixed $value): bool
+    {
+        return true;
+    }
+}

src/PropertyHandler/MixedExporter.php

@@ -6,6 +6,7 @@
 
 use Crell\Serde\Attributes\DictionaryField;
 use Crell\Serde\Attributes\Field;
+use Crell\Serde\Attributes\MixedField;
 use Crell\Serde\CollectionItem;
 use Crell\Serde\Deserializer;
 use Crell\Serde\Dict;
@@ -19,14 +20,19 @@
  * Exporter/importer for `mixed` properties.
  *
  * This class makes a good-faith attempt to detect the type of a given field by its value.
- * It currently does not work for objects, and on import it works only on array-based
- * formats (JSON, YAML, TOML, etc.)
+ * On import, it currently works only on array-based formats (JSON, YAML, TOML, etc.)
+ *
+ * To deserialize into an object, the property must have the MixedField attribute.
+ *
+ * @see MixedField
  */
 class MixedExporter implements Importer, Exporter
 {
     public function exportValue(Serializer $serializer, Field $field, mixed $value, mixed $runningValue): mixed
     {
-        return $serializer->serialize($value, $runningValue, Field::create(
+        // We need to bypass the circular reference check in Serializer::serialize(),
+        // or else an object would always fail here.
+        return $serializer->doSerialize($value, $runningValue, Field::create(
             serializedName: $field->serializedName,
             phpType: \get_debug_type($value),
         ));
@@ -39,6 +45,12 @@ public function importValue(Deserializer $deserializer, Field $field, mixed $sou
         // it directly.
         $type = \get_debug_type($source[$field->serializedName]);
 
+        /** @var MixedField|null $typeField */
+        $typeField = $field->typeField;
+        if ($typeField && class_exists($typeField->suggestedType) && $type === 'array') {
+            $type = $typeField->suggestedType;
+        }
+
         return $deserializer->deserialize($source, Field::create(
             serializedName: $field->serializedName,
             phpType: $type,

src/Serializer.php

@@ -44,8 +44,7 @@ public function serialize(mixed $value, mixed $runningValue, Field $field): mixe
             $this->seenObjects[] = $value;
         }
 
-        $reader = $this->findExporter($field, $value);
-        $result = $reader->exportValue($this, $field, $value, $runningValue);
+        $result = $this->doSerialize($value, $runningValue, $field);
 
         if (is_object($value)) {
             array_pop($this->seenObjects);
@@ -54,6 +53,21 @@ public function serialize(mixed $value, mixed $runningValue, Field $field): mixe
         return $result;
     }
 
+    /**
+     * @internal
+     *
+     * There's one case where we need the circular detection disabled, and that's when
+     * dealing with mixed fields.  A mixed field throws its value back through the serializer,
+     * which is normally fine but would trigger the circular reference checks in serialize().
+     * Instead, we split it out to a separate method that no one should use except MixedExporter.
+     * That means if you're reading this, you should walk away now because you're not supposed
+     * to use this method.
+     */
+    public function doSerialize(mixed $value, mixed $runningValue, Field $field): mixed
+    {
+        return $this->findExporter($field, $value)->exportValue($this, $field, $value, $runningValue);
+    }
+
     protected function findExporter(Field $field, mixed $value): Exporter
     {
         $format = $this->formatter->format();

tests/Records/MixedValObject.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Crell\Serde\Records;
+
+use Crell\Serde\Attributes\MixedField;
+
+class MixedValObject
+{
+    public function __construct(
+        #[MixedField(Point::class)]
+        public mixed $val
+    ) {}
+}

tests/SerdeTestCases.php

@@ -49,6 +49,7 @@
 use Crell\Serde\Records\MappedCollected\ThingC;
 use Crell\Serde\Records\MappedCollected\ThingList;
 use Crell\Serde\Records\MixedVal;
+use Crell\Serde\Records\MixedValObject;
 use Crell\Serde\Records\MultiCollect\ThingOneA;
 use Crell\Serde\Records\MultiCollect\ThingTwoC;
 use Crell\Serde\Records\MultiCollect\Wrapper;
@@ -1062,27 +1063,30 @@ public static function mixed_val_property_examples(): iterable
         yield 'dict' => [new MixedVal(['a' => 'A', 'b' => 'B', 'c' => 'C'])];
     }
 
-    public function mixed_val_property_validate(mixed $serialized, mixed $data): void
+    #[Test,  DataProvider('mixed_val_property_object_examples')]
+    public function mixed_val_property_object(mixed $data): void
     {
-    }
+        $s = new SerdeCommon(formatters: $this->formatters);
 
-    /**
-     * This isn't a desired feature; it's just confirmation for the future why it is how it is.
-     */
-    #[Test]
-    public function mixed_val_object_does_not_serialize(): void
-    {
-        // MixedExporter sends the property value back through the Serialize pipeline
-        // a second time with a new Field definition. However, that trips the circular
-        // reference detection.  Ideally we will fix that somehow, but I'm not sure how.
-        // Importing an object to mixed will never work correctly.
-        $this->expectException(CircularReferenceDetected::class);
+        $serialized = $s->serialize($data, $this->format);
+
+        $this->mixed_val_property_validate($serialized, $data);
 
-        $data = new MixedVal(new Point(3, 4, 5));
+        $result = $s->deserialize($serialized, from: $this->format, to: MixedValObject::class);
 
-        $s = new SerdeCommon(formatters: $this->formatters);
+        self::assertEquals($data, $result);
+    }
 
-        $serialized = $s->serialize($data, $this->format);
+    public static function mixed_val_property_object_examples(): iterable
+    {
+        yield 'string' => [new MixedValObject('hello')];
+        yield 'int' => [new MixedValObject(5)];
+        yield 'float' => [new MixedValObject(3.14)];
+        yield 'object' => [new MixedValObject(new Point(1, 2, 3))];
+    }
+
+    public function mixed_val_property_validate(mixed $serialized, mixed $data): void
+    {
     }
 
     #[Test]