Navigation

Execute Database Commands

Overview

The MongoDB PHP Library provides helper methods across the Client, Database, and Collection classes for common database commands. In addition, the MongoDB\Database::command() method may be used to run database commands that do not have a helper method.

Execute Database Commands

Basic Command

To execute a command on a mongod instance, use the MongoDB\Database::command() method. For instance, the following operation uses the geoNear command to search for the three closest documents to longitude -74 and latitude 40 in the restos collection in the test database:

<?php

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

$cursor = $database->command([
    'geoNear' => 'restos',
    'near' => [
        'type' => 'Point',
        'coordinates' => [-74.0, 40.0],
    ],
    'spherical' => 'true',
    'num' => 3,
]);

$results = $cursor->toArray()[0];

var_dump($results);

The output would then resemble:

object(MongoDB\Model\BSONDocument)#27 (1) {
  ["storage":"ArrayObject":private]=>
  array(4) {
    ["waitedMS"]=>
    int(0)
    ["results"]=>
    object(MongoDB\Model\BSONArray)#25 (1) {
      ["storage":"ArrayObject":private]=>
      array(3) {
        [0]=>
        object(MongoDB\Model\BSONDocument)#14 (1) {
          ["storage":"ArrayObject":private]=>
          array(2) {
            ["dis"]=>
            float(39463.618389163)
            ["obj"]=>
            object(MongoDB\Model\BSONDocument)#13 (1) {
              ["storage":"ArrayObject":private]=>
              array(3) {
                ["_id"]=>
                object(MongoDB\BSON\ObjectID)#3 (1) {
                  ["oid"]=>
                  string(24) "55cba2486c522cafdb059bed"
                }
                ["location"]=>
                object(MongoDB\Model\BSONDocument)#12 (1) {
                  ["storage":"ArrayObject":private]=>
                  array(2) {
                    ["coordinates"]=>
                    object(MongoDB\Model\BSONArray)#11 (1) {
                      ["storage":"ArrayObject":private]=>
                      array(2) {
                        [0]=>
                        float(-74.1641319)
                        [1]=>
                        float(39.6686512)
                      }
                    }
                    ["type"]=>
                    string(5) "Point"
                  }
                }
                ["name"]=>
                string(32) "Soul Food Kitchen Seafood Heaven"
              }
            }
          }
        }
        [1]=>
        object(MongoDB\Model\BSONDocument)#19 (1) {
          ["storage":"ArrayObject":private]=>
          array(2) {
            ["dis"]=>
            float(50686.851650416)
            ["obj"]=>
            object(MongoDB\Model\BSONDocument)#18 (1) {
              ["storage":"ArrayObject":private]=>
              array(3) {
                ["_id"]=>
                object(MongoDB\BSON\ObjectID)#15 (1) {
                  ["oid"]=>
                  string(24) "55cba2476c522cafdb0544df"
                }
                ["location"]=>
                object(MongoDB\Model\BSONDocument)#17 (1) {
                  ["storage":"ArrayObject":private]=>
                  array(2) {
                    ["coordinates"]=>
                    object(MongoDB\Model\BSONArray)#16 (1) {
                      ["storage":"ArrayObject":private]=>
                      array(2) {
                        [0]=>
                        float(-74.2566332)
                        [1]=>
                        float(40.4109872)
                      }
                    }
                    ["type"]=>
                    string(5) "Point"
                  }
                }
                ["name"]=>
                string(20) "Seguine Bagel Bakery"
              }
            }
          }
        }
        [2]=>
        object(MongoDB\Model\BSONDocument)#24 (1) {
          ["storage":"ArrayObject":private]=>
          array(2) {
            ["dis"]=>
            float(58398.379630263)
            ["obj"]=>
            object(MongoDB\Model\BSONDocument)#23 (1) {
              ["storage":"ArrayObject":private]=>
              array(3) {
                ["_id"]=>
                object(MongoDB\BSON\ObjectID)#20 (1) {
                  ["oid"]=>
                  string(24) "55cba2476c522cafdb053c92"
                }
                ["location"]=>
                object(MongoDB\Model\BSONDocument)#22 (1) {
                  ["storage":"ArrayObject":private]=>
                  array(2) {
                    ["coordinates"]=>
                    object(MongoDB\Model\BSONArray)#21 (1) {
                      ["storage":"ArrayObject":private]=>
                      array(2) {
                        [0]=>
                        float(-74.3731727)
                        [1]=>
                        float(40.4404759)
                      }
                    }
                    ["type"]=>
                    string(5) "Point"
                  }
                }
                ["name"]=>
                string(17) "Water'S Edge Club"
              }
            }
          }
        }
      }
    }
    ["stats"]=>
    object(MongoDB\Model\BSONDocument)#26 (1) {
      ["storage":"ArrayObject":private]=>
      array(5) {
        ["nscanned"]=>
        int(25139)
        ["objectsLoaded"]=>
        int(25134)
        ["avgDistance"]=>
        float(49516.283223281)
        ["maxDistance"]=>
        float(58398.379630263)
        ["time"]=>
        int(126)
      }
    }
    ["ok"]=>
    float(1)
  }
}

Commands with Custom Read Preference

Some commands, such as createUser, may only be executed on a primary replica set member or a standalone.

The command helper methods in the MongoDB PHP Library, such as MongoDB\Database::drop(), know to apply their own read preference if necessary. However, the MongoDB\Database::command() method is a generic method and defaults to the read preference of the Database object on which it is invoked. To execute commands that require a specific read preference, specify the read preference in the $options parameter of the method.

The following example adds a user to the test database and specifies a custom read preference:

<?php

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

$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 output would then resemble:

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

View Command Results

View Single Result Documents

The MongoDB\Database::command() method returns a MongoDB\Driver\Cursor object.

Many MongoDB commands return their responses as a single document. To read the command response, you may either iterate on the cursor and access the first document, or access the first result in the array, as in the following:

<?php

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

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

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

The output would then resemble:

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

Iterate Results from a Cursor

Some commands, such as listCollections, return their results via an iterable cursor. To view the results, iterate through the cursor.

The following example lists the collections in the test database by iterating through the cursor returned by the listCollections command using a foreach loop:

<?php

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

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

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

The output would then be a list of the values for the name key, for instance:

persons
posts
zips

Note

At the protocol level, commands that support a cursor return a single result document with the essential ingredients for constructing the command cursor (i.e. the cursor’s ID, namespace, and the first batch of results). In the PHP driver implementation, the MongoDBDriverManager::executeCommand() method detects such a result and constructs the iterable command cursor, which is returned rather than the base result document.

←   Collation Decimal128  →