Merge pull request #497

src/Exception/UnsupportedException.php

@@ -39,6 +39,16 @@ class UnsupportedException extends RuntimeException
         return new static('Collations are not supported by the server executing this operation');
     }
 
+   /**
+     * Thrown when explain is not supported by a server.
+     *
+     * @return self
+     */
+    public static function explainNotSupported()
+    {
+        return new static('Explain is not supported by the server executing this operation');
+    }
+
     /**
      * Thrown when a command's readConcern option is not supported by a server.
      *

src/Operation/Count.php

@@ -34,7 +34,7 @@ use MongoDB\Exception\UnsupportedException;
  * @see \MongoDB\Collection::count()
  * @see http://docs.mongodb.org/manual/reference/command/count/
  */
-class Count implements Executable
+class Count implements Executable, Explainable
 {
     private static $wireVersionForCollation = 5;
     private static $wireVersionForReadConcern = 4;
@@ -151,7 +151,7 @@ class Count implements Executable
             throw UnsupportedException::readConcernNotSupported();
         }
 
-        $cursor = $server->executeReadCommand($this->databaseName, $this->createCommand(), $this->createOptions());
+        $cursor = $server->executeReadCommand($this->databaseName, new Command($this->createCommandDocument()), $this->createOptions());
         $result = current($cursor->toArray());
 
         // Older server versions may return a float
@@ -162,12 +162,17 @@ class Count implements Executable
         return (integer) $result->n;
     }
 
+    public function getCommandDocument(Server $server)
+    {
+        return $this->createCommandDocument();
+    }
+
     /**
-     * Create the count command.
+     * Create the count command document.
      *
-     * @return Command
+     * @return array
      */
-    private function createCommand()
+    private function createCommandDocument()
     {
         $cmd = ['count' => $this->collectionName];
 
@@ -189,7 +194,7 @@ class Count implements Executable
             }
         }
 
-        return new Command($cmd);
+        return $cmd;
     }
 
     /**

src/Operation/Delete.php

@@ -35,7 +35,7 @@ use MongoDB\Exception\UnsupportedException;
  * @internal
  * @see http://docs.mongodb.org/manual/reference/command/delete/
  */
-class Delete implements Executable
+class Delete implements Executable, Explainable
 {
     private static $wireVersionForCollation = 5;
 
@@ -117,18 +117,42 @@ class Delete implements Executable
             throw UnsupportedException::collationNotSupported();
         }
 
+        $bulk = new Bulk();
+        $bulk->delete($this->filter, $this->createDeleteOptions());
+
+        $writeResult = $server->executeBulkWrite($this->databaseName . '.' . $this->collectionName, $bulk, $this->createExecuteOptions());
+
+        return new DeleteResult($writeResult);
+    }
+
+    public function getCommandDocument(Server $server)
+    {
+        $cmd = ['delete' => $this->collectionName, 'deletes' => [['q' => $this->filter] + $this->createDeleteOptions()]];
+
+        if (isset($this->options['writeConcern'])) {
+            $cmd['writeConcern'] = $this->options['writeConcern'];
+        }
+
+        return $cmd;
+    }
+
+    /**
+     * Create options for the delete command.
+     *
+     * Note that these options are different from the bulk write options, which
+     * are created in createExecuteOptions().
+     *
+     * @return array
+     */
+    private function createDeleteOptions()
+    {
         $deleteOptions = ['limit' => $this->limit];
 
         if (isset($this->options['collation'])) {
             $deleteOptions['collation'] = (object) $this->options['collation'];
         }
 
-        $bulk = new Bulk();
-        $bulk->delete($this->filter, $deleteOptions);
-
-        $writeResult = $server->executeBulkWrite($this->databaseName . '.' . $this->collectionName, $bulk, $this->createOptions());
-
-        return new DeleteResult($writeResult);
+        return $deleteOptions;
     }
 
     /**
@@ -137,7 +161,7 @@ class Delete implements Executable
      * @see http://php.net/manual/en/mongodb-driver-server.executebulkwrite.php
      * @return array
      */
