Document MixedField.

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/MixedField.php

@@ -4,13 +4,26 @@
 
 namespace Crell\Serde\Attributes;
 
+use Attribute;
 use Crell\AttributeUtils\SupportsScopes;
 use Crell\Serde\TypeField;
-use Attribute;
 
+/**
+ * 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],

src/PropertyHandler/MixedExporter.php

@@ -20,8 +20,11 @@
  * 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
 {