DOCSP-41956: run a command

Author: rustagir

source/includes/write/run-command.php

@@ -0,0 +1,19 @@
+<?php
+
+require __DIR__ . '/vendor/autoload.php';
+
+use MongoDB\Client;
+
+$client = new Client('<connection string>');
+
+// start-runcommand
+$database = $client->plants;
+
+$countCommand = ['count' => 'flowers'];
+$explainCommand = ['explain' => $countCommand, 'verbosity' => 'queryPlanner'];
+
+$result = $database->command($explainCommand);
+// end-runcommand
+
+var_dump($result->toArray());
+

source/write/run-command.txt

@@ -0,0 +1,179 @@
+.. _php-run-command:
+
+======================
+Run a Database Command
+======================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: administration, code example
+
+Overview
+--------
+
+In this guide, you can learn how to use the {+php-library+}
+to run a database command. You can use database commands to perform a
+variety of administrative and diagnostic tasks, such as fetching server
+statistics, initializing a replica set, or running an aggregation pipeline.
+
+.. important:: Prefer Library Methods to Database Commands
+
+   The library provides wrapper methods for many database commands.
+   We recommend using these methods instead of executing database
+   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.
+
+.. _php-execute-command:
+
+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
+``command()`` method. This method returns a ``Cursor`` object.
+
+The following code shows how you can use the ``command()``
+method to run the ``hello`` command, which returns information about
+the current member's role in the replica set, on a database:
+
+.. code-block:: php
+
+   $result = $database->command(['ping' => 1]);
+
+To find a link to a full list of database commands and corresponding
+parameters, see the :ref:`Additional Information section
+<php-addtl-info-runcommand>`.
+
+.. note:: Read Preference
+
+   The ``command()`` method does not
+   obey the read preference you might have set on your ``Database``
+   instance elsewhere in your code. By default, ``command()`` uses the ``primary``
+   read preference.
+   
+   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(['ping' => 1], ['readPreference' => $readPref]);
+
+   For more information on read preference options, see :manual:`Read
+   Preference </core/read-preference/>` in the Server manual.
+
+.. _php-command-response:
+
+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:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Field
+     - Description
+
+   * - <command result>
+     - Fields specific to the database command. For example,
+       ``count`` returns the ``n`` field and ``explain`` returns the
+       ``queryPlanner`` field.
+
+   * - ``ok``
+     - Whether the command has succeeded (``1``)
+       or failed (``0``).
+
+   * - ``operationTime``
+     - The logical time of the operation. MongoDB uses the
+       logical time to order operations.
+       
+       .. seealso::
+  
+          To learn more about logical time, 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
+
+.. _rust-command-example:
+
+Command Example
+---------------
+
+The following code shows how you can use the ``command()`` method to run
+the ``explain`` command for a ``count`` operation on the ``flowers``
+collection of the ``plants`` database. The ``explain`` command runs in the
+``"queryPlanner"`` verbosity mode:
+
+.. literalinclude:: /includes/write/run-command.php
+   :language: php
+   :dedent:
+   :start-after: start-runcommand
+   :end-before: end-runcommand
+
+Output
+~~~~~~
+
+The output includes fields explaining the
+execution of the ``count`` operation, such as the winning plan, which is
+the plan selected by the query optimizer, and any rejected
+plans. The output also contains information about the execution of the
+``explain`` command:
+
+.. code-block:: json
+   :emphasize-lines: 
+
+   string(1203)
+   "[{"explainVersion":"1","queryPlanner":{"namespace":"plants.flowers",
+   "indexFilterSet":false,"maxIndexedOrSolutionsReached":false,
+   "maxIndexedAndSolutionsReached":false,"maxScansToExplodeReached":false,"winningPlan":
+   {"stage":"RECORD_STORE_FAST_COUNT"},"rejectedPlans":[]},"command":{"count":"flowers",
+   "$db":"plants"},"serverInfo":{"host":"...","port":27017,"version":"7.0.12",
+   "gitVersion":"..."},"serverParameters":{...},"ok":1,"$clusterTime":{...},"signature":{...},
+   "keyId":...}},"operationTime":{"$timestamp":{"t":1725637892,"i":12}}}]"
+
+.. _php-addtl-info-runcommand:
+
+Additional Information
+----------------------
+
+For more information about the concepts in this guide, see the following
+documentation in the Server manual:
+
+- :manual:`db.runCommand() </reference/method/db.runCommand/>`
+- :manual:`Database Commands </reference/command/>`
+- :manual:`hello Command </reference/command/hello/>`
+- :manual:`explain Command </reference/command/explain/>`
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+- `MongoDB\\Database::command() <{+api+}/method/MongoDBDatabase-command/>`__