PHPLIB-1022: Codec implementation for better BSON decoding/encoding

phpcs.xml.dist

@@ -172,9 +172,11 @@
     <rule ref="PSR1.Classes.ClassDeclaration.MultipleClasses">
         <exclude-pattern>/examples</exclude-pattern>
         <exclude-pattern>/tests/PHPUnit/ConstraintTrait.php</exclude-pattern>
+        <exclude-pattern>tests/Collection/CodecCollectionTest</exclude-pattern>
     </rule>
     <rule ref="Squiz.Classes.ClassFileName.NoMatch">
         <exclude-pattern>/examples</exclude-pattern>
+        <exclude-pattern>tests/Collection/CodecCollectionTest</exclude-pattern>
     </rule>
     <rule ref="Squiz.Classes.ValidClassName.NotCamelCaps">
         <exclude-pattern>/tests/SpecTests/ClientSideEncryption/Prose*</exclude-pattern>

psalm.xml.dist

@@ -14,4 +14,9 @@
             <directory name="vendor" />
         </ignoreFiles>
     </projectFiles>
+    <stubs>
+        <file name="stubs/BSON/BSON.stub.php"/>
+        <file name="stubs/BSON/Document.stub.php"/>
+        <file name="stubs/BSON/PackedArray.stub.php"/>
+    </stubs>
 </psalm>

src/Codec/Codec.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace MongoDB\Codec;
+
+/**
+ * @api
+ *
+ * @psalm-template B
+ * @psalm-template T
+ * @template-extends Decoder<B, T>
+ * @template-extends Encoder<B, T>
+ */
+interface Codec extends Decoder, Encoder
+{
+}

src/Codec/CodecLibrary.php

@@ -0,0 +1,137 @@
+<?php
+
+namespace MongoDB\Codec;
+
+use MongoDB\Exception\UnexpectedValueException;
+
+use function array_map;
+use function get_debug_type;
+use function sprintf;
+
+class CodecLibrary implements Codec
+{
+    /** @var array<Decoder> */
+    private $decoders = [];
+
+    /** @var array<Encoder> */
+    private $encoders = [];
+
+    /** @param Decoder|Encoder $items */
+    public function __construct(...$items)
+    {
+        array_map(
+            function ($item) {
+                if ($item instanceof Decoder) {
+                    $this->attachDecoder($item);
+                }
+
+                if ($item instanceof Encoder) {
+                    $this->attachEncoder($item);
+                }
+
+                // Yes, we'll silently discard everything. Please let me already have union types...
+            },
+            $items
+        );
+    }
+
+    /** @return static */
+    final public function attachCodec(Codec $codec): self
+    {
+        $this->decoders[] = $codec;
+        $this->encoders[] = $codec;
+        if ($codec instanceof KnowsCodecLibrary) {
+            $codec->attachLibrary($this);
+        }
+
+        return $this;
+    }
+
+    /** @return static */
+    final public function attachDecoder(Decoder $decoder): self
+    {
+        $this->decoders[] = $decoder;
+        if ($decoder instanceof KnowsCodecLibrary) {
+            $decoder->attachLibrary($this);
+        }
+
+        return $this;
+    }
+
+    /** @return static */
+    final public function attachEncoder(Encoder $encoder): self
+    {
+        $this->encoders[] = $encoder;
+        if ($encoder instanceof KnowsCodecLibrary) {
+            $encoder->attachLibrary($this);
+        }
+
+        return $this;
+    }
+
+    /** @param mixed $value */
+    final public function canDecode($value): bool
+    {
+        foreach ($this->decoders as $decoder) {
+            if ($decoder->canDecode($value)) {
+                return true;
+            }
+        }
+
+        return $value === null;
+    }
+
+    /** @param mixed $value */
+    final public function canEncode($value): bool
+    {
+        foreach ($this->encoders as $encoder) {
+            if ($encoder->canEncode($value)) {
+                return true;
+            }
+        }
+
+        return $value === null;
+    }
+
+    /**
+     * @param mixed $value
+     * @return mixed
+     */
+    final public function decode($value)
+    {
+        foreach ($this->decoders as $decoder) {
+            if (! $decoder->canDecode($value)) {
+                continue;
+            }
+
+            return $decoder->decode($value);
+        }
+
+        if ($value === null) {
+            return null;
+        }
+
+        throw new UnexpectedValueException(sprintf('No decoder found for value of type "%s"', get_debug_type($value)));
+    }
+
+    /**
+     * @param mixed $value
+     * @return mixed
+     */
+    final public function encode($value)
+    {
+        foreach ($this->encoders as $encoder) {
+            if (! $encoder->canEncode($value)) {
+                continue;
+            }
+
+            return $encoder->encode($value);
+        }
+
+        if ($value === null) {
+            return null;
+        }
+
+        throw new UnexpectedValueException(sprintf('No encoder found for value of type "%s"', get_debug_type($value)));
+    }
+}

src/Codec/Decoder.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace MongoDB\Codec;
+
+/**
+ * @api
+ *
+ * @psalm-template B
+ * @psalm-template T
+ */
+interface Decoder
+{
+    /**
+     * @param mixed $value
+     * @psalm-assert-if-true B $value
+     */
+    public function canDecode($value): bool;
+
+    /**
+     * @param mixed $value
+     * @psalm-param B $value
+     * @return mixed
+     * @psalm-return T
+     */
+    public function decode($value);
+}

