Navigation

MongoDB\Database::command()

On this page

Definition

MongoDB\Database::command

Execute a command on the database. This is generally used to execute commands that do not have a corresponding helper method within the library.

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

This method has the following parameters:

Parameter Type Description
$command array|object The database command document.
$options array Optional. An array specifying the desired options.

The $options parameter supports the following options:

Option Type Description
readPreference MongoDB\Driver\ReadPreference Optional. Read preference to use for the operation. Defaults to the database’s read preference.
session MongoDB\Driver\Session

Optional. Client session to associate with the operation.

New in version 1.3.
typeMap array Optional. The type map to apply to cursors, which determines how BSON documents are converted to PHP values. Defaults to the database’s type map.

Return Values

A MongoDB\Driver\Cursor object.

Errors/Exceptions

MongoDB\Exception\InvalidArgumentException for errors related to the parsing of parameters or options.

MongoDB\Driver\Exception\RuntimeException for other errors at the driver level (e.g. connection errors).

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 ping command and prints its result document:

copy 
<?php

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

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

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

The output would resemble:

copy 
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 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 MongoDB\Database::listCollections() in practice.

copy 
<?php

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

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

var_dump($cursor->toArray());

The output would resemble:

copy 
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) {
        }
      }
    }
  }
}

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.