PHPLIB-1180: Add basic infrastructure for codecs (#1125)

* Add psalm stubs for new BSON classes

* Add basic codec infrastructure

* Introduce codec library

* Exclude methods inherited from traits in PedantryTest

This commit also uses dataset names for better visibility during debugging

* Exclude stubs from git exports

* Improve architecture document

* Use native types for DocumentCodec interface

* Add description to codec interfaces

* Remove internal designation from Decoder and Encoder interfaces

* Remove unnecessary psalm-param annotations

* Rename attachLibrary method in KnowsCodecLibrary interface

The new method name is more specific and helps prevent naming conflicts

* Use better values in test codecs

* Add comment explaining stub files are temporary

* Add comment explaining potential mocking when using PHPUnit 10

* Introduce domain exceptions for decoding and encoding

* Improve codec architecture documentation

.gitattributes

@@ -4,6 +4,7 @@ tests export-ignore
 docs export-ignore
 examples export-ignore
 mongo-orchestration export-ignore
+stubs export-ignore
 tools export-ignore
 Makefile export-ignore
 phpcs.xml.dist export-ignore

psalm-baseline.xml

@@ -75,6 +75,16 @@
  <code>$mergedDriver['platform']</code>
  </MixedAssignment>
  </file>
+ <file src="src/Codec/DecodeIfSupported.php">
+ <MixedInferredReturnType occurrences="1">
+ <code>($value is BSONType ? NativeType : $value)</code>
+ </MixedInferredReturnType>
+ </file>
+ <file src="src/Codec/EncodeIfSupported.php">
+ <MixedInferredReturnType occurrences="1">
+ <code>($value is NativeType ? BSONType : $value)</code>
+ </MixedInferredReturnType>
+ </file>
  <file src="src/Command/ListCollections.php">
  <MixedAssignment occurrences="2">
  <code>$cmd[$option]</code>

psalm.xml.dist

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

src/Codec/Codec.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;
+
+/**
+ * The Codec interface allows decoding BSON data to native PHP types and back
+ * to BSON.
+ *
+ * @psalm-template BSONType
+ * @psalm-template NativeType
+ * @template-extends Decoder<BSONType, NativeType>
+ * @template-extends Encoder<BSONType, NativeType>
+ */
+interface Codec extends Decoder, Encoder
+{
+}

src/Codec/CodecLibrary.php

@@ -0,0 +1,146 @@
+<?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\InvalidArgumentException;
+use MongoDB\Exception\UnsupportedValueException;
+
+class CodecLibrary implements Codec
+{
+ use DecodeIfSupported;
+ use EncodeIfSupported;
+
+ /** @var array<Decoder> */
+ private $decoders = [];
+
+ /** @var array<Encoder> */
+ private $encoders = [];
+
+ /** @param Decoder|Encoder $items */
+ public function __construct(...$items)
+ {
+ foreach ($items as $item) {
+ if (! $item instanceof Decoder && ! $item instanceof Encoder) {
+ throw InvalidArgumentException::invalidType('$items', $item, [Decoder::class, Encoder::class]);
+ }
+
+ if ($item instanceof Codec) {
+ // Use attachCodec to avoid multiple calls to attachLibrary
+ $this->attachCodec($item);
+
+ continue;
+ }
+
+ if ($item instanceof Decoder) {
+ $this->attachDecoder($item);
+ }
+
+ if ($item instanceof Encoder) {
+ $this->attachEncoder($item);
+ }
+ }
+ }
+
+ /** @return static */
+ final public function attachCodec(Codec $codec): self
+ {
+ $this->decoders[] = $codec;
+ $this->encoders[] = $codec;
+ if ($codec instanceof KnowsCodecLibrary) {
+ $codec->attachCodecLibrary($this);
+ }
+
+ return $this;
+ }
+
+ /** @return static */
+ final public function attachDecoder(Decoder $decoder): self
+ {
+ $this->decoders[] = $decoder;
+ if ($decoder instanceof KnowsCodecLibrary) {
+ $decoder->attachCodecLibrary($this);
+ }
+
+ return $this;
+ }
+
+ /** @return static */
+ final public function attachEncoder(Encoder $encoder): self
+ {
+ $this->encoders[] = $encoder;
+ if ($encoder instanceof KnowsCodecLibrary) {
+ $encoder->attachCodecLibrary($this);
+ }
+
+ return $this;
+ }
+
+ /** @param mixed $value */
+ final public function canDecode($value): bool
+ {
+ foreach ($this->decoders as $decoder) {
+ if ($decoder->canDecode($value)) {
+ return true;
+ }
+ }
+
+ return false;
+ }
+
+ /** @param mixed $value */
+ final public function canEncode($value): bool
+ {
+ foreach ($this->encoders as $encoder) {
+ if ($encoder->canEncode($value)) {
+ return true;
+ }
+ }
+
+ return false;
+ }
+
+ /**
+ * @param mixed $value
+ * @return mixed
+ */
+ final public function decode($value)
+ {
+ foreach ($this->decoders as $decoder) {
+ if ($decoder->canDecode($value)) {
+ return $decoder->decode($value);
+ }
+ }
+
+ throw UnsupportedValueException::invalidDecodableValue($value);
+ }
+
+ /**
+ * @param mixed $value
+ * @return mixed
+ */
+ final public function encode($value)
+ {
+ foreach ($this->encoders as $encoder) {
+ if ($encoder->canEncode($value)) {
+ return $encoder->encode($value);
+ }
+ }
+
+ throw UnsupportedValueException::invalidEncodableValue($value);
+ }
+}

src/Codec/DecodeIfSupported.php

@@ -0,0 +1,52 @@
+<?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;
+
+/**
+ * @psalm-template BSONType
+ * @psalm-template NativeType
+ */
+trait DecodeIfSupported
+{
+ /**
+ * @param mixed $value
+ * @psalm-assert-if-true BSONType $value
+ */
+ abstract public function canDecode($value): bool;
+
+ /**
+ * @param mixed $value
+ * @psalm-param BSONType $value
+ * @return mixed
+ * @psalm-return NativeType
+ * @throws UnsupportedValueException if the decoder does not support the value
+ */
+ abstract public function decode($value);
+
+ /**
+ * @param mixed $value
+ * @return mixed
+ * @psalm-return ($value is BSONType ? NativeType : $value)
+ */
+ public function decodeIfSupported($value)
+ {
+ return $this->canDecode($value) ? $this->decode($value) : $value;
+ }
+}

src/Codec/Decoder.php

@@ -0,0 +1,59 @@
+<?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;
+
+/**
+ * @psalm-template BSONType
+ * @psalm-template NativeType
+ */
+interface Decoder
+{
+ /**
+ * Checks if the decoder supports a given value.
+ *
+ * @param mixed $value
+ * @psalm-assert-if-true BSONType $value
+ */
+ public function canDecode($value): bool;
+
+ /**
+ * Decodes a given value. If the decoder does not support the value, it
+ * should throw an exception.
+ *
+ * @param mixed $value
+ * @psalm-param BSONType $value
+ * @return mixed
+ * @psalm-return NativeType
+ * @throws UnsupportedValueException if the decoder does not support the value
+ */
+ public function decode($value);
+
+ /**
+ * Decodes a given value if supported, otherwise returns the value as-is.
+ *
+ * The DecodeIfSupported trait provides a default implementation of this
+ * method.
+ *
+ * @param mixed $value
+ * @return mixed
+ * @psalm-return ($value is BSONType ? NativeType : $value)
+ */
+ public function decodeIfSupported($value);
+}

src/Codec/DocumentCodec.php

@@ -0,0 +1,46 @@
+<?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\Document;
+use MongoDB\Exception\UnsupportedValueException;
+
+/**
+ * The DocumentCodec interface allows decoding BSON document data to native PHP
+ * objects and back to BSON documents.
+ *
+ * @psalm-template ObjectType of object
+ * @template-extends Codec<Document, ObjectType>
+ */
+interface DocumentCodec extends Codec
+{
+ /**
+ * @param mixed $value
+ * @psalm-param Document $value
+ * @psalm-return ObjectType
+ * @throws UnsupportedValueException if the decoder does not support the value
+ */
+ public function decode($value): object;
+
+ /**
+ * @param mixed $value
+ * @psalm-param ObjectType $value
+ * @throws UnsupportedValueException if the encoder does not support the value
+ */
+ public function encode($value): Document;
+}