src/Codec/Encoder.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace MongoDB\Codec;
+
+/**
+ * @api
+ *
+ * @psalm-template B
+ * @psalm-template T
+ */
+interface Encoder
+{
+    /**
+     * @param mixed $value
+     * @psalm-assert-if-true T $value
+     */
+    public function canEncode($value): bool;
+
+    /**
+     * @param mixed $value
+     * @psalm-param T $value
+     * @return mixed
+     * @psalm-return B
+     */
+    public function encode($value);
+}

src/Codec/KnowsCodecLibrary.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace MongoDB\Codec;
+
+interface KnowsCodecLibrary
+{
+    public function attachLibrary(CodecLibrary $library): void;
+}

src/Codec/LazyBSONArrayCodec.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace MongoDB\Codec;
+
+use MongoDB\BSON\PackedArray;
+use MongoDB\Exception\UnexpectedValueException;
+use MongoDB\Model\LazyBSONArray;
+
+use function array_values;
+use function sprintf;
+
+/**
+ * Codec for lazy decoding of BSON PackedArray instances
+ *
+ * @template-implements Codec<PackedArray, LazyBSONArray>
+ */
+class LazyBSONArrayCodec implements Codec, KnowsCodecLibrary
+{
+    /** @var CodecLibrary|null */
+    private $library = null;
+
+    public function attachLibrary(CodecLibrary $library): void
+    {
+        $this->library = $library;
+    }
+
+    /** @inheritDoc */
+    public function canDecode($value): bool
+    {
+        return $value instanceof PackedArray;
+    }
+
+    /** @inheritDoc */
+    public function canEncode($value): bool
+    {
+        return $value instanceof LazyBSONArray;
+    }
+
+    /** @inheritDoc */
+    public function decode($value): LazyBSONArray
+    {
+        if (! $value instanceof PackedArray) {
+            throw new UnexpectedValueException(sprintf('"%s" can only decode from "%s" instances', self::class, PackedArray::class));
+        }
+
+        return new LazyBSONArray($value, $this->getLibrary());
+    }
+
+    /** @inheritDoc */
+    public function encode($value): PackedArray
+    {
+        if (! $value instanceof LazyBSONArray) {
+            throw new UnexpectedValueException(sprintf('"%s" can only encode "%s" instances', self::class, LazyBSONArray::class));
+        }
+
+        $return = [];
+        foreach ($value as $offset => $offsetValue) {
+            $return[$offset] = $this->getLibrary()->canEncode($offsetValue) ? $this->getLibrary()->encode($offsetValue) : $offsetValue;
+        }
+
+        return PackedArray::fromPHP(array_values($return));
+    }
+
+    private function getLibrary(): CodecLibrary
+    {
+        return $this->library ?? $this->library = new CodecLibrary(new LazyBSONDocumentCodec(), $this);
+    }
+}

src/Codec/LazyBSONDocumentCodec.php

@@ -0,0 +1,67 @@
+<?php
+
+namespace MongoDB\Codec;
+
+use MongoDB\BSON\Document;
+use MongoDB\Exception\UnexpectedValueException;
+use MongoDB\Model\LazyBSONDocument;
+
+use function sprintf;
+
+/**
+ * Codec for lazy decoding of BSON Document instances
+ *
+ * @template-implements Codec<Document, LazyBSONDocument>
+ */
+class LazyBSONDocumentCodec implements Codec, KnowsCodecLibrary
+{
+    /** @var CodecLibrary|null */
+    private $library = null;
+
+    public function attachLibrary(CodecLibrary $library): void
+    {
+        $this->library = $library;
+    }
+
+    /** @inheritDoc */
+    public function canDecode($value): bool
+    {
+        return $value instanceof Document;
+    }
+
+    /** @inheritDoc */
+    public function canEncode($value): bool
+    {
+        return $value instanceof LazyBSONDocument;
+    }
+
+    /** @inheritDoc */
+    public function decode($value): LazyBSONDocument
+    {
+        if (! $value instanceof Document) {
+            throw new UnexpectedValueException(sprintf('"%s" can only decode from "%s" instances', self::class, Document::class));
+        }
+
+        return new LazyBSONDocument($value, $this->getLibrary());
+    }
+
+    /** @inheritDoc */
+    public function encode($value): Document
+    {
+        if (! $value instanceof LazyBSONDocument) {
+            throw new UnexpectedValueException(sprintf('"%s" can only encode "%s" instances', self::class, LazyBSONDocument::class));
+        }
+
+        $return = [];
+        foreach ($value as $field => $fieldValue) {
+            $return[$field] = $this->getLibrary()->canEncode($fieldValue) ? $this->getLibrary()->encode($fieldValue) : $fieldValue;
+        }
+
+        return Document::fromPHP($return);
+    }
+
+    private function getLibrary(): CodecLibrary
+    {
+        return $this->library ?? $this->library = new CodecLibrary($this, new LazyBSONArrayCodec());
+    }
+}