-    private function createOptions()
+    private function createExecuteOptions()
     {
         $options = [];
 

src/Operation/DeleteMany.php

@@ -30,7 +30,7 @@ use MongoDB\Exception\UnsupportedException;
  * @see \MongoDB\Collection::deleteOne()
  * @see http://docs.mongodb.org/manual/reference/command/delete/
  */
-class DeleteMany implements Executable
+class DeleteMany implements Executable, Explainable
 {
     private $delete;
 
@@ -74,4 +74,9 @@ class DeleteMany implements Executable
     {
         return $this->delete->execute($server);
     }
+
+    public function getCommandDocument(Server $server)
+    {
+        return $this->delete->getCommandDocument($server);
+    }
 }

src/Operation/DeleteOne.php

@@ -30,7 +30,7 @@ use MongoDB\Exception\UnsupportedException;
  * @see \MongoDB\Collection::deleteOne()
  * @see http://docs.mongodb.org/manual/reference/command/delete/
  */
-class DeleteOne implements Executable
+class DeleteOne implements Executable, Explainable
 {
     private $delete;
 
@@ -74,4 +74,9 @@ class DeleteOne implements Executable
     {
         return $this->delete->execute($server);
     }
+
+    public function getCommandDocument(Server $server)
+    {
+        return $this->delete->getCommandDocument($server);
+    }
 }

src/Operation/Distinct.php

@@ -34,7 +34,7 @@ use MongoDB\Exception\UnsupportedException;
  * @see \MongoDB\Collection::distinct()
  * @see http://docs.mongodb.org/manual/reference/command/distinct/
  */
-class Distinct implements Executable
+class Distinct implements Executable, Explainable
 {
     private static $wireVersionForCollation = 5;
     private static $wireVersionForReadConcern = 4;
@@ -133,7 +133,7 @@ class Distinct implements Executable
             throw UnsupportedException::readConcernNotSupported();
         }
 
-        $cursor = $server->executeReadCommand($this->databaseName, $this->createCommand(), $this->createOptions());
+        $cursor = $server->executeReadCommand($this->databaseName, new Command($this->createCommandDocument()), $this->createOptions());
         $result = current($cursor->toArray());
 
         if ( ! isset($result->values) || ! is_array($result->values)) {
@@ -143,12 +143,17 @@ class Distinct implements Executable
         return $result->values;
     }
 
+    public function getCommandDocument(Server $server)
+    {
+        return $this->createCommandDocument();
+    }
+
     /**
-     * Create the distinct command.
+     * Create the distinct command document.
      *
-     * @return Command
+     * @return array
      */
-    private function createCommand()
+    private function createCommandDocument()
     {
         $cmd = [
             'distinct' => $this->collectionName,
@@ -167,7 +172,7 @@ class Distinct implements Executable
             $cmd['maxTimeMS'] = $this->options['maxTimeMS'];
         }
 
-        return new Command($cmd);
+        return $cmd;
     }
 
     /**

src/Operation/Explain.php

+<?php
+/*
+ * Copyright 2018 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
+ *
+ *   http://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\Operation;
+
+use MongoDB\Driver\Command;
+use MongoDB\Driver\Server;
+use MongoDB\Exception\UnsupportedException;
+use MongoDB\Exception\InvalidArgumentException;
+use MongoDB\Model\BSONDocument;
+
+/**
+ * Operation for the explain command.
+ *
+ * @api
+ * @see \MongoDB\Collection::explain()
+ * @see http://docs.mongodb.org/manual/reference/command/explain/
+ */
+class Explain implements Executable
+{
+    const VERBOSITY_ALL_PLANS = 'allPlansExecution';
+    const VERBOSITY_EXEC_STATS = 'executionStats';
+    const VERBOSITY_QUERY = 'queryPlanner';
+
+    private static $wireVersionForExplain = 2;
+    private static $wireVersionForDistinct = 4;
+    private static $wireVersionForFindAndModify = 4;
+
+    private $databaseName;
+    private $explainable;
+    private $options;
+
+    /**
+     * Constructs an explain command for explainable operations.
+     *
+     * Supported options:
+     *
+     *  * verbosity (string): The mode in which the explain command will be run.
+     *
+     *  * typeMap (array): Type map for BSON deserialization. This will be used
+     *    used for the returned command result document.
+     *
+     * @param string $databaseName      Database name
+     * @param Explainable $explainable  Operation to explain
+     * @param array  $options           Command options
+     * @throws InvalidArgumentException for parameter/option parsing errors
+     */
+    public function __construct($databaseName, Explainable $explainable, array $options = [])
+    {
+        if (isset($options['verbosity']) && ! is_string($options['verbosity'])) {
+            throw InvalidArgumentException::invalidType('"verbosity" option', $options['verbosity'], 'string');
+        }
+
+        if (isset($options['typeMap']) && ! is_array($options['typeMap'])) {
+            throw InvalidArgumentException::invalidType('"typeMap" option', $options['typeMap'], 'array');
+        }
+
+        $this->databaseName = $databaseName;
+        $this->explainable = $explainable;
+        $this->options = $options;
+    }
+
+    public function execute(Server $server)
+    {
+        if (! \MongoDB\server_supports_feature($server, self::$wireVersionForExplain)) {
+            throw UnsupportedException::explainNotSupported();
+        }
+
+        if ($this->explainable instanceof Distinct && ! \MongoDB\server_supports_feature($server, self::$wireVersionForDistinct)) {
+            throw UnsupportedException::explainNotSupported();
+        }
+
+        if ($this->isFindAndModify($this->explainable) && ! \MongoDB\server_supports_feature($server, self::$wireVersionForFindAndModify)) {
+            throw UnsupportedException::explainNotSupported();
+        }
+
+        $cmd = ['explain' => $this->explainable->getCommandDocument($server)];
+
+        if (isset($this->options['verbosity'])) {
+            $cmd['verbosity'] = $this->options['verbosity'];
+        }
+
+        $cursor = $server->executeCommand($this->databaseName, new Command($cmd));
+
+        if (isset($this->options['typeMap'])) {
+            $cursor->setTypeMap($this->options['typeMap']);
+        }
+
+        return current($cursor->toArray());
+    }
+
+    private function isFindAndModify($explainable)
+    {
+        if ($explainable instanceof FindAndModify || $explainable instanceof FindOneAndDelete || $explainable instanceof FindOneAndReplace || $explainable instanceof FindOneAndUpdate) {
+            return true;
+        }
+        return false;
+    }
+}

src/Operation/Explainable.php

+<?php
+/*
+ * Copyright 2018 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
+ *
+ *   http://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\Operation;
+
+use MongoDB\Driver\Server;
+
+/**
+ * Explainable interface for explainable operations (count, distinct, find,
+ * findAndModify, delete, and update).
+ *
+ * @internal
+ */
+interface Explainable extends Executable
+{
+    function getCommandDocument(Server $server);
+}

src/Operation/Find.php

@@ -26,7 +26,7 @@ use MongoDB\Driver\Session;
 use MongoDB\Driver\Exception\RuntimeException as DriverRuntimeException;
 use MongoDB\Exception\InvalidArgumentException;
 use MongoDB\Exception\UnsupportedException;
-
+use MongoDB\Model\BSONDocument;
 /**
  * Operation for the find command.
  *
@@ -35,7 +35,7 @@ use MongoDB\Exception\UnsupportedException;
  * @see http://docs.mongodb.org/manual/tutorial/query-documents/
  * @see http://docs.mongodb.org/manual/reference/operator/query-modifier/
  */
-class Find implements Executable
+class Find implements Executable, Explainable
 {
     const NON_TAILABLE = 1;
     const TAILABLE = 2;
@@ -284,7 +284,7 @@ class Find implements Executable
             throw UnsupportedException::readConcernNotSupported();
         }
 
-        $cursor = $server->executeQuery($this->databaseName . '.' . $this->collectionName, $this->createQuery(), $this->createOptions());
+        $cursor = $server->executeQuery($this->databaseName . '.' . $this->collectionName, new Query($this->filter, $this->createQueryOptions()), $this->createExecuteOptions());
 
         if (isset($this->options['typeMap'])) {
             $cursor->setTypeMap($this->options['typeMap']);
@@ -293,13 +293,58 @@ class Find implements Executable
         return $cursor;
     }
 
+    public function getCommandDocument(Server $server)
+    {
+        return $this->createCommandDocument();
+    }
+
+    /**
+     * Construct a command document for Find
+     */
+    private function createCommandDocument()
+    {
+        $cmd = ['find' => $this->collectionName, 'filter' => (object) $this->filter];
+
+        $options = $this->createQueryOptions();
+
+        if (empty($options)) {
+            return $cmd;
+        }
+
+        // maxAwaitTimeMS is a Query level option so should not be considered here
+        unset($options['maxAwaitTimeMS']);
+
+        $modifierFallback = [
+            ['allowPartialResults' , 'partial'],
+            ['comment' , '$comment'],
+            ['hint' , '$hint'],
+            ['maxScan' , '$maxScan'],
+            ['max' , '$max'],
+            ['maxTimeMS' , '$maxTimeMS'],
+            ['min' , '$min'],
+            ['returnKey' , '$returnKey'],
+            ['showRecordId' , '$showDiskLoc'],
+            ['sort' , '$orderby'],
+            ['snapshot' , '$snapshot'],
+        ];
+
+        foreach ($modifierFallback as $modifier) {
+            if ( ! isset($options[$modifier[0]]) && isset($options['modifiers'][$modifier[1]])) {
+                $options[$modifier[0]] = $options['modifiers'][$modifier[1]];
+            }
+        }
+        unset($options['modifiers']);
+
+        return $cmd + $options;
+    }
+
     /**
      * Create options for executing the command.
      *
      * @see http://php.net/manual/en/mongodb-driver-server.executequery.php
      * @return array
      */
-    private function createOptions()
+    private function createExecuteOptions()
     {
         $options = [];
 
@@ -315,11 +360,14 @@ class Find implements Executable
     }
 
     /**
-     * Create the find query.
+     * Create options for the find query.
+     *
+     * Note that these are separate from the options for executing the command,
+     * which are created in createExecuteOptions().
      *
-     * @return Query
+     * @return array
      */
-    private function createQuery()
+    private function createQueryOptions()
     {
         $options = [];
 
@@ -351,6 +399,6 @@ class Find implements Executable
             $options['modifiers'] = $modifiers;
         }
 
-        return new Query($this->filter, $options);
+        return $options;
     }
 }

