PHPLIB-266 Support passing index hint to aggregations

Author: kvwalker

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

@@ -34,6 +34,10 @@ post: |
   Document validation requires MongoDB 3.2 or later: if you are using an earlier
   version of MongoDB, this option will be ignored.
 ---
+source:
+  file: apiargs-MongoDBCollection-method-find-option.yaml
+  ref: hint
+---
 source:
   file: apiargs-common-option.yaml
   ref: maxTimeMS

src/Operation/Aggregate.php

@@ -74,6 +74,10 @@ class Aggregate 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.
+     *
      *  * maxTimeMS (integer): The maximum amount of time to allow the query to
      *    run.
      *
@@ -146,6 +150,10 @@ public function __construct($databaseName, $collectionName, array $pipeline, arr
             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 or array or object');
+        }
+
         if (isset($options['maxTimeMS']) && ! is_integer($options['maxTimeMS'])) {
             throw InvalidArgumentException::invalidType('"maxTimeMS" option', $options['maxTimeMS'], 'integer');
         }
@@ -272,6 +280,10 @@ private function createCommand(Server $server, $isCursorSupported)
             $cmd['collation'] = (object) $this->options['collation'];
         }
 
+        if (isset($this->options['hint'])) {
+            $cmd['hint'] = $this->options['hint'];
+        }
+
         if (isset($this->options['maxTimeMS'])) {
             $cmd['maxTimeMS'] = $this->options['maxTimeMS'];
         }

tests/Operation/AggregateTest.php

@@ -44,6 +44,10 @@ public function provideInvalidConstructorOptions()
             $options[][] = ['collation' => $value];
         }
 
+        foreach ($this->getInvalidHintValues() as $value) {
+            $options[][] = ['hint' => $value];
+        }
+
         foreach ($this->getInvalidIntegerValues() as $value) {
             $options[][] = ['maxTimeMS' => $value];
         }
@@ -98,4 +102,9 @@ public function testConstructorTypeMapOptionRequiresUseCursor()
             ['typeMap' => ['root' => 'array'], 'useCursor' => false]
         );
     }
+
+    private function getInvalidHintValues()
+    {
+        return [123, 3.14, true];
+    }
 }