PHPLIB-491: Support hint for update command

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

@@ -23,7 +23,7 @@ post: |
   .. versionadded:: 1.4
 ---
 source:
-  file: apiargs-aggregate-option.yaml
+  file: apiargs-common-option.yaml
   ref: hint
 post: |
   .. versionadded:: 1.3

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

@@ -87,18 +87,11 @@ interface: phpmethod
 operation: ~
 optional: true
 ---
-arg_name: option
-name: hint
-type: string|array|object
-description: |
-  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.
-
+source:
+  file: apiargs-common-option.yaml
+  ref: hint
+post: |
   .. versionadded:: 1.2
-interface: phpmethod
-operation: ~
-optional: true
 ---
 arg_name: option
 name: maxAwaitTimeMS

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

@@ -19,8 +19,10 @@ source:
   ref: comment
 ---
 source:
-  file: apiargs-MongoDBCollection-method-find-option.yaml
+  file: apiargs-common-option.yaml
   ref: hint
+post: |
+  .. versionadded:: 1.2
 ---
 source:
   file: apiargs-common-option.yaml

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

@@ -10,6 +10,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.2+ and will result in an exception at
+  execution time if specified for an older server version.
+
+  .. versionadded:: 1.6
+---
 source:
   file: apiargs-common-option.yaml
   ref: session

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

@@ -16,6 +16,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.2+ and will result in an exception at
+  execution time if specified for an older server version.
+
+  .. versionadded:: 1.6
+---
 source:
   file: apiargs-common-option.yaml
   ref: session

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

@@ -16,6 +16,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.2+ and will result in an exception at
+  execution time if specified for an older server version.
+
+  .. versionadded:: 1.6
+---
 source:
   file: apiargs-common-option.yaml
   ref: session

docs/includes/apiargs-MongoDBDatabase-method-aggregate-option.yaml

@@ -19,7 +19,7 @@ source:
   ref: explain
 ---
 source:
-  file: apiargs-aggregate-option.yaml
+  file: apiargs-common-option.yaml
   ref: hint
 ---
 source:

docs/includes/apiargs-aggregate-option.yaml

@@ -49,15 +49,4 @@ description: |
 interface: phpmethod
 operation: ~
 optional: true
----
-arg_name: option
-name: hint
-type: string|array|object
-description: |
-  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.
-interface: phpmethod
-operation: ~
-optional: true
 ...

docs/includes/apiargs-common-option.yaml

@@ -16,6 +16,17 @@ operation: ~
 optional: true
 ---
 arg_name: option
+name: hint
+type: string|array|object
+description: |
+  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.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
 name: maxTimeMS
 type: integer
 description: |

src/Exception/UnsupportedException.php

@@ -49,6 +49,16 @@ public static function explainNotSupported()
         return new static('Explain is not supported by the server executing this operation');
     }
 
+    /**
+     * Thrown when a command's hint option is not supported by a server.
+     *
+     * @return self
+     */
+    public static function hintNotSupported()
+    {
+        return new static('Hint is not supported by the server executing this operation');
+    }
+
     /**
      * Thrown when a command's readConcern option is not supported by a server.
      *

src/Operation/ReplaceOne.php

@@ -55,6 +55,13 @@ class ReplaceOne implements Executable
      *    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.2 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/Update.php

@@ -28,6 +28,7 @@
 use function is_array;
 use function is_bool;
 use function is_object;
+use function is_string;
 use function MongoDB\is_first_key_operator;
 use function MongoDB\is_pipeline;
 use function MongoDB\server_supports_feature;
@@ -52,6 +53,9 @@ class Update implements Executable, Explainable
     /** @var integer */
     private static $wireVersionForDocumentLevelValidation = 4;
 
+    /** @var integer */
+    private static $wireVersionForHint = 8;
+
     /** @var string */
     private $databaseName;
 
@@ -89,6 +93,13 @@ class Update 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.2 and will result in an
+     *    exception at execution time if used.
+     *
      *  * multi (boolean): When true, updates all documents matching the query.
      *    This option cannot be true if the $update argument is a replacement
      *    document (i.e. contains no update operators). The default is false.
@@ -137,6 +148,10 @@ public function __construct($databaseName, $collectionName, $filter, $update, ar
             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 (! is_bool($options['multi'])) {
             throw InvalidArgumentException::invalidType('"multi" option', $options['multi'], 'boolean');
         }
@@ -187,6 +202,10 @@ public function execute(Server $server)
             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();
@@ -261,8 +280,10 @@ private function createUpdateOptions()
             'upsert' => $this->options['upsert'],
         ];
 
-        if (isset($this->options['arrayFilters'])) {
-            $updateOptions['arrayFilters'] = $this->options['arrayFilters'];
+        foreach (['arrayFilters', 'hint'] as $option) {
+            if (isset($this->options[$option])) {
+                $updateOptions[$option] = $this->options[$option];
+            }
         }
 
         if (isset($this->options['collation'])) {

src/Operation/UpdateMany.php

@@ -61,6 +61,13 @@ class UpdateMany 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.2 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/UpdateOne.php

@@ -61,6 +61,13 @@ class UpdateOne 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.2 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.