Merge pull request #501

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

+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: readPreference
+---
+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: typeMap
+post: |
+  This will be used for the returned command result document.
+---
+arg_name: option
+name: verbosity
+type: string
+description: |
+  The verbosity level at which to run the command. See the :manual:`explain
+  </reference/command/explain>` command for more information.
+interface: phpmethod
+operation: ~
+optional: true
+...

docs/includes/apiargs-MongoDBCollection-method-explain-param.yaml

+arg_name: param
+name: $explainable
+type: :phpclass:`MongoDB\\Operation\\Explainable`
+description: |
+  The command to explain.
+interface: phpmethod
+operation: ~
+optional: false
+---
+source:
+  file: apiargs-common-param.yaml
+  ref: $options
+...

docs/reference/class/MongoDBCollection.txt

@@ -71,6 +71,7 @@ Methods
    /reference/method/MongoDBCollection-drop
    /reference/method/MongoDBCollection-dropIndex
    /reference/method/MongoDBCollection-dropIndexes
+   /reference/method/MongoDBCollection-explain
    /reference/method/MongoDBCollection-find
    /reference/method/MongoDBCollection-findOne
    /reference/method/MongoDBCollection-findOneAndDelete

docs/reference/method/MongoDBCollection-explain.txt

+==============================
+MongoDB\\Collection::explain()
+==============================
+
+.. versionadded:: 1.4
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. phpmethod:: MongoDB\\Collection::explain()
+
+   Explain the given command.
+
+   .. code-block:: php
+
+      function explain(MongoDB\\Operation\\Explainable $explainable, array $options = []): array|object
+
+   This method has the following parameters:
+
+   .. include:: /includes/apiargs/MongoDBCollection-method-explain-param.rst
+
+   The ``$options`` parameter supports the following options:
+
+   .. include:: /includes/apiargs/MongoDBCollection-method-explain-option.rst
+
+Return Values
+-------------
+
+An array or object with the result document of the :manual:`explain
+</reference/command/explain>` command. The return type will depend on the
+``typeMap`` option.
+
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-unsupportedexception.rst
+.. include:: /includes/extracts/error-invalidargumentexception.rst
+.. include:: /includes/extracts/error-driver-runtimeexception.rst
+
+Explainable Commands
+--------------------
+
+Explainable commands include, but are not limited to:
+
+   - :phpclass:`MongoDB\\Operation\\Count`
+   - :phpclass:`MongoDB\\Operation\\DeleteMany`
+   - :phpclass:`MongoDB\\Operation\\DeleteOne`
+   - :phpclass:`MongoDB\\Operation\\Distinct`
+   - :phpclass:`MongoDB\\Operation\\Find`
+   - :phpclass:`MongoDB\\Operation\\FindOne`
+   - :phpclass:`MongoDB\\Operation\\FindOneAndDelete`
+   - :phpclass:`MongoDB\\Operation\\FindOneAndReplace`
+   - :phpclass:`MongoDB\\Operation\\FindOneAndUpdate`
+   - :phpclass:`MongoDB\\Operation\\UpdateMany`
+   - :phpclass:`MongoDB\\Operation\\UpdateOne`
+
+Examples
+--------
+
+This example explains a count command.
+
+.. code-block:: php
+
+   <?php
+
+   $collection = (new MongoDB\Client)->test->restaurants;
+
+   $count = new MongoDB\Operation\Count(
+       $collection->getDatabaseName(),
+       $collection->getCollectionName(),
+       ['cuisine' => 'Italian']
+   );
+
+   $result = $collection->explain($count);
+
+   var_dump($result);
+
+The output would then resemble::
+
+   object(MongoDB\Model\BSONDocument)#29 (1) {
+     ["storage":"ArrayObject":private]=>
+     array(4) {
+       ["queryPlanner"]=>
+       object(MongoDB\Model\BSONDocument)#21 (1) {
+         ["storage":"ArrayObject":private]=>
+         array(6) {
+           ["plannerVersion"]=>
+           int(1)
+           ["namespace"]=>
+           string(16) "test.restaurants"
+           ["indexFilterSet"]=>
+           bool(false)
+           ["parsedQuery"]=>
+           object(MongoDB\Model\BSONDocument)#15 (1) {
+             ["storage":"ArrayObject":private]=>
+             array(1) {
+               ["cuisine"]=>
+               object(MongoDB\Model\BSONDocument)#14 (1) {
+                 ["storage":"ArrayObject":private]=>
+                 array(1) {
+                   ["$eq"]=>
+                   string(7) "Italian"
+                 }
+               }
+             }
+           }
+           ["winningPlan"]=>
+           object(MongoDB\Model\BSONDocument)#19 (1) {
+             ["storage":"ArrayObject":private]=>
+             array(2) {
+               ["stage"]=>
+               string(5) "COUNT"
+               ["inputStage"]=>
+               object(MongoDB\Model\BSONDocument)#18 (1) {
+                 ["storage":"ArrayObject":private]=>
+                 array(3) {
+                   ["stage"]=>
+                   string(8) "COLLSCAN"
+                   ["filter"]=>
+                   object(MongoDB\Model\BSONDocument)#17 (1) {
+                     ["storage":"ArrayObject":private]=>
+                     array(1) {
+                       ["cuisine"]=>
+                       object(MongoDB\Model\BSONDocument)#16 (1) {
+                         ["storage":"ArrayObject":private]=>
+                         array(1) {
+                           ["$eq"]=>
+                           string(7) "Italian"
+                         }
+                       }
+                     }
+                   }
+                   ["direction"]=>
+                   string(7) "forward"
+                 }
+               }
+             }
+           }
+           ["rejectedPlans"]=>
+           object(MongoDB\Model\BSONArray)#20 (1) {
+             ["storage":"ArrayObject":private]=>
+             array(0) {
+             }
+           }
+         }
+       }
+       ["executionStats"]=>
+       object(MongoDB\Model\BSONDocument)#27 (1) {
+         ["storage":"ArrayObject":private]=>
+         array(7) {
+           ["executionSuccess"]=>
+           bool(true)
+           ["nReturned"]=>
+           int(0)
+           ["executionTimeMillis"]=>
+           int(24)
+           ["totalKeysExamined"]=>
+           int(0)
+           ["totalDocsExamined"]=>
+           int(25359)
+           ["executionStages"]=>
+           object(MongoDB\Model\BSONDocument)#25 (1) {
+             ["storage":"ArrayObject":private]=>
+             array(14) {
+               ["stage"]=>
+               string(5) "COUNT"
+               ["nReturned"]=>
+               int(0)
+               ["executionTimeMillisEstimate"]=>
+               int(20)
+               ["works"]=>
+               int(25361)
+               ["advanced"]=>
+               int(0)
+               ["needTime"]=>
+               int(25360)
+               ["needYield"]=>
+               int(0)
+               ["saveState"]=>
+               int(198)
+               ["restoreState"]=>
+               int(198)
+               ["isEOF"]=>
+               int(1)
+               ["invalidates"]=>
+               int(0)
+               ["nCounted"]=>
+               int(1069)
+               ["nSkipped"]=>
+               int(0)
+               ["inputStage"]=>
+               object(MongoDB\Model\BSONDocument)#24 (1) {
+                 ["storage":"ArrayObject":private]=>
+                 array(14) {
+                   ["stage"]=>
+                   string(8) "COLLSCAN"
+                   ["filter"]=>
+                   object(MongoDB\Model\BSONDocument)#23 (1) {
+                     ["storage":"ArrayObject":private]=>
+                     array(1) {
+                       ["cuisine"]=>
+                       object(MongoDB\Model\BSONDocument)#22 (1) {
+                         ["storage":"ArrayObject":private]=>
+                         array(1) {
+                           ["$eq"]=>
+                           string(7) "Italian"
+                         }
+                       }
+                     }
+                   }
+                   ["nReturned"]=>
+                   int(1069)
+                   ["executionTimeMillisEstimate"]=>
+                   int(20)
+                   ["works"]=>
+                   int(25361)
+                   ["advanced"]=>
+                   int(1069)
+                   ["needTime"]=>
+                   int(24291)
+                   ["needYield"]=>
+                   int(0)
+                   ["saveState"]=>
+                   int(198)
+                   ["restoreState"]=>
+                   int(198)
+                   ["isEOF"]=>
+                   int(1)
+                   ["invalidates"]=>
+                   int(0)
+                   ["direction"]=>
+                   string(7) "forward"
+                   ["docsExamined"]=>
+                   int(25359)
+                 }
+               }
+             }
+           }
+           ["allPlansExecution"]=>
+           object(MongoDB\Model\BSONArray)#26 (1) {
+             ["storage":"ArrayObject":private]=>
+             array(0) {
+             }
+           }
+         }
+       }
+       ["serverInfo"]=>
+       object(MongoDB\Model\BSONDocument)#28 (1) {
+         ["storage":"ArrayObject":private]=>
+         array(4) {
+           ["host"]=>
+           string(9) "localhost"
+           ["port"]=>
+           int(27017)
+           ["version"]=>
+           string(5) "3.6.1"
+           ["gitVersion"]=>
+           string(40) "025d4f4fe61efd1fb6f0005be20cb45a004093d1"
+         }
+       }
+       ["ok"]=>
+       float(1)
+     }
+   }
+
+See Also
+--------
+
+- :manual:`explain </reference/command/explain>` command reference in the MongoDB
+  manual

