JM tech review

Author: rustagir

source/includes/write/run-command.php

@@ -4,14 +4,29 @@
 
 use MongoDB\Client;
 
-$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset');
+$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your connection URI');
 $client = new MongoDB\Client($uri);
 
+// start-hello
+$database = $client->selectDatabase('myDB');
+$cursor = $database->command(['hello' => 1]);
+// end-hello
+
+// start-readpref
+$readPref = new MongoDB\Driver\ReadPreference('primaryPreferred');
+$cursor = $database->command(
+    ['hello' => 1], 
+    ['readPreference' => $readPref]
+);
+// end-readpref
+
 // start-runcommand
 $database = $client->accounts;
 $command = ['dbStats' => 1];
 
-$result = $database->command($command);
-// end-runcommand
+// dbStats returns a single document
+$cursor = $database->command($command);
 
-var_dump(json_encode($result->toArray()));
+// Print the first document in the cursor
+echo json_encode($cursor->toArray()[0]), PHP_EOL;
+// end-runcommand

source/write/run-command.txt

@@ -32,10 +32,11 @@ statistics, initializing a replica set, or running an aggregation pipeline.
    commands when possible.
 
    To perform administrative tasks, use the :mongosh:`MongoDB Shell </>`
-   instead of the {+php-library+}. Calling the ``db.runCommand()``
-   method inside the shell is the preferred way to issue database
-   commands, as it provides a consistent interface between the shell and
-   drivers or libraries.
+   instead of the {+php-library+}. The shell provides helper methods
+   that might not be available in the library.
+   
+   If there are no available helpers in the library or the shell, you
+   can use the ``db.runCommand()`` shell method.
 
 .. _php-execute-command:
 
@@ -44,18 +45,20 @@ Execute a Command
 
 To run a database command, you must specify the command and any relevant
 parameters in a command document, then pass the command document to the
-``MongoDB\Database::command()`` method. This method returns a
-``Cursor`` object.
+``MongoDB\Database::command()`` method. Many database commands return
+multiple result documents, so the ``command()`` method returns a
+``Cursor`` object that you can iterate through.
 
 The following code shows how you can use the ``command()``
-method on a ``MongoDB\Driver\Database`` instance to run the ``hello``
+method on a :phpclass:`MongoDB\Database` instance to run the ``hello``
 command, which returns information about the current member's role in
 the replica set:
 
-.. code-block:: php
-
-   $database = $client->selectDatabase('<db>');
-   $result = $database->command(['hello' => 1]);
+.. literalinclude:: /includes/write/run-command.php
+   :language: php
+   :dedent:
+   :start-after: start-hello
+   :end-before: end-hello
 
 To find a link to a full list of database commands and corresponding
 parameters, see the :ref:`Additional Information section
@@ -70,13 +73,11 @@ parameters, see the :ref:`Additional Information section
    You can set a read preference for command execution by setting one
    in the options parameter, as shown in the following code:
 
-   .. code-block:: php
-
-      $readPref = new MongoDB\Driver\ReadPreference('primaryPreferred');
-      $result = $database->command(
-          ['hello' => 1], 
-          ['readPreference' => $readPref]
-      );
+   .. literalinclude:: /includes/write/run-command.php
+      :language: php
+      :dedent:
+      :start-after: start-readpref
+      :end-before: end-readpref
 
    For more information on read preference options, see :manual:`Read
    Preference </core/read-preference/>` in the {+mdb-server+} manual.
@@ -87,11 +88,25 @@ Response
 --------
 
 The ``command()`` method returns a ``Cursor`` object that contains
-the response from the database after the command has been executed.
-
-Each database command performs a different function, so the response
-content can vary depending on the command executed. However, every
-response contains a document with the following fields:
+the response from the database for the given command. Each database
+command performs a different function, so the response
+content can vary. Some command responses contain multiple result
+documents. In these situations, the library converts the cursor
+envelope in the raw command response, which includes the cursor ID and
+the first batch of results, into an iterable cursor.
+
+Before you run a command, learn about the response format of the
+command so that your application either iterates through multiple
+results or extracts the first and only document in the cursor. See the
+:ref:`php-addtl-info-runcommand` section of this guide to find a link to
+the full list of database commands.
+
+If the number of documents in the command response is sufficiently large, you
+can run a :manual:`getMore </reference/command/getMore/>` command to
+retrieve the next batch of results from the cursor by using the cursor
+ID.
+
+The raw command response contains the following fields:
 
 .. list-table::
    :header-rows: 1
@@ -102,29 +117,24 @@ response contains a document with the following fields:
 
    * - <command result>
      - Fields specific to the database command. For example,
-       ``count`` returns the ``n`` field and ``explain`` returns the
-       ``queryPlanner`` field.
+       the ``count`` command returns the ``n`` field.
 
    * - ``ok``
-     - Whether the command has succeeded (``1``)
-       or failed (``0``).
+     - Whether the command has succeeded (``1``) or failed (``0``). The
+       library raises a :php:`CommandException
+       <mongodb-driver-exception-commandexception.php>` if
+       the ``ok`` field is ``0``.
 
    * - ``operationTime``
      - The logical time of the operation. MongoDB uses the
        logical time to order operations. To learn more about this
-       concept, see our blog  post about the :website:`Global Logical
+       concept, see our blog post about the :website:`Global Logical
        Clock </blog/post/transactions-background-part-4-the-global-logical-clock>`.
 
    * - ``$clusterTime``
      - A document that contains the signed cluster time. Cluster time is a
        logical time used for the ordering of operations.
 
-       This document contains the following fields:
-
-       - ``clusterTime``, the timestamp of the highest known cluster time for the member
-       - ``signature``, a document that contains the hash of the cluster time and the ID
-         of the key used to sign the cluster time
-
 .. _php-command-example:
 
 Command Example
@@ -146,9 +156,9 @@ collections:
 
 .. code-block:: none
 
-   string(234) "[{"db":"accounts","collections":2,"views":0,"objects":5,"avgObjSize":22,
-   "dataSize":110,"storageSize":8192,"totalFreeStorageSize":0,"numExtents":0,"indexes":2,
-   "indexSize":8192,"indexFreeStorageSize":0,"fileSize":0,"nsSizeMB":0,"ok":1}]"
+   {"db":"accounts","collections":2,"views":0,"objects":5,"avgObjSize":22,"dataSize":110,
+   "storageSize":40960,"totalFreeStorageSize":0,"numExtents":0,"indexes":2,"indexSize":40960,
+   "indexFreeStorageSize":0,"fileSize":0,"nsSizeMB":0,"ok":1}
 
 .. _php-addtl-info-runcommand: