Add example for deserialisation using typemap

Author: alcaeus

examples/typemap.php

@@ -0,0 +1,121 @@
+<?php
+declare(strict_types=1);
+
+namespace MongoDB\Examples;
+
+use MongoDB\BSON\ObjectId;
+use MongoDB\BSON\Unserializable;
+use MongoDB\Client;
+use UnexpectedValueException;
+
+use function dirname;
+use function getenv;
+use function is_array;
+use function var_dump;
+
+require dirname(__FILE__) . '/../vendor/autoload.php';
+
+class TypemapEntry implements Unserializable
+{
+    /** @var ObjectId */
+    private $id;
+
+    /** @var string */
+    private $name;
+
+    /** @var array<TypemapEmail> */
+    private $emails;
+
+    private function __construct()
+    {
+    }
+
+    public function getId(): ObjectId
+    {
+        return $this->id;
+    }
+
+    public function getName(): string
+    {
+        return $this->name;
+    }
+
+    public function getEmails(): array
+    {
+        return $this->emails;
+    }
+
+    public function bsonUnserialize(array $data): void
+    {
+        if (! $data['_id'] instanceof ObjectId) {
+            throw new UnexpectedValueException('_id field is not of the expected type');
+        }
+
+        if (! is_array($data['emails'])) {
+            throw new UnexpectedValueException('emails field is not of the expected type');
+        }
+
+        $this->id = $data['_id'];
+        $this->name = (string) $data['name'];
+
+        /** @psalm-suppress MixedPropertyTypeCoercion */
+        $this->emails = $data['emails'];
+    }
+}
+
+class TypemapEmail implements Unserializable
+{
+    /** @var string */
+    private $type;
+
+    /** @var string */
+    private $address;
+
+    private function __construct()
+    {
+    }
+
+    public function getType(): string
+    {
+        return $this->type;
+    }
+
+    public function getAddress(): string
+    {
+        return $this->address;
+    }
+
+    public function bsonUnserialize(array $data): void
+    {
+        $this->type = (string) $data['type'];
+        $this->address = (string) $data['address'];
+    }
+}
+
+$client = new Client(getenv('MONGODB_URI') ?: 'mongodb://127.0.0.1/');
+
+$collection = $client->test->coll;
+$collection->drop();
+
+$document = [
+    'name' => 'alcaeus',
+    'emails' => [
+        ['type' => 'work', 'address' => '[email protected]'],
+        ['type' => 'private', 'address' => '[email protected]'],
+    ],
+];
+
+$collection->insertOne($document);
+
+$typeMap = [
+    'root' => TypemapEntry::class, // Root object will be an Entry instance
+    'fieldPaths' => [
+        'emails' => 'array', // Emails field is used as PHP array
+        'emails.$' => TypemapEmail::class, // Each element in the emails array will be an Email instance
+    ],
+];
+
+$entry = $collection->findOne([], ['typeMap' => $typeMap]);
+
+/** @psalm-suppress ForbiddenCode */
+var_dump($entry);

psalm-baseline.xml

@@ -1,5 +1,14 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <files psalm-version="4.x-dev@5108834088c1d8cae3698df6ef6bf15fe6e76c53">
+  <file src="examples/typemap.php">
+    <PropertyNotSetInConstructor occurrences="5">
+      <code>$address</code>
+      <code>$emails</code>
+      <code>$id</code>
+      <code>$name</code>
+      <code>$type</code>
+    </PropertyNotSetInConstructor>
+  </file>
   <file src="src/Client.php">
     <MixedArgument occurrences="1">
       <code>$driverOptions['driver'] ?? []</code>