src/Operation/FindAndModify.php

@@ -35,7 +35,7 @@ use MongoDB\Exception\UnsupportedException;
  * @internal
  * @see http://docs.mongodb.org/manual/reference/command/findAndModify/
  */
-class FindAndModify implements Executable
+class FindAndModify implements Executable, Explainable
 {
     private static $wireVersionForArrayFilters = 6;
     private static $wireVersionForCollation = 5;
@@ -210,7 +210,7 @@ class FindAndModify implements Executable
             throw UnsupportedException::writeConcernNotSupported();
         }
 
-        $cursor = $server->executeReadWriteCommand($this->databaseName, $this->createCommand($server), $this->createOptions());
+        $cursor = $server->executeReadWriteCommand($this->databaseName, new Command($this->createCommandDocument($server)), $this->createOptions());
         $result = current($cursor->toArray());
 
         if ( ! isset($result->value)) {
@@ -239,13 +239,17 @@ class FindAndModify implements Executable
         return $result->value;
     }
 
+    public function getCommandDocument(Server $server)
+    {
+        return $this->createCommandDocument($server);
+    }
+
     /**
-     * Create the findAndModify command.
+     * Create the findAndModify command document.
      *
-     * @param Server $server
-     * @return Command
+     * @return array
      */
-    private function createCommand(Server $server)
+    private function createCommandDocument(Server $server)
     {
         $cmd = ['findAndModify' => $this->collectionName];
 
@@ -274,7 +278,7 @@ class FindAndModify implements Executable
             $cmd['bypassDocumentValidation'] = $this->options['bypassDocumentValidation'];
         }
 
