Merge v1.x into v2.x

.github/workflows/tests.yml

@@ -62,8 +62,12 @@ jobs:
           fetch-depth: 2
           submodules: true
 
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
       - id: setup-mongodb
-        uses: mongodb-labs/drivers-evergreen-tools@81c6b49dd61e833229d750084f9f3c71b31acd8d
+        uses: mongodb-labs/drivers-evergreen-tools@master
         with:
           version: ${{ matrix.mongodb-version }}
           topology: ${{ matrix.topology }}

generator/config/stage/geoNear.yaml

@@ -11,6 +11,7 @@ arguments:
         name: distanceField
         type:
             - string
+        optional: true
         description: |
             The output field that contains the calculated distance. To specify a field within an embedded document, use dot notation.
     -

src/Exception/InvalidArgumentException.php

@@ -34,6 +34,17 @@ public static function cannotCombineCodecAndTypeMap(): self
         return new self('Cannot provide both "codec" and "typeMap" options');
     }
 
+    /**
+     * Thrown when an argument or option is expected to be a string or a document.
+     *
+     * @param string $name  Name of the argument or option
+     * @param mixed  $value Actual value (used to derive the type)
+     */
+    public static function expectedDocumentOrStringType(string $name, mixed $value): self
+    {
+        return new self(sprintf('Expected %s to have type "string" or "document" (array or object) but found "%s"', $name, get_debug_type($value)));
+    }
+
     /**
      * Thrown when an argument or option is expected to be a document.
      *

src/Operation/Aggregate.php

@@ -37,7 +37,6 @@
 use function is_array;
 use function is_bool;
 use function is_integer;
-use function is_object;
 use function is_string;
 use function MongoDB\is_document;
 use function MongoDB\is_last_pipeline_operator_write;
@@ -150,8 +149,8 @@ public function __construct(private string $databaseName, private ?string $colle
             throw InvalidArgumentException::invalidType('"explain" option', $this->options['explain'], 'boolean');
         }
 
-        if (isset($this->options['hint']) && ! is_string($this->options['hint']) && ! is_array($this->options['hint']) && ! is_object($this->options['hint'])) {
-            throw InvalidArgumentException::invalidType('"hint" option', $this->options['hint'], 'string or array or object');
+        if (isset($this->options['hint']) && ! is_string($this->options['hint']) && ! is_document($this->options['hint'])) {
+            throw InvalidArgumentException::expectedDocumentOrStringType('"hint" option', $this->options['hint']);
         }
 
         if (isset($this->options['let']) && ! is_document($this->options['let'])) {

src/Operation/Count.php

@@ -90,8 +90,8 @@ public function __construct(private string $databaseName, private string $collec
             throw InvalidArgumentException::expectedDocumentType('"collation" option', $this->options['collation']);
         }
 
-        if (isset($this->options['hint']) && ! is_string($this->options['hint']) && ! is_array($this->options['hint']) && ! is_object($this->options['hint'])) {
-            throw InvalidArgumentException::invalidType('"hint" option', $this->options['hint'], 'string or array or object');
+        if (isset($this->options['hint']) && ! is_string($this->options['hint']) && ! is_document($this->options['hint'])) {
+            throw InvalidArgumentException::expectedDocumentOrStringType('"hint" option', $this->options['hint']);
         }
 
         if (isset($this->options['limit']) && ! is_integer($this->options['limit'])) {

src/Operation/Delete.php

@@ -26,8 +26,6 @@
 use MongoDB\Exception\InvalidArgumentException;
 use MongoDB\Exception\UnsupportedException;
 
-use function is_array;
-use function is_object;
 use function is_string;
 use function MongoDB\is_document;
 use function MongoDB\is_write_concern_acknowledged;
@@ -96,8 +94,8 @@ public function __construct(private string $databaseName, private string $collec
             throw InvalidArgumentException::expectedDocumentType('"collation" option', $this->options['collation']);
         }
 
-        if (isset($this->options['hint']) && ! is_string($this->options['hint']) && ! is_array($this->options['hint']) && ! is_object($this->options['hint'])) {
-            throw InvalidArgumentException::invalidType('"hint" option', $this->options['hint'], ['string', 'array', 'object']);
+        if (isset($this->options['hint']) && ! is_string($this->options['hint']) && ! is_document($this->options['hint'])) {
+            throw InvalidArgumentException::expectedDocumentOrStringType('"hint" option', $this->options['hint']);
         }
 
         if (isset($this->options['session']) && ! $this->options['session'] instanceof Session) {

src/Operation/Distinct.php

@@ -91,7 +91,7 @@ public function __construct(private string $databaseName, private string $collec
         }
 
         if (isset($this->options['hint']) && ! is_string($this->options['hint']) && ! is_document($this->options['hint'])) {
-            throw InvalidArgumentException::invalidType('"hint" option', $this->options['hint'], 'string or array or object');
+            throw InvalidArgumentException::expectedDocumentOrStringType('"hint" option', $this->options['hint']);
         }
 
         if (isset($this->options['maxTimeMS']) && ! is_integer($this->options['maxTimeMS'])) {

src/Operation/Find.php

@@ -33,7 +33,7 @@
 use function assert;
 use function is_array;
 use function is_bool;
 use function is_integer;
 use function is_object;
 use function is_string;
 use function MongoDB\document_to_array;
@@ -195,8 +195,8 @@
             }
         }
 
-        if (isset($this->options['hint']) && ! is_string($this->options['hint']) && ! is_array($this->options['hint']) && ! is_object($this->options['hint'])) {
-            throw InvalidArgumentException::invalidType('"hint" option', $this->options['hint'], 'string or array or object');
+        if (isset($this->options['hint']) && ! is_string($this->options['hint']) && ! is_document($this->options['hint'])) {
+            throw InvalidArgumentException::expectedDocumentOrStringType('"hint" option', $this->options['hint']);
         }
 
         if (isset($this->options['limit']) && ! is_integer($this->options['limit'])) {

src/Operation/FindAndModify.php

@@ -151,8 +151,8 @@ public function __construct(private string $databaseName, private string $collec
             throw InvalidArgumentException::expectedDocumentType('"fields" option', $options['fields']);
         }
 
-        if (isset($options['hint']) && ! is_string($options['hint']) && ! is_array($options['hint']) && ! is_object($options['hint'])) {
-            throw InvalidArgumentException::invalidType('"hint" option', $options['hint'], ['string', 'array', 'object']);
+        if (isset($options['hint']) && ! is_string($options['hint']) && ! is_document($options['hint'])) {
+            throw InvalidArgumentException::expectedDocumentOrStringType('"hint" option', $options['hint']);
         }
 
         if (isset($options['maxTimeMS']) && ! is_integer($options['maxTimeMS'])) {

src/Operation/Update.php

@@ -28,7 +28,6 @@
 
 use function is_array;
 use function is_bool;
-use function is_object;
 use function is_string;
 use function MongoDB\is_document;
 use function MongoDB\is_first_key_operator;
@@ -122,8 +121,8 @@ public function __construct(private string $databaseName, private string $collec
             throw InvalidArgumentException::expectedDocumentType('"collation" option', $options['collation']);
         }
 
-        if (isset($options['hint']) && ! is_string($options['hint']) && ! is_array($options['hint']) && ! is_object($options['hint'])) {
-            throw InvalidArgumentException::invalidType('"hint" option', $options['hint'], ['string', 'array', 'object']);
+        if (isset($options['hint']) && ! is_string($options['hint']) && ! is_document($options['hint'])) {
+            throw InvalidArgumentException::expectedDocumentOrStringType('"hint" option', $options['hint']);
         }
 
         if (! is_bool($options['multi'])) {

tests/TestCase.php

@@ -250,7 +250,7 @@ protected static function getInvalidDocumentCodecValues(): array
      */
     protected static function getInvalidHintValues(): array
     {
-        return [123, 3.14, true];
+        return [123, 3.14, true, PackedArray::fromPHP([])];
     }
 
     /**