============================
MongoDB\\Database::command()
============================

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

Definition
----------

.. phpmethod:: MongoDB\Database::command()

   Execute a :manual:`command </reference/command>` on the database. This is
   generally used to execute commands that do not have a corresponding helper
   method within the library.

   .. code-block:: php

      function command(
          array|object $command,
          array $options = []
      ): MongoDB\Driver\Cursor

Parameters
----------

``$command`` : array|object
  The :manual:`database command </reference/command>` document.

``$options`` : array
  An array specifying the desired options.

  .. list-table::
     :header-rows: 1
     :widths: 20 20 80

     * - Name
       - Type
       - Description

     * - readPreference
       - :php:`MongoDB\Driver\ReadPreference <class.mongodb-driver-readpreference>`
       - .. include:: /includes/extracts/database-option-readPreference.rst

     * - session
       - :php:`MongoDB\Driver\Session <class.mongodb-driver-session>`
       - .. include:: /includes/extracts/common-option-session.rst

         .. versionadded:: 1.3

     * - typeMap
       - array
       - .. include:: /includes/extracts/database-option-typeMap.rst

Return Values
-------------

A :php:`MongoDB\Driver\Cursor <class.mongodb-driver-cursor>` object.

Errors/Exceptions
-----------------

.. include:: /includes/extracts/error-invalidargumentexception.rst
.. include:: /includes/extracts/error-driver-runtimeexception.rst

Example
-------

Most database commands return a single result document, which can be obtained by
converting the returned cursor to an array and accessing its first element. The
following example executes a :manual:`ping </reference/command/ping>` command
and prints its result document:

.. code-block:: php

   <?php

   $database = (new MongoDB\Client)->test;

   $cursor = $database->command(['ping' => 1]);

   var_dump($cursor->toArray()[0]);

The output would resemble:

.. code-block:: none

   object(MongoDB\Model\BSONDocument)#11 (1) {
     ["storage":"ArrayObject":private]=>
     array(1) {
       ["ok"]=>
       float(1)
     }
   }

Some database commands return a cursor with multiple results. The following
example executes :manual:`listCollections </reference/command/listCollections>`,
which returns a cursor containing a result document for each collection in the
``test`` database. Note that this example is illustrative; applications would
generally use :phpmethod:`MongoDB\Database::listCollections()` in practice.

.. code-block:: php

   <?php

   $database = (new MongoDB\Client)->test;

   $cursor = $database->command(['listCollections' => 1]);

   var_dump($cursor->toArray());

The output would resemble:

.. code-block:: none

   array(3) {
     [0]=>
     object(MongoDB\Model\BSONDocument)#11 (1) {
       ["storage":"ArrayObject":private]=>
       array(2) {
         ["name"]=>
         string(11) "restaurants"
         ["options"]=>
         object(MongoDB\Model\BSONDocument)#3 (1) {
           ["storage":"ArrayObject":private]=>
           array(0) {
           }
         }
       }
     }
     [1]=>
     object(MongoDB\Model\BSONDocument)#13 (1) {
       ["storage":"ArrayObject":private]=>
       array(2) {
         ["name"]=>
         string(5) "users"
         ["options"]=>
         object(MongoDB\Model\BSONDocument)#12 (1) {
           ["storage":"ArrayObject":private]=>
           array(0) {
           }
         }
       }
     }
     [2]=>
     object(MongoDB\Model\BSONDocument)#15 (1) {
       ["storage":"ArrayObject":private]=>
       array(2) {
         ["name"]=>
         string(6) "restos"
         ["options"]=>
         object(MongoDB\Model\BSONDocument)#14 (1) {
           ["storage":"ArrayObject":private]=>
           array(0) {
           }
         }
       }
     }
   }

See Also
--------

- :doc:`/tutorial/commands`
- :manual:`Database Commands </reference/command>` in the MongoDB manual
- :php:`MongoDB\Driver\Cursor <class.mongodb-driver-cursor>`
- :php:`MongoDB\Driver\Manager::executeCommand()
  <manual/en/mongodb-driver-manager.executecommand.php>`