-        return new Command($cmd);
+        return $cmd;
     }
 
     /**

src/Operation/FindOne.php

@@ -30,7 +30,7 @@ use MongoDB\Exception\UnsupportedException;
  * @see http://docs.mongodb.org/manual/tutorial/query-documents/
  * @see http://docs.mongodb.org/manual/reference/operator/query-modifier/
  */
-class FindOne implements Executable
+class FindOne implements Executable, Explainable
 {
     private $find;
 
@@ -126,4 +126,9 @@ class FindOne implements Executable
 
         return ($document === false) ? null : $document;
     }
+
+    public function getCommandDocument(Server $server)
+    {
+        return $this->find->getCommandDocument($server);
+    }
 }

src/Operation/FindOneAndDelete.php

@@ -29,7 +29,7 @@ use MongoDB\Exception\UnsupportedException;
  * @see \MongoDB\Collection::findOneAndDelete()
  * @see http://docs.mongodb.org/manual/reference/command/findAndModify/
  */
-class FindOneAndDelete implements Executable
+class FindOneAndDelete implements Executable, Explainable
 {
     private $findAndModify;
 
@@ -105,4 +105,9 @@ class FindOneAndDelete implements Executable
     {
         return $this->findAndModify->execute($server);
     }
+
+    public function getCommandDocument(Server $server)
+    {
+        return $this->findAndModify->getCommandDocument($server);
+    }
 }

src/Operation/FindOneAndReplace.php

@@ -29,7 +29,7 @@ use MongoDB\Exception\UnsupportedException;
  * @see \MongoDB\Collection::findOneAndReplace()
  * @see http://docs.mongodb.org/manual/reference/command/findAndModify/
  */
-class FindOneAndReplace implements Executable
+class FindOneAndReplace implements Executable, Explainable
 {
     const RETURN_DOCUMENT_BEFORE = 1;
     const RETURN_DOCUMENT_AFTER = 2;
@@ -148,4 +148,9 @@ class FindOneAndReplace implements Executable
     {
         return $this->findAndModify->execute($server);
     }
+
+    public function getCommandDocument(Server $server)
+    {
+        return $this->findAndModify->getCommandDocument($server);
+    }
 }

src/Operation/FindOneAndUpdate.php

@@ -29,7 +29,7 @@ use MongoDB\Exception\UnsupportedException;
  * @see \MongoDB\Collection::findOneAndUpdate()
  * @see http://docs.mongodb.org/manual/reference/command/findAndModify/
  */
-class FindOneAndUpdate implements Executable
+class FindOneAndUpdate implements Executable, Explainable
 {
     const RETURN_DOCUMENT_BEFORE = 1;
     const RETURN_DOCUMENT_AFTER = 2;
@@ -151,4 +151,9 @@ class FindOneAndUpdate implements Executable
     {
         return $this->findAndModify->execute($server);
     }
+
+    public function getCommandDocument(Server $server)
+    {
+        return $this->findAndModify->getCommandDocument($server);
+    }
 }

src/Operation/Update.php

@@ -35,7 +35,7 @@ use MongoDB\Exception\UnsupportedException;
  * @internal
  * @see http://docs.mongodb.org/manual/reference/command/update/
  */
-class Update implements Executable
+class Update implements Executable, Explainable
 {
     private static $wireVersionForArrayFilters = 6;
     private static $wireVersionForCollation = 5;
@@ -167,19 +167,6 @@ class Update implements Executable
             throw UnsupportedException::collationNotSupported();
         }
 
-        $updateOptions = [
-            'multi' => $this->options['multi'],
-            'upsert' => $this->options['upsert'],
-        ];
-
-        if (isset($this->options['arrayFilters'])) {
-            $updateOptions['arrayFilters'] = $this->options['arrayFilters'];
-        }
-
-        if (isset($this->options['collation'])) {
-            $updateOptions['collation'] = (object) $this->options['collation'];
-        }
-
         $bulkOptions = [];
 
         if (isset($this->options['bypassDocumentValidation']) && \MongoDB\server_supports_feature($server, self::$wireVersionForDocumentLevelValidation)) {
@@ -187,20 +174,35 @@ class Update implements Executable
         }
 
         $bulk = new Bulk($bulkOptions);
-        $bulk->update($this->filter, $this->update, $updateOptions);
+        $bulk->update($this->filter, $this->update, $this->createUpdateOptions());
 