src/Collection.php

@@ -39,6 +39,8 @@ use MongoDB\Operation\DeleteOne;
 use MongoDB\Operation\Distinct;
 use MongoDB\Operation\DropCollection;
 use MongoDB\Operation\DropIndexes;
+use MongoDB\Operation\Explain;
+use MongoDB\Operation\Explainable;
 use MongoDB\Operation\Find;
 use MongoDB\Operation\FindOne;
 use MongoDB\Operation\FindOneAndDelete;
@@ -498,6 +500,35 @@ class Collection
         return $operation->execute($server);
     }
 
+    /**
+     * Explains explainable commands.
+     *
+     * @see Explain::__construct() for supported options
+     * @see http://docs.mongodb.org/manual/reference/command/explain/
+     * @param Explainable $explainable  Command on which to run explain
+     * @param array       $options      Additional options
+     * @return array|object
+     * @throws UnsupportedException if explainable or options are not supported by the selected server
+     * @throws InvalidArgumentException for parameter/option parsing errors
+     * @throws DriverRuntimeException for other driver errors (e.g. connection errors)
+     */
+    public function explain(Explainable $explainable, array $options = [])
+    {
+        if ( ! isset($options['readPreference'])) {
+            $options['readPreference'] = $this->readPreference;
+        }
+
+        if ( ! isset($options['typeMap'])) {
+            $options['typeMap'] = $this->typeMap;
+        }
+
+        $server = $this->manager->selectServer($options['readPreference']);
+
+        $operation = new Explain($this->databaseName, $explainable, $options);
+
+        return $operation->execute($server);
+    }
+
     /**
      * Finds documents matching the query.
      *

tests/Collection/CollectionFunctionalTest.php

@@ -9,6 +9,7 @@ use MongoDB\Driver\ReadConcern;
 use MongoDB\Driver\ReadPreference;
 use MongoDB\Driver\WriteConcern;
 use MongoDB\Exception\InvalidArgumentException;
+use MongoDB\Operation\Count;
 use MongoDB\Operation\MapReduce;
 use MongoDB\Tests\CommandObserver;
 use stdClass;
@@ -151,6 +152,21 @@ class CollectionFunctionalTest extends FunctionalTestCase
         $this->collection->dropIndex('*');
     }
 
+    public function testExplain()
+    {
+        if (version_compare($this->getServerVersion(), '3.0.0', '<')) {
+            $this->markTestSkipped('Explain command is not supported');
+        }
+
+        $this->createFixtures(3);
+
+        $operation = new Count($this->getDatabaseName(), $this->getCollectionName(), ['x' => ['$gte' => 1]], []);
+
+        $result = $this->collection->explain($operation);
+
+        $this->assertArrayHasKey('queryPlanner', $result);
+    }
+
     public function testFindOne()
     {
         $this->createFixtures(5);