diff --git a/docs/reference/method/MongoDBClient-selectCollection.txt b/docs/reference/method/MongoDBClient-selectCollection.txt index 34a251988..88828c29b 100644 --- a/docs/reference/method/MongoDBClient-selectCollection.txt +++ b/docs/reference/method/MongoDBClient-selectCollection.txt @@ -72,7 +72,7 @@ with a custom read preference: 'test', 'users', [ - 'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY), + 'readPreference' => new MongoDB\Driver\ReadPreference('primaryPreferred'), ] ); diff --git a/docs/reference/method/MongoDBClient-selectDatabase.txt b/docs/reference/method/MongoDBClient-selectDatabase.txt index 73ecc2b95..a556a06ae 100644 --- a/docs/reference/method/MongoDBClient-selectDatabase.txt +++ b/docs/reference/method/MongoDBClient-selectDatabase.txt @@ -71,7 +71,7 @@ preference: $db = $client->selectDatabase( 'test', [ - 'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY), + 'readPreference' => new MongoDB\Driver\ReadPreference('primaryPreferred'), ] ); diff --git a/docs/reference/method/MongoDBCollection-getReadConcern.txt b/docs/reference/method/MongoDBCollection-getReadConcern.txt index 2a40efedf..37873d0f9 100644 --- a/docs/reference/method/MongoDBCollection-getReadConcern.txt +++ b/docs/reference/method/MongoDBCollection-getReadConcern.txt @@ -36,7 +36,7 @@ Example selectCollection('test', 'users', [ - 'readConcern' => new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::MAJORITY), + 'readConcern' => new MongoDB\Driver\ReadConcern('majority'), ]); var_dump($collection->getReadConcern()); diff --git a/docs/reference/method/MongoDBCollection-updateMany.txt b/docs/reference/method/MongoDBCollection-updateMany.txt index 65f1fb01c..73092e78d 100644 --- a/docs/reference/method/MongoDBCollection-updateMany.txt +++ b/docs/reference/method/MongoDBCollection-updateMany.txt @@ -61,7 +61,7 @@ The following example updates all of the documents with the ``borough`` of $updateResult = $collection->updateMany( [ 'borough' => 'Queens' ], - [ '$set' => [ 'active' => 'True' ]] + [ '$set' => [ 'active' => true ]] ); printf("Matched %d document(s)\n", $updateResult->getMatchedCount()); diff --git a/docs/reference/method/MongoDBCollection-withOptions.txt b/docs/reference/method/MongoDBCollection-withOptions.txt index 92e09f6e3..a68a5fec0 100644 --- a/docs/reference/method/MongoDBCollection-withOptions.txt +++ b/docs/reference/method/MongoDBCollection-withOptions.txt @@ -52,7 +52,7 @@ preference: $collection = (new MongoDB\Client)->selectCollection('test', 'restaurants'); $newCollection = $sourceCollection->withOptions([ - 'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY), + 'readPreference' => new MongoDB\Driver\ReadPreference('primaryPreferred'), ]); See Also diff --git a/docs/reference/method/MongoDBDatabase-command.txt b/docs/reference/method/MongoDBDatabase-command.txt index 84b581785..d442541cf 100644 --- a/docs/reference/method/MongoDBDatabase-command.txt +++ b/docs/reference/method/MongoDBDatabase-command.txt @@ -15,7 +15,9 @@ Definition .. phpmethod:: MongoDB\\Database::command() - Execute a :manual:`command ` on the database. + Execute a :manual:`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 @@ -43,9 +45,10 @@ Errors/Exceptions Example ------- -The following example executes a :manual:`ping -` command, which returns a cursor with a single -result document: +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 ` command +and prints its result document: .. code-block:: php @@ -55,7 +58,7 @@ result document: $cursor = $database->command(['ping' => 1]); - var_dump($c->toArray()[0]); + var_dump($cursor->toArray()[0]); The output would resemble: @@ -69,9 +72,11 @@ The output would resemble: } } -The following example executes a :manual:`listCollections -` command, which returns a cursor with -multiple result documents: +Some database commands return a cursor with multiple results. The following +example executes :manual:`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 @@ -81,7 +86,7 @@ multiple result documents: $cursor = $database->command(['listCollections' => 1]); - var_dump($c->toArray()); + var_dump($cursor->toArray()); The output would resemble: diff --git a/docs/reference/method/MongoDBDatabase-getReadConcern.txt b/docs/reference/method/MongoDBDatabase-getReadConcern.txt index 4b02a1dd9..56568aa4b 100644 --- a/docs/reference/method/MongoDBDatabase-getReadConcern.txt +++ b/docs/reference/method/MongoDBDatabase-getReadConcern.txt @@ -36,7 +36,7 @@ Example selectDatabase('test', [ - 'readConcern' => new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::MAJORITY), + 'readConcern' => new MongoDB\Driver\ReadConcern('majority'), ]); var_dump($database->getReadConcern()); diff --git a/docs/reference/method/MongoDBDatabase-selectCollection.txt b/docs/reference/method/MongoDBDatabase-selectCollection.txt index 6294e1a75..fb17687b4 100644 --- a/docs/reference/method/MongoDBDatabase-selectCollection.txt +++ b/docs/reference/method/MongoDBDatabase-selectCollection.txt @@ -71,7 +71,7 @@ database with a custom read preference: $users = $db->selectCollection( 'users', [ - 'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY), + 'readPreference' => new MongoDB\Driver\ReadPreference('primaryPreferred'), ] ); diff --git a/docs/reference/method/MongoDBDatabase-selectGridFSBucket.txt b/docs/reference/method/MongoDBDatabase-selectGridFSBucket.txt index 9c63fdf7c..f93906276 100644 --- a/docs/reference/method/MongoDBDatabase-selectGridFSBucket.txt +++ b/docs/reference/method/MongoDBDatabase-selectGridFSBucket.txt @@ -71,7 +71,7 @@ database with a custom read preference: $imagesBucket = $db->selectGridFSBucket([ 'bucketName' => 'images', - 'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY), + 'readPreference' => new MongoDB\Driver\ReadPreference('primaryPreferred'), ]); See Also diff --git a/docs/reference/method/MongoDBDatabase-withOptions.txt b/docs/reference/method/MongoDBDatabase-withOptions.txt index 9bc0a82ea..6f732eacc 100644 --- a/docs/reference/method/MongoDBDatabase-withOptions.txt +++ b/docs/reference/method/MongoDBDatabase-withOptions.txt @@ -52,7 +52,7 @@ preference: $db = (new MongoDB\Client)->test; $newDb = $db->withOptions([ - 'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY), + 'readPreference' => new MongoDB\Driver\ReadPreference('primaryPreferred'), ]); See Also diff --git a/docs/reference/method/MongoDBGridFSBucket-getReadConcern.txt b/docs/reference/method/MongoDBGridFSBucket-getReadConcern.txt index d9c0a8e2a..7b12c0513 100644 --- a/docs/reference/method/MongoDBGridFSBucket-getReadConcern.txt +++ b/docs/reference/method/MongoDBGridFSBucket-getReadConcern.txt @@ -37,7 +37,7 @@ Example $database = (new MongoDB\Client)->selectDatabase('test'); $bucket = $database->selectGridFSBucket([ - 'readConcern' => new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::MAJORITY), + 'readConcern' => new MongoDB\Driver\ReadConcern('majority'), ]); var_dump($bucket->getReadConcern()); diff --git a/docs/reference/method/MongoDBModelIndexInfo-isGeoHaystack.txt b/docs/reference/method/MongoDBModelIndexInfo-isGeoHaystack.txt index a2ee99e55..97f844f10 100644 --- a/docs/reference/method/MongoDBModelIndexInfo-isGeoHaystack.txt +++ b/docs/reference/method/MongoDBModelIndexInfo-isGeoHaystack.txt @@ -17,13 +17,17 @@ Definition .. phpmethod:: MongoDB\\Model\\IndexInfo::isGeoHaystack() - Return whether the index is a :manual:`geoHaystack - ` index. + Return whether the index is a :manual:`geoHaystack ` + index. .. code-block:: php function isGeoHaystack(): boolean + .. note:: + + MongoDB 5.0 and later no longer supports geoHaystack indexes. + Return Values ------------- diff --git a/docs/tutorial/commands.txt b/docs/tutorial/commands.txt index 68a5ec268..bccf74626 100644 --- a/docs/tutorial/commands.txt +++ b/docs/tutorial/commands.txt @@ -20,17 +20,18 @@ The |php-library| provides helper methods across the :phpclass:`Client :phpmethod:`MongoDB\\Database::command()` method may be used to run database commands that do not have a helper method. -Execute Database Commands -------------------------- +The :phpmethod:`MongoDB\\Database::command()` method always returns a +:php:`MongoDB\\Driver\\Cursor ` object, since it must +support execution of commands that return single result documents *and* multiple +results via a command cursor. -Basic Command -~~~~~~~~~~~~~ +Commands That Return a Single Result Document +--------------------------------------------- -To execute a command on a :program:`mongod` instance, use the -:phpmethod:`MongoDB\\Database::command()` method. For instance, the following -operation uses the :manual:`geoNear ` command to -search for the three closest documents to longitude ``-74`` and latitude ``40`` -in the ``restos`` collection in the ``test`` database: +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 ` command +and prints its result document: .. code-block:: php @@ -38,196 +39,90 @@ in the ``restos`` collection in the ``test`` database: $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]; + $cursor = $database->command(['ping' => 1]); - var_dump($results); + var_dump($cursor->toArray()[0]); -The output would then resemble: +The output would resemble: .. code-block:: none - object(MongoDB\Model\BSONDocument)#27 (1) { + object(MongoDB\Model\BSONDocument)#11 (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) - } - } + array(1) { ["ok"]=> float(1) } } -Commands with Custom Read Preference -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Commands That Yield Multiple Results +------------------------------------ + +Some database commands return a cursor with multiple results. The following +example executes :manual:`listCollections `, +which returns a cursor containing a result document for each collection in the +``test`` database, and iterates through the results using a ``foreach`` loop. +Note that this example is illustrative; applications would generally use +:phpmethod:`MongoDB\\Database::listCollections()` in practice. + +.. code-block:: php + + test; + + $cursor = $database->command(['listCollections' => 1]); + + foreach ($cursor as $collection) { + echo $collection['name'], "\n"; + } + +The output might resemble the following: + +.. code-block:: none + + persons + posts + zips -Some commands, such as :manual:`createUser `, may -only be executed on a :term:`primary` replica set member or a -:term:`standalone`. +.. note:: -The command helper methods in the |php-library|, such as + At the *protocol* level, commands that yield multiple results via a cursor + will return a single result document with the essential ingredients for + constructing the cursor (i.e. the cursor's ID, namespace, and an optional + first batch of results). If the :php:`MongoDB\Driver\Manager::executeCommand() + ` method in the PHP driver detects + such a response, it will construct an iterable command cursor and return it + instead of the raw result document. If necessary, raw result documents can + still be observed using `command monitoring + `_. + +Specifying a Custom Read Preference +----------------------------------- + +Write commands, such as :manual:`createUser `, +can only be executed on a writable server (e.g. :term:`primary` replica set +member). Command helper methods in the |php-library|, such as :phpmethod:`MongoDB\\Database::drop()`, know to apply their own :term:`read preference` if necessary. However, the :phpmethod:`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. +object on which it is invoked. When necessary, the ``readPreference`` option may +be used to override the default read preference. -The following example adds a user to the ``test`` database and specifies a -custom read preference: +The following example connects to a cluster and specifies ``secondaryPreferred`` +as the Client's default read preference. It then specifies a ``primary`` read +preference when executing the ``createUser`` command on the ``test`` database: .. code-block:: php test; + $client = new MongoDB\Client( + 'mongodb+srv://cluster0.example.com', + ['readPreference' => 'secondaryPreferred'] + ); + + $client->test; $cursor = $db->command( [ @@ -236,7 +131,7 @@ custom read preference: 'roles' => ['readWrite'], ], [ - 'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_PRIMARY), + 'readPreference' => new MongoDB\Driver\ReadPreference('primary'), ] ); @@ -253,81 +148,3 @@ The output would then resemble: float(1) } } - -View Command Results --------------------- - -View Single Result Documents -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The :phpmethod:`MongoDB\\Database::command()` method returns a -:php:`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: - -.. code-block:: php - - test; - - $cursor = $database->command(['ping' => 1]); - - var_dump($cursor->toArray()[0]); - -The output would then resemble: - -.. code-block:: none - - object(MongoDB\Model\BSONDocument)#2 (1) { - ["storage":"ArrayObject":private]=> - array(1) { - ["ok"]=> - float(1) - } - } - -Iterate Results from a Cursor -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Some commands, such as :manual:`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: - -.. code-block:: php - - 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: - -.. code-block:: none - - 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 - :php:`MongoDB\Driver\Manager::executeCommand() - ` method detects such a result and - constructs the iterable command cursor, which is returned rather than the - base result document.