-        $writeResult = $server->executeBulkWrite($this->databaseName . '.' . $this->collectionName, $bulk, $this->createOptions());
+        $writeResult = $server->executeBulkWrite($this->databaseName . '.' . $this->collectionName, $bulk, $this->createExecuteOptions());
 
         return new UpdateResult($writeResult);
     }
 
+    public function getCommandDocument(Server $server)
+    {
+        $cmd = ['update' => $this->collectionName, 'updates' => [['q' => $this->filter, 'u' => $this->update] + $this->createUpdateOptions()]];
+
+        if (isset($this->options['writeConcern'])) {
+            $cmd['writeConcern'] = $this->options['writeConcern'];
+        }
+
+        if (isset($this->options['bypassDocumentValidation']) && \MongoDB\server_supports_feature($server, self::$wireVersionForDocumentLevelValidation)) {
+            $cmd['bypassDocumentValidation'] = $this->options['bypassDocumentValidation'];
+        }
+
+        return $cmd;
+    }
+
     /**
      * Create options for executing the bulk write.
      *
      * @see http://php.net/manual/en/mongodb-driver-server.executebulkwrite.php
      * @return array
      */
-    private function createOptions()
+    private function createExecuteOptions()
     {
         $options = [];
 
@@ -214,4 +216,30 @@ class Update implements Executable
 
         return $options;
     }
+
+    /**
+     * Create options for the update command.
+     *
+     * Note that these options are different from the bulk write options, which
+     * are created in createExecuteOptions().
+     *
+     * @return array
+     */
+    private function createUpdateOptions()
+    {
+        $updateOptions = [
+            'multi' => $this->options['multi'],
+            'upsert' => $this->options['upsert'],
+        ];
+
+        if (isset($this->options['arrayFilters'])) {
+            $updateOptions['arrayFilters'] = $this->options['arrayFilters'];
+        }
+
+        if (isset($this->options['collation'])) {
+            $updateOptions['collation'] = (object) $this->options['collation'];
+        }
+
+        return $updateOptions;
+    }
 }

src/Operation/UpdateMany.php

@@ -30,7 +30,7 @@ use MongoDB\Exception\UnsupportedException;
  * @see \MongoDB\Collection::updateMany()
  * @see http://docs.mongodb.org/manual/reference/command/update/
  */
-class UpdateMany implements Executable
+class UpdateMany implements Executable, Explainable
 {
     private $update;
 
@@ -104,4 +104,9 @@ class UpdateMany implements Executable
     {
         return $this->update->execute($server);
     }
+
+    public function getCommandDocument(Server $server)
+    {
+        return $this->update->getCommandDocument($server);
+    }
 }

src/Operation/UpdateOne.php

@@ -30,7 +30,7 @@ use MongoDB\Exception\UnsupportedException;
  * @see \MongoDB\Collection::updateOne()
  * @see http://docs.mongodb.org/manual/reference/command/update/
  */
-class UpdateOne implements Executable
+class UpdateOne implements Executable, Explainable
 {
     private $update;
 
@@ -104,4 +104,9 @@ class UpdateOne implements Executable
     {
         return $this->update->execute($server);
     }
+
+    public function getCommandDocument(Server $server)
+    {
+        return $this->update->getCommandDocument($server);
+    }
 }

tests/Operation/ExplainFunctionalTest.php

