PHPLIB-1181: Introduce lazy BSON classes

psalm-baseline.xml

@@ -28,6 +28,11 @@
       <code>($value is NativeType ? BSONType : $value)</code>
     </MixedInferredReturnType>
   </file>
+  <file src="src/Codec/LazyBSONArrayCodec.php">
+    <MixedAssignment>
+      <code>$return[]</code>
+    </MixedAssignment>
+  </file>
   <file src="src/Command/ListCollections.php">
     <MixedAssignment>
       <code>$cmd[$option]</code>
@@ -168,6 +173,74 @@
       <code><![CDATA[$this->index['name']]]></code>
     </MixedReturnStatement>
   </file>
+  <file src="src/Model/LazyBSONArray.php">
+    <MixedArgument>
+      <code>$offset</code>
+      <code>$offset</code>
+      <code>$offset</code>
+    </MixedArgument>
+    <MixedArgumentTypeCoercion>
+      <code><![CDATA[new CallbackFilterIterator(
+                    $itemIterator,
+                    /** @param TValue $value */
+                    function ($value, int $offset) use (&$seen): bool {
+                        return ! isset($this->unset[$offset]) && ! isset($seen[$offset]);
+                    },
+                )]]></code>
+      <code><![CDATA[new CallbackIterator(
+                // Skip keys that were unset or handled in a previous iterator
+                new CallbackFilterIterator(
+                    $itemIterator,
+                    /** @param TValue $value */
+                    function ($value, int $offset) use (&$seen): bool {
+                        return ! isset($this->unset[$offset]) && ! isset($seen[$offset]);
+                    },
+                ),
+                /**
+                 * @param TValue $value
+                 * @return TValue
+                 */
+                function ($value, int $offset) use (&$seen) {
+                    // Mark key as seen, skipping any future occurrences
+                    $seen[$offset] = true;
+
+                    // Return actual value (potentially overridden by offsetSet)
+                    return $this->offsetGet($offset);
+                },
+            )]]></code>
+    </MixedArgumentTypeCoercion>
+    <MixedArrayAssignment>
+      <code>$seen[$offset]</code>
+    </MixedArrayAssignment>
+    <MixedAssignment>
+      <code>$value</code>
+    </MixedAssignment>
+    <RedundantConditionGivenDocblockType>
+      <code>is_array($input)</code>
+    </RedundantConditionGivenDocblockType>
+    <TypeDoesNotContainType>
+      <code>is_numeric($key)</code>
+    </TypeDoesNotContainType>
+  </file>
+  <file src="src/Model/LazyBSONDocument.php">
+    <MismatchingDocblockReturnType>
+      <code><![CDATA[Iterator<string, TValue>]]></code>
+    </MismatchingDocblockReturnType>
+    <MixedAssignment>
+      <code>$value</code>
+    </MixedAssignment>
+    <MixedInferredReturnType>
+      <code><![CDATA[Iterator<string, TValue>]]></code>
+    </MixedInferredReturnType>
+    <RedundantConditionGivenDocblockType>
+      <code>is_object($input)</code>
+    </RedundantConditionGivenDocblockType>
+  </file>
+  <file src="src/Model/ListIterator.php">
+    <InvalidTemplateParam>
+      <code>ListIterator</code>
+    </InvalidTemplateParam>
+  </file>
   <file src="src/Operation/Aggregate.php">
     <MixedArgument>
       <code><![CDATA[$this->options['typeMap']]]></code>

src/Codec/ArrayCodec.php

@@ -0,0 +1,111 @@
+<?php
+/*
+ * Copyright 2023-present MongoDB, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+namespace MongoDB\Codec;
+
+use MongoDB\Exception\UnsupportedValueException;
+
+use function array_map;
+use function is_array;
+
+/**
+ * Codec to recursively encode/decode values in arrays.
+ *
+ * @template-implements Codec<array, array>
+ */
+final class ArrayCodec implements Codec, CodecLibraryAware
+{
+    private ?CodecLibrary $library = null;
+
+    public function attachCodecLibrary(CodecLibrary $library): void
+    {
+        $this->library = $library;
+    }
+
+    /**
+     * @param mixed $value
+     * @psalm-assert-if-true array $value
+     */
+    public function canDecode($value): bool
+    {
+        return is_array($value);
+    }
+
+    /**
+     * @param mixed $value
+     * @psalm-assert-if-true array $value
+     */
+    public function canEncode($value): bool
+    {
+        return is_array($value);
+    }
+
+    /** @param mixed $value */
+    public function decode($value): array
+    {
+        if (! $this->canDecode($value)) {
+            throw UnsupportedValueException::invalidDecodableValue($value);
+        }
+
+        return array_map(
+            [$this->getLibrary(), 'decodeIfSupported'],
+            $value,
+        );
+    }
+
+    /**
+     * @param mixed $value
+     * @return mixed
+     * @psalm-return ($value is array ? array : $value)
+     */
+    public function decodeIfSupported($value)
+    {
+        return $this->canDecode($value) ? $this->decode($value) : $value;
+    }
+
+    /** @param mixed $value */
+    public function encode($value): array
+    {
+        if (! $this->canEncode($value)) {
+            throw UnsupportedValueException::invalidEncodableValue($value);
+        }
+
+        return array_map(
+            [$this->getLibrary(), 'encodeIfSupported'],
+            $value,
+        );
+    }
+
+    /**
+     * @param mixed $value
+     * @return mixed
+     * @psalm-return ($value is array ? array : $value)
+     */
+    public function encodeIfSupported($value)
+    {
+        return $this->canEncode($value) ? $this->encode($value) : $value;
+    }
+
+    private function getLibrary(): CodecLibrary
+    {
+        if (! $this->library) {
+            $this->library = new CodecLibrary();
+        }
+
+        return $this->library;
+    }
+}

