Introduce domain exceptions for decoding and encoding

src/Codec/CodecLibrary.php

@@ -18,10 +18,7 @@
 namespace MongoDB\Codec;
 
 use MongoDB\Exception\InvalidArgumentException;
-use MongoDB\Exception\UnexpectedValueException;
-
-use function get_debug_type;
-use function sprintf;
+use MongoDB\Exception\UnsupportedValueException;
 
 class CodecLibrary implements Codec
 {
@@ -129,7 +126,7 @@ final public function decode($value)
             }
         }
 
-        throw new UnexpectedValueException(sprintf('No decoder found for value of type "%s"', get_debug_type($value)));
+        throw UnsupportedValueException::invalidDecodableValue($value);
     }
 
     /**
@@ -144,6 +141,6 @@ final public function encode($value)
             }
         }
 
-        throw new UnexpectedValueException(sprintf('No encoder found for value of type "%s"', get_debug_type($value)));
+        throw UnsupportedValueException::invalidEncodableValue($value);
     }
 }

src/Codec/DecodeIfSupported.php

@@ -17,6 +17,8 @@
 
 namespace MongoDB\Codec;
 
+use MongoDB\Exception\UnsupportedValueException;
+
 /**
  * @psalm-template BSONType
  * @psalm-template NativeType
@@ -34,6 +36,7 @@ abstract public function canDecode($value): bool;
      * @psalm-param BSONType $value
      * @return mixed
      * @psalm-return NativeType
+     * @throws UnsupportedValueException if the decoder does not support the value
      */
     abstract public function decode($value);
 

src/Codec/Decoder.php

@@ -17,7 +17,7 @@
 
 namespace MongoDB\Codec;
 
-use MongoDB\Exception\InvalidArgumentException;
+use MongoDB\Exception\UnsupportedValueException;
 
 /**
  * @psalm-template BSONType
@@ -41,7 +41,7 @@ public function canDecode($value): bool;
      * @psalm-param BSONType $value
      * @return mixed
      * @psalm-return NativeType
-     * @throws InvalidArgumentException if the decoder does not support the value
+     * @throws UnsupportedValueException if the decoder does not support the value
      */
     public function decode($value);
 

src/Codec/DocumentCodec.php

@@ -18,6 +18,7 @@
 namespace MongoDB\Codec;
 
 use MongoDB\BSON\Document;
+use MongoDB\Exception\UnsupportedValueException;
 
 /**
  * The DocumentCodec interface allows decoding BSON document data to native PHP
@@ -32,12 +33,14 @@ 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;
 }

src/Codec/EncodeIfSupported.php

@@ -17,6 +17,8 @@
 
 namespace MongoDB\Codec;
 
+use MongoDB\Exception\UnsupportedValueException;
+
 /**
  * @psalm-template BSONType
  * @psalm-template NativeType
@@ -34,6 +36,7 @@ abstract public function canEncode($value): bool;
      * @psalm-param NativeType $value
      * @return mixed
      * @psalm-return BSONType
+     * @throws UnsupportedValueException if the encoder does not support the value
      */
     abstract public function encode($value);
 

src/Codec/Encoder.php

@@ -17,7 +17,7 @@
 
 namespace MongoDB\Codec;
 
-use MongoDB\Exception\InvalidArgumentException;
+use MongoDB\Exception\UnsupportedValueException;
 
 /**
  * @psalm-template BSONType
@@ -41,7 +41,7 @@ public function canEncode($value): bool;
      * @psalm-param NativeType $value
      * @return mixed
      * @psalm-return BSONType
-     * @throws InvalidArgumentException if the decoder does not support the value
+     * @throws UnsupportedValueException if the encoder does not support the value
      */
     public function encode($value);
 

src/Exception/UnsupportedValueException.php

@@ -0,0 +1,55 @@
+<?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\Exception;
+
+use InvalidArgumentException;
+
+use function get_debug_type;
+use function sprintf;
+
+class UnsupportedValueException extends InvalidArgumentException implements Exception
+{
+    /** @var mixed */
+    private $value;
+
+    /** @return mixed */
+    public function getValue()
+    {
+        return $this->value;
+    }
+
+    /** @param mixed $value */
+    public static function invalidDecodableValue($value): self
+    {
+        return new self(sprintf('Could not decode value of type "%s".', get_debug_type($value)), $value);
+    }
+
+    /** @param mixed $value */
+    public static function invalidEncodableValue($value): self
+    {
+        return new self(sprintf('Could not encode value of type "%s".', get_debug_type($value)), $value);
+    }
+
+    /** @param mixed $value */
+    private function __construct(string $message, $value)
+    {
+        parent::__construct($message);
+
+        $this->value = $value;
+    }
+}

tests/Codec/CodecLibraryTest.php

@@ -7,7 +7,7 @@
 use MongoDB\Codec\DecodeIfSupported;
 use MongoDB\Codec\EncodeIfSupported;
 use MongoDB\Codec\KnowsCodecLibrary;
-use MongoDB\Exception\UnexpectedValueException;
+use MongoDB\Exception\UnsupportedValueException;
 use MongoDB\Tests\TestCase;
 
 class CodecLibraryTest extends TestCase
@@ -36,17 +36,13 @@ public function testDecodeNull(): void
 
         $this->assertFalse($codec->canDecode(null));
 
-        $this->expectException(UnexpectedValueException::class);
-        $this->expectExceptionMessage('No decoder found for value of type "null"');
-
-        $this->assertNull($codec->decode(null));
+        $this->expectExceptionObject(UnsupportedValueException::invalidDecodableValue(null));
+        $codec->decode(null);
     }
 
     public function testDecodeUnsupportedValue(): void
     {
-        $this->expectException(UnexpectedValueException::class);
-        $this->expectExceptionMessage('No decoder found for value of type "string"');
-
+        $this->expectExceptionObject(UnsupportedValueException::invalidDecodableValue('foo'));
         $this->getCodecLibrary()->decode('foo');
     }
 
@@ -74,17 +70,13 @@ public function testEncodeNull(): void
 
         $this->assertFalse($codec->canEncode(null));
 
-        $this->expectException(UnexpectedValueException::class);
-        $this->expectExceptionMessage('No encoder found for value of type "null"');
-
+        $this->expectExceptionObject(UnsupportedValueException::invalidEncodableValue(null));
         $codec->encode(null);
     }
 
     public function testEncodeUnsupportedValue(): void
     {
-        $this->expectException(UnexpectedValueException::class);
-        $this->expectExceptionMessage('No encoder found for value of type "string"');
-
+        $this->expectExceptionObject(UnsupportedValueException::invalidEncodableValue('foo'));
         $this->getCodecLibrary()->encode('foo');
     }