+<?php
+
+namespace MongoDB\Tests\Operation;
+
+use MongoDB\Driver\BulkWrite;
+use MongoDB\Collection;
+use MongoDB\Operation\Count;
+use MongoDB\Operation\CreateCollection;
+use MongoDB\Operation\Distinct;
+use MongoDB\Operation\Delete;
+use MongoDB\Operation\DeleteMany;
+use MongoDB\Operation\DeleteOne;
+use MongoDB\Operation\Explain;
+use MongoDB\Operation\Find;
+use MongoDB\Operation\FindAndModify;
+use MongoDB\Operation\FindOne;
+use MongoDB\Operation\FindOneAndDelete;
+use MongoDB\Operation\FindOneAndReplace;
+use MongoDB\Operation\FindOneAndUpdate;
+use MongoDB\Operation\Update;
+use MongoDB\Operation\UpdateMany;
+use MongoDB\Operation\UpdateOne;
+use MongoDB\Tests\CommandObserver;
+use stdClass;
+
+class ExplainFunctionalTest extends FunctionalTestCase
+{
+    public function setUp()
+    {
+        parent::setUp();
+        if (version_compare($this->getServerVersion(), '3.0.0', '<')) {
+            $this->markTestSkipped('Explain command is not supported');
+        }
+    }
+
+    /**
+     * @dataProvider provideVerbosityInformation
+     */
+    public function testCount($verbosity, $executionStatsExpected, $allPlansExecutionExpected)
+    {
+        $this->createFixtures(3);
+
+        $operation = new Count($this->getDatabaseName(), $this->getCollectionName(), ['x' => ['$gte' => 1]], []);
+
+        $explainOperation = new Explain($this->getDatabaseName(), $operation, ['verbosity' => $verbosity, 'typeMap' => ['root' => 'array', 'document' => 'array']]);
+        $result = $explainOperation->execute($this->getPrimaryServer());
+
+        $this->assertExplainResult($result, $executionStatsExpected, $allPlansExecutionExpected);
+    }
+
+    /**
+     * @dataProvider provideVerbosityInformation
+     */
+    public function testDelete($verbosity, $executionStatsExpected, $allPlansExecutionExpected)
+    {
+        $this->createFixtures(3);
+
+        $filter = ['_id' => 1];
+
+        $operation = new Delete($this->getDatabaseName(), $this->getCollectionName(), $filter, 1);
+
+        $explainOperation = new Explain($this->getDatabaseName(), $operation, ['verbosity' => $verbosity, 'typeMap' => ['root' => 'array', 'document' => 'array']]);
+        $result = $explainOperation->execute($this->getPrimaryServer());
+
+        $this->assertExplainResult($result, $executionStatsExpected, $allPlansExecutionExpected);
+    }
+
+    /**
+     * @dataProvider provideVerbosityInformation
+     */
+    public function testDeleteMany($verbosity, $executionStatsExpected, $allPlansExecutionExpected)
+    {
+        $this->createFixtures(3);
+
+        $filter = ['_id' => ['$gt' => 1]];
+
+        $operation = new DeleteMany($this->getDatabaseName(), $this->getCollectionName(), $filter);
+
+        $explainOperation = new Explain($this->getDatabaseName(), $operation, ['verbosity' => $verbosity, 'typeMap' => ['root' => 'array', 'document' => 'array']]);
+        $result = $explainOperation->execute($this->getPrimaryServer());
+
+        $this->assertExplainResult($result, $executionStatsExpected, $allPlansExecutionExpected);
+    }
+
+    /**
+     * @dataProvider provideVerbosityInformation
+     */
+    public function testDeleteOne($verbosity, $executionStatsExpected, $allPlansExecutionExpected)
+    {
+        $this->createFixtures(3);
+
+        $filter = ['_id' => 1];
+
+        $operation = new DeleteOne($this->getDatabaseName(), $this->getCollectionName(), $filter);
+
+        $explainOperation = new Explain($this->getDatabaseName(), $operation, ['verbosity' => $verbosity, 'typeMap' => ['root' => 'array', 'document' => 'array']]);
+        $result = $explainOperation->execute($this->getPrimaryServer());
+
+        $this->assertExplainResult($result, $executionStatsExpected, $allPlansExecutionExpected);
+    }
+
+    /**
+     * @dataProvider provideVerbosityInformation
+     */
+    public function testDistinct($verbosity, $executionStatsExpected, $allPlansExecutionExpected)
+    {
+        if (version_compare($this->getServerVersion(), '3.2.0', '<')) {
+            $this->markTestSkipped('Explaining distinct command requires server version >= 3.2');
+        }
+
+        $operation = new Distinct($this->getDatabaseName(), $this->getCollectionName(), 'x', []);
+
+        $explainOperation = new Explain($this->getDatabaseName(), $operation, ['verbosity' => $verbosity, 'typeMap' => ['root' => 'array', 'document' => 'array']]);
+        $result = $explainOperation->execute($this->getPrimaryServer());
+
+        $this->assertExplainResult($result, $executionStatsExpected, $allPlansExecutionExpected);
+    }
+
+    /**
+     * @dataProvider provideVerbosityInformation
+     */
+    public function testFindAndModify($verbosity, $executionStatsExpected, $allPlansExecutionExpected)
+    {
+        if (version_compare($this->getServerVersion(), '3.2.0', '<')) {
+            $this->markTestSkipped('Explaining findAndModify command requires server version >= 3.2');
+        }
+
+        $operation = new FindAndModify($this->getDatabaseName(), $this->getCollectionName(), ['remove' => true]);
+
+        $explainOperation = new Explain($this->getDatabaseName(), $operation, ['verbosity' => $verbosity, 'typeMap' => ['root' => 'array', 'document' => 'array']]);
+        $result = $explainOperation->execute($this->getPrimaryServer());
+
+        $this->assertExplainResult($result, $executionStatsExpected, $allPlansExecutionExpected);
+    }
+
+    /**
+     * @dataProvider provideVerbosityInformation
+     */
+    public function testFind($verbosity, $executionStatsExpected, $allPlansExecutionExpected)
+    {
+        $this->createFixtures(3);
+
+        $operation = new Find($this->getDatabaseName(), $this->getCollectionName(), []);
+
+        $explainOperation = new Explain($this->getDatabaseName(), $operation, ['verbosity' => $verbosity, 'typeMap' => ['root' => 'array', 'document' => 'array']]);
+        $result = $explainOperation->execute($this->getPrimaryServer());
+
+        $this->assertExplainResult($result, $executionStatsExpected, $allPlansExecutionExpected);
+    }
+
+    public function testFindMaxAwait()
+    {
+        if (version_compare($this->getServerVersion(), '3.2.0', '<')) {
+            $this->markTestSkipped('maxAwaitTimeMS option is not supported');
+        }
+
+        $maxAwaitTimeMS = 100;
+
+        /* Calculate an approximate pivot to use for time assertions. We will
+         * assert that the duration of blocking responses is greater than this
+         * value, and vice versa. */
+        $pivot = ($maxAwaitTimeMS * 0.001) * 0.9;
+
+        // Create a capped collection.
+        $databaseName = $this->getDatabaseName();
+        $cappedCollectionName = $this->getCollectionName();
+        $cappedCollectionOptions = [
+            'capped' => true,
+            'max' => 100,
+            'size' => 1048576,
+        ];
+
+        $operation = new CreateCollection($databaseName, $cappedCollectionName, $cappedCollectionOptions);
+        $operation->execute($this->getPrimaryServer());
+
+        $this->createFixtures(2);
+
+        $operation = new Find($databaseName, $cappedCollectionName, [], ['cursorType' => Find::TAILABLE_AWAIT, 'maxAwaitTimeMS' => $maxAwaitTimeMS]);
+
+        (new CommandObserver)->observe(
+            function() use ($operation) {
+                $explainOperation = new Explain($this->getDatabaseName(), $operation, ['typeMap' => ['root' => 'array', 'document' => 'array']]);
+                $explainOperation->execute($this->getPrimaryServer());
+            },
+            function(stdClass $command) {
+                $this->assertObjectNotHasAttribute('maxAwaitTimeMS', $command->explain);
+                $this->assertObjectHasAttribute('tailable', $command->explain);
+                $this->assertObjectHasAttribute('awaitData', $command->explain);
+            }
+        );
+    }
+
+    public function testFindModifiers()
+    {
+        $this->createFixtures(3);
+
+        $operation = new Find(
+            $this->getDatabaseName(),
+            $this->getCollectionName(),
+            [],
+            ['modifiers' => ['$orderby' => ['_id' => 1]]]
+        );
+
+        (new CommandObserver)->observe(
+            function() use ($operation) {
+                $explainOperation = new Explain($this->getDatabaseName(), $operation, ['typeMap' => ['root' => 'array', 'document' => 'array']]);
+                $explainOperation->execute($this->getPrimaryServer());
+            },
+            function(stdClass $command) {
+                $this->assertObjectHasAttribute('sort', $command->explain);
+                $this->assertObjectNotHasAttribute('modifiers', $command->explain);
+            }
+        );
+    }
+
+
+    /**
+     * @dataProvider provideVerbosityInformation
+     */
+    public function testFindOne($verbosity, $executionStatsExpected, $allPlansExecutionExpected)
+    {
+        $this->createFixtures(1);
+
+        $operation = new FindOne($this->getDatabaseName(), $this->getCollectionName(), []);
+
+        $explainOperation = new Explain($this->getDatabaseName(), $operation, ['verbosity' => $verbosity, 'typeMap' => ['root' => 'array', 'document' => 'array']]);
+        $result = $explainOperation->execute($this->getPrimaryServer());
+
+        $this->assertExplainResult($result, $executionStatsExpected, $allPlansExecutionExpected);
+    }
+
+    /**
+     * @dataProvider provideVerbosityInformation
+     */
+    public function testFindOneAndDelete($verbosity, $executionStatsExpected, $allPlansExecutionExpected)
+    {
+        if (version_compare($this->getServerVersion(), '3.2.0', '<')) {
+            $this->markTestSkipped('Explaining findOneAndDelete command requires server version >= 3.2');
+        }
+
+        $operation = new FindOneAndDelete($this->getDatabaseName(), $this->getCollectionName(), []);
+
+        $explainOperation = new Explain($this->getDatabaseName(), $operation, ['verbosity' => $verbosity, 'typeMap' => ['root' => 'array', 'document' => 'array']]);
+        $result = $explainOperation->execute($this->getPrimaryServer());
+
+        $this->assertExplainResult($result, $executionStatsExpected, $allPlansExecutionExpected);
+    }
+
+    /**
+     * @dataProvider provideVerbosityInformation
+     */
+    public function testFindOneAndReplace($verbosity, $executionStatsExpected, $allPlansExecutionExpected)
+    {
+        if (version_compare($this->getServerVersion(), '3.2.0', '<')) {
+            $this->markTestSkipped('Explaining findOneAndReplace command requires server version >= 3.2');
+        }
+
+        $operation = new FindOneAndReplace($this->getDatabaseName(), $this->getCollectionName(), ['x' => 1.1], ['x' => 5]);
+
+        $explainOperation = new Explain($this->getDatabaseName(), $operation, ['verbosity' => $verbosity, 'typeMap' => ['root' => 'array', 'document' => 'array']]);
+        $result = $explainOperation->execute($this->getPrimaryServer());
+
+        $this->assertExplainResult($result, $executionStatsExpected, $allPlansExecutionExpected);
+    }
+
+    /**
+     * @dataProvider provideVerbosityInformation
+     */
+    public function testFindOneAndUpdate($verbosity, $executionStatsExpected, $allPlansExecutionExpected)
+    {
+        if (version_compare($this->getServerVersion(), '3.2.0', '<')) {
+            $this->markTestSkipped('Explaining findOneAndUpdate command requires server version >= 3.2');
+        }
+
+        $operation = new FindOneAndUpdate($this->getDatabaseName(), $this->getCollectionName(), [], ['$rename' => ['x' => 'y']]);
+
+        $explainOperation = new Explain($this->getDatabaseName(), $operation, ['verbosity' => $verbosity, 'typeMap' => ['root' => 'array', 'document' => 'array']]);
+        $result = $explainOperation->execute($this->getPrimaryServer());
+
+        $this->assertExplainResult($result, $executionStatsExpected, $allPlansExecutionExpected);
+    }
+
+    /**
+     * @dataProvider provideVerbosityInformation
+     */
+    public function testUpdate($verbosity, $executionStatsExpected, $allPlansExecutionExpected)
+    {
+        $this->createFixtures(3);
+
+        $filter = ['_id' => ['$gt' => 1]];
+        $update = ['$inc' => ['x' => 1]];
+
+        $operation = new Update($this->getDatabaseName(), $this->getCollectionName(), $filter, $update);
+
+        $explainOperation = new Explain($this->getDatabaseName(), $operation, ['verbosity' => $verbosity, 'typeMap' => ['root' => 'array', 'document' => 'array']]);
+        $result = $explainOperation->execute($this->getPrimaryServer());
+
+        $this->assertExplainResult($result, $executionStatsExpected, $allPlansExecutionExpected);
+    }
+
+    /**
+     * @dataProvider provideVerbosityInformation
+     */
+    public function testUpdateMany($verbosity, $executionStatsExpected, $allPlansExecutionExpected)
+    {
+        $this->createFixtures(3);
+
+        $filter = ['_id' => ['$gt' => 1]];
+        $update = ['$inc' => ['x' => 1]];
+
+        $operation = new UpdateMany($this->getDatabaseName(), $this->getCollectionName(), $filter, $update);
+
+        $explainOperation = new Explain($this->getDatabaseName(), $operation, ['verbosity' => $verbosity, 'typeMap' => ['root' => 'array', 'document' => 'array']]);
+        $result = $explainOperation->execute($this->getPrimaryServer());
+
+        $this->assertExplainResult($result, $executionStatsExpected, $allPlansExecutionExpected);
+    }
+
+    /**
+     * @dataProvider provideVerbosityInformation
+     */
+    public function testUpdateOne($verbosity, $executionStatsExpected, $allPlansExecutionExpected)
+    {
+        $this->createFixtures(3);
+
+        $filter = ['_id' => ['$lte' => 1]];
+        $update = ['$inc' => ['x' => 1]];
+
+        $operation = new UpdateOne($this->getDatabaseName(), $this->getCollectionName(), $filter, $update);
+
+        $explainOperation = new Explain($this->getDatabaseName(), $operation, ['verbosity' => $verbosity, 'typeMap' => ['root' => 'array', 'document' => 'array']]);
+        $result = $explainOperation->execute($this->getPrimaryServer());
+
+        $this->assertExplainResult($result, $executionStatsExpected, $allPlansExecutionExpected);
+    }
+
+    public function provideVerbosityInformation()
+    {
+        return [
+            [Explain::VERBOSITY_ALL_PLANS, true, true],
+            [Explain::VERBOSITY_EXEC_STATS, true, false],
+            [Explain::VERBOSITY_QUERY, false, false],
+        ];
+    }
+
+    private function assertExplainResult($result, $executionStatsExpected, $allPlansExecutionExpected)
+    {
+        $this->assertArrayHasKey('queryPlanner', $result);
+        if ($executionStatsExpected) {
+            $this->assertArrayHasKey('executionStats', $result);
+            if ($allPlansExecutionExpected) {
+                $this->assertArrayHasKey('allPlansExecution', $result['executionStats']);
+            } else {
+                $this->assertArrayNotHasKey('allPlansExecution', $result['executionStats']);
+            }
+        } else {
+            $this->assertArrayNotHasKey('executionStats', $result);
+        }
+    }
+
+    /**
+     * Create data fixtures.
+     *
+     * @param integer $n
+     */
+    private function createFixtures($n)
+    {
+        $bulkWrite = new BulkWrite(['ordered' => true]);
+
+        for ($i = 1; $i <= $n; $i++) {
+            $bulkWrite->insert([
+                '_id' => $i,
+                'x' => (integer) ($i . $i),
+            ]);
+        }
+
+        $result = $this->manager->executeBulkWrite($this->getNamespace(), $bulkWrite);
+
+        $this->assertEquals($n, $result->getInsertedCount());
+    }
+}

tests/Operation/ExplainTest.php

+<?php
+
+namespace MongoDB\Tests\Operation;
+
+use MongoDB\Operation\Count;
+use MongoDB\Operation\Distinct;
+use MongoDB\Operation\Explain;
+
+class ExplainTest extends TestCase
+{
+    /**
+     * @expectedException MongoDB\Exception\InvalidArgumentException
+     * @dataProvider provideInvalidConstructorOptions
+     */
+    public function testConstructorOptionTypeChecks(array $options)
+    {
+        $explainable = $this->getMockBuilder('MongoDB\Operation\Explainable')->getMock();
+        new Explain($this->getDatabaseName(), $explainable, $options);
+    }
+
+    public function provideInvalidConstructorOptions()
+    {
+        $options = [];
+
+        foreach ($this->getInvalidStringValues() as $value) {
+            $options[][] = ['verbosity' => $value];
+        }
+
+        foreach ($this->getInvalidArrayValues() as $value) {
+            $options[][] = ['typeMap' => $value];
+        }
+
+        return $options;
+    }
+}