PHPLIB-539: Allow hinting for delete

docs/includes/apiargs-MongoDBCollection-method-deleteMany-option.yaml

@@ -2,6 +2,15 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: collation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: hint
+post: |
+  This option is available in MongoDB 4.4+ and will result in an exception at
+  execution time if specified for an older server version.
+
+  .. versionadded:: 1.7
+---
 source:
   file: apiargs-common-option.yaml
   ref: session

docs/includes/apiargs-MongoDBCollection-method-deleteOne-option.yaml

@@ -2,6 +2,15 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: collation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: hint
+post: |
+  This option is available in MongoDB 4.4+ and will result in an exception at
+  execution time if specified for an older server version.
+
+  .. versionadded:: 1.7
+---
 source:
   file: apiargs-common-option.yaml
   ref: session

src/Operation/Delete.php

@@ -27,6 +27,7 @@ use MongoDB\Exception\InvalidArgumentException;
 use MongoDB\Exception\UnsupportedException;
 use function is_array;
 use function is_object;
+use function is_string;
 use function MongoDB\server_supports_feature;
 
 /**
@@ -43,6 +44,9 @@ class Delete implements Executable, Explainable
     /** @var integer */
     private static $wireVersionForCollation = 5;
 
+    /** @var int */
+    private static $wireVersionForHint = 9;
+
     /** @var string */
     private $databaseName;
 
@@ -68,6 +72,13 @@ class Delete implements Executable, Explainable
      *    This is not supported for server versions < 3.4 and will result in an
      *    exception at execution time if used.
      *
+     *  * hint (string|document): The index to use. Specify either the index
+     *    name as a string or the index key pattern as a document. If specified,
+     *    then the query system will only consider plans using the hinted index.
+     *
+     *    This is not supported for server versions < 4.4 and will result in an
+     *    exception at execution time if used.
+     *
      *  * session (MongoDB\Driver\Session): Client session.
      *
      *    Sessions are not supported for server versions < 3.6.
@@ -97,6 +108,10 @@ class Delete implements Executable, Explainable
             throw InvalidArgumentException::invalidType('"collation" option', $options['collation'], 'array or object');
         }
 
+        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['session']) && ! $options['session'] instanceof Session) {
             throw InvalidArgumentException::invalidType('"session" option', $options['session'], Session::class);
         }
@@ -130,6 +145,10 @@ class Delete implements Executable, Explainable
             throw UnsupportedException::collationNotSupported();
         }
 
+        if (isset($this->options['hint']) && ! server_supports_feature($server, self::$wireVersionForHint)) {
+            throw UnsupportedException::hintNotSupported();
+        }
+
         $inTransaction = isset($this->options['session']) && $this->options['session']->isInTransaction();
         if ($inTransaction && isset($this->options['writeConcern'])) {
             throw UnsupportedException::writeConcernNotSupportedInTransaction();
@@ -170,6 +189,10 @@ class Delete implements Executable, Explainable
             $deleteOptions['collation'] = (object) $this->options['collation'];
         }
 
+        if (isset($this->options['hint'])) {
+            $deleteOptions['hint'] = $this->options['hint'];
+        }
+
         return $deleteOptions;
     }
 

src/Operation/DeleteMany.php

@@ -45,6 +45,13 @@ class DeleteMany implements Executable, Explainable
      *    This is not supported for server versions < 3.4 and will result in an
      *    exception at execution time if used.
      *
+     *  * hint (string|document): The index to use. Specify either the index
+     *    name as a string or the index key pattern as a document. If specified,
+     *    then the query system will only consider plans using the hinted index.
+     *
+     *    This is not supported for server versions < 4.4 and will result in an
+     *    exception at execution time if used.
+     *
      *  * session (MongoDB\Driver\Session): Client session.
      *
      *    Sessions are not supported for server versions < 3.6.

src/Operation/DeleteOne.php

@@ -45,6 +45,13 @@ class DeleteOne implements Executable, Explainable
      *    This is not supported for server versions < 3.4 and will result in an
      *    exception at execution time if used.
      *
+     *  * hint (string|document): The index to use. Specify either the index
+     *    name as a string or the index key pattern as a document. If specified,
+     *    then the query system will only consider plans using the hinted index.
+     *
+     *    This is not supported for server versions < 4.4 and will result in an
+     *    exception at execution time if used.
+     *
      *  * session (MongoDB\Driver\Session): Client session.
      *
      *    Sessions are not supported for server versions < 3.6.