src/Codec/CodecLibrary.php

@@ -64,7 +64,7 @@ final public function attachCodec(Codec $codec): self
     {
         $this->decoders[] = $codec;
         $this->encoders[] = $codec;
-        if ($codec instanceof KnowsCodecLibrary) {
+        if ($codec instanceof CodecLibraryAware) {
             $codec->attachCodecLibrary($this);
         }
 
@@ -75,7 +75,7 @@ final public function attachCodec(Codec $codec): self
     final public function attachDecoder(Decoder $decoder): self
     {
         $this->decoders[] = $decoder;
-        if ($decoder instanceof KnowsCodecLibrary) {
+        if ($decoder instanceof CodecLibraryAware) {
             $decoder->attachCodecLibrary($this);
         }
 
@@ -86,7 +86,7 @@ final public function attachDecoder(Decoder $decoder): self
     final public function attachEncoder(Encoder $encoder): self
     {
         $this->encoders[] = $encoder;
-        if ($encoder instanceof KnowsCodecLibrary) {
+        if ($encoder instanceof CodecLibraryAware) {
             $encoder->attachCodecLibrary($this);
         }
 

src/Codec/KnowsCodecLibrary.php → src/Codec/CodecLibraryAware.php

@@ -22,7 +22,7 @@
  * it was added to. The library will be injected when the codec is added to the
  * library. This allows codecs to recursively encode its nested values.
  */
-interface KnowsCodecLibrary
+interface CodecLibraryAware
 {
     public function attachCodecLibrary(CodecLibrary $library): void;
 }

src/Codec/LazyBSONArrayCodec.php

@@ -0,0 +1,110 @@
+<?php
+/*
+ * Copyright 2023-present MongoDB, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+namespace MongoDB\Codec;
+
+use MongoDB\BSON\PackedArray;
+use MongoDB\Exception\UnsupportedValueException;
+use MongoDB\Model\LazyBSONArray;
+
+/**
+ * Codec for lazy decoding of BSON PackedArray instances
+ *
+ * @template-implements Codec<PackedArray, LazyBSONArray>
+ */
+final class LazyBSONArrayCodec implements Codec, CodecLibraryAware
+{
+    private ?CodecLibrary $library = null;
+
+    public function attachCodecLibrary(CodecLibrary $library): void
+    {
+        $this->library = $library;
+    }
+
+    /**
+     * @param mixed $value
+     * @psalm-assert-if-true PackedArray $value
+     */
+    public function canDecode($value): bool
+    {
+        return $value instanceof PackedArray;
+    }
+
+    /**
+     * @param mixed $value
+     * @psalm-assert-if-true LazyBSONArray $value
+     */
+    public function canEncode($value): bool
+    {
+        return $value instanceof LazyBSONArray;
+    }
+
+    /** @param mixed $value */
+    public function decode($value): LazyBSONArray
+    {
+        if (! $value instanceof PackedArray) {
+            throw UnsupportedValueException::invalidDecodableValue($value);
+        }
+
+        return new LazyBSONArray($value, $this->getLibrary());
+    }
+
+    /**
+     * @param mixed $value
+     * @return mixed
+     * @psalm-return ($value is PackedArray ? LazyBSONArray : $value)
+     */
+    public function decodeIfSupported($value)
+    {
+        return $this->canDecode($value) ? $this->decode($value) : $value;
+    }
+
+    /** @param mixed $value */
+    public function encode($value): PackedArray
+    {
+        if (! $value instanceof LazyBSONArray) {
+            throw UnsupportedValueException::invalidEncodableValue($value);
+        }
+
+        $return = [];
+        /** @var mixed $offsetValue */
+        foreach ($value as $offsetValue) {
+            $return[] = $this->getLibrary()->encodeIfSupported($offsetValue);
+        }
+
+        return PackedArray::fromPHP($return);
+    }
+
+    /**
+     * @param mixed $value
+     * @return mixed
+     * @psalm-return ($value is LazyBSONArray ? PackedArray : $value)
+     */
+    public function encodeIfSupported($value)
+    {
+        return $this->canEncode($value) ? $this->encode($value) : $value;
+    }
+
+    private function getLibrary(): CodecLibrary
+    {
+        if (! $this->library) {
+            $this->library = new LazyBSONCodecLibrary();
+        }
+
+        return $this->library;
+    }
+}

src/Codec/LazyBSONCodecLibrary.php

@@ -0,0 +1,31 @@
+<?php
+/*
+ * Copyright 2023-present MongoDB, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+namespace MongoDB\Codec;
+
+final class LazyBSONCodecLibrary extends CodecLibrary
+{
+    public function __construct()
+    {
+        parent::__construct(
+            new LazyBSONDocumentCodec(),
+            new LazyBSONArrayCodec(),
+            new ArrayCodec(),
+            new ObjectCodec(),
+        );
+    }
+}