Database Commands

While the library provides helpers for some common database commands, it is far from an exhaustive list. This page will demonstrate how to execute arbitrary commands on the MongoDB server via the Database::command() method and access their results.

Single Result Documents

The command() method always returns a MongoDB\Driver\Cursor. Unless otherwise stated in the MongoDB documentation, command responses are returned as a single document. Reading such a result will require iterating on the cursor and accessing the first (and only) document, like so:

<?php

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

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

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

The above example would output something similar to:

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

Iterable Results as a Command Cursor

Some commands, such as listCollections, return their results via an iterable command cursor. In this case, the returned MongoDB\Driver\Cursor may be iterated in the same manner as one might do with a Collection::find() query, like so:

<?php

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

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

foreach ($cursor as $collection) {
    echo $collection['name'], "\n";
}

The above example would output something similar to:

persons
posts
zips

Note: at the protocol level, commands that support a cursor actually return a single result document with the essential ingredients for constructing the command cursor (i.e. the cursor's ID, namespace, and first batch of results); however, the driver's executeCommand() method already detects such a result and constructs the iterable command cursor for us.

Specifying a Read Preference

Some commands, such as createUser, can only be executed on a primary server. Command helpers in the library, such as Database::drop(), know to apply their own read preference if necessary; however, command() is a generic method and has no special knowledge. It defaults to the read preference of the Database object on which it is invoked. In such cases, it can be helpful to explicitly specify the correct read preference, like so:

<?php

$db = (new MongoDB\Client)->demo;

$cursor = $db->command(
    [
        'createUser' => 'username',
        'pwd' => 'password',
        'roles' => ['readWrite'],
    ],
    [
        'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_PRIMARY),
    ]
);

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

The above example would output something similar to:

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