From baa04c9862f5e620d9d0cc28e18aef0aa4a381ad Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 11 Sep 2024 11:27:57 -0400 Subject: [PATCH 1/9] DOCSP-41963: Databases and collections --- source/databases-collections.txt | 276 ++++++++++++++++++ .../databases-collections.php | 82 ++++++ source/index.txt | 1 + 3 files changed, 359 insertions(+) create mode 100644 source/databases-collections.txt create mode 100644 source/includes/databases-collections/databases-collections.php diff --git a/source/databases-collections.txt b/source/databases-collections.txt new file mode 100644 index 00000000..acec9fb3 --- /dev/null +++ b/source/databases-collections.txt @@ -0,0 +1,276 @@ +.. _php-databases-collections: + +========================= +Databases and Collections +========================= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: table, row, organize, storage, code example + +Overview +-------- + +In this guide, you can learn how to use MongoDB databases and +collections with the {+php-library+}. + +MongoDB organizes data into a hierarchy of the following levels: + +- **Databases**: Top-level data structures in a MongoDB deployment that store collections. +- **Collections**: Groups of MongoDB documents. They are analogous to tables in relational databases. +- **Documents**: Units that store literal data such as string, numbers, dates, and other embedded documents. + For more information about document field types and structure, see the + :manual:`Documents ` guide in the {+mdb-server+} manual. + +Access a Database +----------------- + +Access a database by passing the database name to the ``MongoDB\Client::selectDatabase()`` +method. + +The following example accesses a database named ``'test_database'``: + +.. literalinclude:: /includes/databases-collections/databases-collections.php + :language: php + :dedent: + :start-after: start-access-database + :end-before: end-access-database + +.. _php-db-coll-access-collection: + +Access a Collection +------------------- + +Access a collection by using either of the following methods: + +- ``MongoDB\Client::selectCollection()``: Pass the database and collection names as + parameters +- ``MongoDB\Database::selectCollection()``: Pass the collection name as a parameter + +The following example accesses a collection named ``test_collection`` by using the +``MongoDB\Database::selectCollection()`` method: + +.. literalinclude:: /includes/databases-collections/databases-collections.php + :language: php + :dedent: + :start-after: start-access-collection + :end-before: end-access-collection + +.. tip:: + + If the provided collection name does not already exist in the database, + MongoDB implicitly creates the collection when you first insert data + into it. + +.. _php-db-coll-create-collection: + +Create a Collection +------------------- + +Pass a collection name to the ``MongoDB\Database::createCollection()`` method to +explicitly create a collection in a MongoDB database. + +The following example creates a collection named ``example_collection``: + +.. literalinclude:: /includes/databases-collections/databases-collections.php + :language: php + :dedent: + :start-after: start-create-collection + :end-before: end-create-collection + +You can specify collection options, such as maximum size and document +validation rules, by passing them as an array parameter to ``createCollection()``. +For a full list of optional parameters, see the `API documentation +<{+api+}/method/MongoDBDatabase-createCollection/#parameters>`__. + +Get a List of Collections +------------------------- + +You can query for a list of collections in a database by calling the +``MongoDB\Database::listCollections()`` method. The method returns a +cursor containing all collections in the database and their associated metadata. + +The following example calls the ``listCollections()`` method and iterates over +the returned cursor to print the collections from the :ref:`php-db-coll-access-collection` +and :ref:`php-db-coll-create-collection` examples: + +.. io-code-block:: + :copyable: + + .. input:: /includes/databases-collections/databases-collections.php + :language: php + :start-after: start-find-collections + :end-before: end-find-collections + :dedent: + + .. output:: + :language: console + :visible: false + + Collection: { "name" : "test_collection", "type" : "collection", ...} + Collection: { "name" : "example_collection", "type" : "collection", ... } + +For more information about iterating over a cursor, see the :ref:`php-cursors` +guide. + +Delete a Collection +------------------- + +You can delete a collection from the database by using the ``MongoDB\Database::dropCollection()`` +method. + +The following example deletes the ``test_collection`` collection: + +.. literalinclude:: /includes/databases-collections/databases-collections.php + :language: php + :dedent: + :start-after: start-drop-collection + :end-before: end-drop-collection + +.. warning:: Dropping a Collection Deletes All Data in the Collection + + Dropping a collection from your database permanently deletes all + documents and all indexes within that collection. + + Drop a collection only if the data in it is no longer needed. + +.. _php-config-read-write: + +Configure Read and Write Operations +----------------------------------- + +You can control how the library routes read operations by setting a **read preference**. +You can also control options for how the library waits for acknowledgment of +read and write operations on a replica set by setting a **read concern** and a +**write concern**. + +By default, databases inherit read and write settings from the ``MongoDB\Client`` +instance, and collections inherit them from the database. However, you can change +these settings on your database by passing an options array to the +``MongoDB\Client::selectDatabase()``. You can change these settings on your collection +by passing an options array to the ``MongoDB\Client::selectCollection()`` method. + +To change the read preference, read concern, and write concern of your database +or collection, set the following options in the array parameter: + +- ``readPreference``: Sets the read preference. For a list of available read + preferences, see `MongoDB\Driver\ReadPreference <{+php-manual}/class.mongodb-driver-readpreference>`__ + in the extension API documentation. +- ``readConcern``: Sets the read concern. For a list of available read + concerns, see `MongoDB\Driver\ReadConcern <{+php-manual}/class.mongodb-driver-readconcern>`__ + in the extension API documentation. +- ``writeConcern``: Sets the write concern. For a list of available write + concerns, see `MongoDB\Driver\ReadConcern <{+php-manual}/class.mongodb-driver-writeconcern>`__ + in the extension API documentation. + +.. tip:: + + To learn more about the read and write settings, see the following guides in the + MongoDB Server manual: + + - :manual:`Read Preference ` + - :manual:`Read Concern ` + - :manual:`Write Concern ` + +Database Configuration Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following example shows how to set the read preference, read concern and +write preference of a database called ``test_database`` by passing an options +array to ``selectDatabase()``: + +.. literalinclude:: /includes/databases-collections/databases-collections.php + :language: php + :dedent: + :start-after: start-database-settings + :end-before: end-database-settings + +Collection Configuration Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following example shows how to set the read preference, read concern and +write preference of a collection called ``test_collection`` by passing an options +array to ``selectCollection()``: + +.. literalinclude:: /includes/databases-collections/databases-collections.php + :language: php + :dedent: + :start-after: start-collection-settings + :end-before: end-collection-settings + +Tag Sets +~~~~~~~~ + +In {+mdb-server+}, you can apply key-value :manual:`tags +` to replica-set +members according to any criteria you choose. You can then use +those tags to target one or more members for a read operation. + +By default, the {+php-library+} ignores tags when choosing a member +to read from. To instruct the {+php-library+} to prefer certain tags, +pass them as a parameter to your ``MongoDB\Driver\ReadPreference`` class +constructor. Then, set the ``MongoDB\Driver\ReadPreference`` object as +the value of the ``readPreference`` database option. + +The following code example sets the ``readPreference`` option to a tag set +that instructs the {+php-library+} to prefer reads from the New York data +center (``'dc' => 'ny'``) and to fall back to the San Francisco data +center (``'dc' => 'sf'``): + +.. literalinclude:: /includes/databases-collections/databases-collections.php + :language: php + :dedent: + :start-after: start-tag-set + :end-before: end-tag-set + +Local Threshold +~~~~~~~~~~~~~~~ + +If multiple replica-set members match the read preference and tag sets you specify, +the {+php-library+} reads from the nearest replica-set members, chosen according to +their ping time. + +By default, the library uses only those members whose ping times are within 15 milliseconds +of the nearest member for queries. To distribute reads between members with +higher latencies, pass an options array to the ``MongoDB\Client`` constructor that +sets the ``localThresholdMS`` option. + +The following example specifies a local threshold of 35 milliseconds: + +.. literalinclude:: /includes/databases-collections/databases-collections.php + :language: php + :dedent: + :start-after: start-local-threshold + :end-before: end-local-threshold + +In the preceding example, the {+php-library+} distributes reads between matching members +within 35 milliseconds of the closest member's ping time. + +.. note:: + + The {+php-library+} ignores the value of ``localThresholdMS`` when communicating with a + replica set through a ``mongos`` instance. In this case, use the + :manual:`localThreshold ` + command-line option. + +API Documentation +----------------- + +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: + +- `MongoDB\\Client::selectDatabase() <{+api+}/method/MongoDBClient-selectDatabase/>`__ +- `MongoDB\\Client::selectCollection() <{+api+}/method/MongoDBClient-selectCollection/>`__ +- `MongoDB\\Database::selectCollection() <{+api+}/method/MongoDBDatabase-selectCollection/>`__ +- `MongoDB\\Database::createCollection() <{+api+}/method/MongoDBDatabase-createCollection/>`__ +- `MongoDB\\Database::listCollections() <{+api+}/method/MongoDBDatabase-listCollections/>`__ +- `MongoDB\\Database::dropCollection() <{+api+}/method/MongoDBDatabase-dropCollection/>`__ \ No newline at end of file diff --git a/source/includes/databases-collections/databases-collections.php b/source/includes/databases-collections/databases-collections.php new file mode 100644 index 00000000..44e3a4de --- /dev/null +++ b/source/includes/databases-collections/databases-collections.php @@ -0,0 +1,82 @@ +selectDatabase('test_database'); +// end-access-database + +// start-access-collection +$collection = $client->test_database->selectCollection('test_collection'); +// end-access-collection + +// start-create-collection +$result = $client->test_database->createCollection('example_collection'); +// end-create-collection + +// start-find-collections +foreach ($db->listCollections() as $collectionInfo) { + echo json_encode($collectionInfo), PHP_EOL; +} +// end-find-collections + +// start-drop-collection +$db->dropCollection('test_collection'); +// end-drop-collection + +// start-database-settings +$readPreference = new ReadPreference(ReadPreference::RP_SECONDARY); +$readConcern = new ReadConcern(ReadConcern::LOCAL); +$writeConcern = new WriteConcern(WriteConcern::MAJORITY); + +$db = $client->selectDatabase('test_database', [ + 'readPreference' => $readPreference, + 'readConcern' => $readConcern, + 'writeConcern' => $writeConcern, +]); + +// end-database-settings + +// start-collection-settings +$readPreference = new ReadPreference(ReadPreference::RP_PRIMARY); +$readConcern = new ReadConcern(ReadConcern::AVAILABLE); +$writeConcern = new WriteConcern(WriteConcern::MAJORITY); + +// Specify the preferences when selecting a collection +$collection = $client->selectCollection('test_database', 'test_collection', [ + 'readPreference' => $readPreference, + 'readConcern' => $readConcern, + 'writeConcern' => $writeConcern, +]); + +// end-collection-settings + +// start-tag-set +$readPreference = new ReadPreference( + ReadPreference::RP_SECONDARY, + [ + ['dc' => 'ny'], + ['dc' => 'sf'], + ], +); + +$db = $client->selectDatabase( + 'test_database', + ['readPreference' => $readPreference], +); + +// end-tag-set + +// start-local-threshold +$options = [ + 'replicaSet' => 'repl0', + 'readPreference' => new ReadPreference(ReadPreference::RP_SECONDARY_PREFERRED), + 'localThresholdMS' => 35 +]; + +$client = new Client('', [], $options); +// end-local-threshold \ No newline at end of file diff --git a/source/index.txt b/source/index.txt index b4b4841a..dc7ad712 100644 --- a/source/index.txt +++ b/source/index.txt @@ -11,6 +11,7 @@ MongoDB PHP Library :titlesonly: Get Started + /databases-collections /read /write /aggregation From 30ca6b80437653ffff99a44200961b12888c496f Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 11 Sep 2024 11:55:45 -0400 Subject: [PATCH 2/9] edits --- source/databases-collections.txt | 28 +++++++++++++------ .../databases-collections.php | 23 +++++++++++---- 2 files changed, 37 insertions(+), 14 deletions(-) diff --git a/source/databases-collections.txt b/source/databases-collections.txt index acec9fb3..645f8ad1 100644 --- a/source/databases-collections.txt +++ b/source/databases-collections.txt @@ -37,7 +37,7 @@ Access a Database Access a database by passing the database name to the ``MongoDB\Client::selectDatabase()`` method. -The following example accesses a database named ``'test_database'``: +The following example accesses a database named ``test_database``: .. literalinclude:: /includes/databases-collections/databases-collections.php :language: php @@ -116,8 +116,18 @@ and :ref:`php-db-coll-create-collection` examples: :language: console :visible: false - Collection: { "name" : "test_collection", "type" : "collection", ...} - Collection: { "name" : "example_collection", "type" : "collection", ... } + MongoDB\Model\CollectionInfo Object + ( + [name] => example_collection + [type] => collection + ... + ) + MongoDB\Model\CollectionInfo Object + ( + [name] => test_collection + [type] => collection + ... + ) For more information about iterating over a cursor, see the :ref:`php-cursors` guide. @@ -163,13 +173,13 @@ To change the read preference, read concern, and write concern of your database or collection, set the following options in the array parameter: - ``readPreference``: Sets the read preference. For a list of available read - preferences, see `MongoDB\Driver\ReadPreference <{+php-manual}/class.mongodb-driver-readpreference>`__ + preferences, see `MongoDB\\Driver\\ReadPreference <{+php-manual+}/class.mongodb-driver-readpreference>`__ in the extension API documentation. - ``readConcern``: Sets the read concern. For a list of available read - concerns, see `MongoDB\Driver\ReadConcern <{+php-manual}/class.mongodb-driver-readconcern>`__ + concerns, see `MongoDB\\Driver\\ReadConcern <{+php-manual+}/class.mongodb-driver-readconcern>`__ in the extension API documentation. - ``writeConcern``: Sets the write concern. For a list of available write - concerns, see `MongoDB\Driver\ReadConcern <{+php-manual}/class.mongodb-driver-writeconcern>`__ + concerns, see `MongoDB\\Driver\\ReadConcern <{+php-manual+}/class.mongodb-driver-writeconcern>`__ in the extension API documentation. .. tip:: @@ -184,7 +194,7 @@ or collection, set the following options in the array parameter: Database Configuration Example ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following example shows how to set the read preference, read concern and +The following example shows how to set the read preference, read concern, and write preference of a database called ``test_database`` by passing an options array to ``selectDatabase()``: @@ -197,7 +207,7 @@ array to ``selectDatabase()``: Collection Configuration Example ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following example shows how to set the read preference, read concern and +The following example shows how to set the read preference, read concern, and write preference of a collection called ``test_collection`` by passing an options array to ``selectCollection()``: @@ -222,7 +232,7 @@ constructor. Then, set the ``MongoDB\Driver\ReadPreference`` object as the value of the ``readPreference`` database option. The following code example sets the ``readPreference`` option to a tag set -that instructs the {+php-library+} to prefer reads from the New York data +that instructs ``test_database`` to prefer reads from the New York data center (``'dc' => 'ny'``) and to fall back to the San Francisco data center (``'dc' => 'sf'``): diff --git a/source/includes/databases-collections/databases-collections.php b/source/includes/databases-collections/databases-collections.php index 44e3a4de..ed0eeca7 100644 --- a/source/includes/databases-collections/databases-collections.php +++ b/source/includes/databases-collections/databases-collections.php @@ -2,32 +2,43 @@ require 'vendor/autoload.php'; use MongoDB\BSON\Document; +use MongoDB\Driver\ReadConcern; +use MongoDB\Driver\ReadPreference; +use MongoDB\Driver\WriteConcern; $uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset'); $client = new MongoDB\Client($uri); +// Accesses the "test_database" database // start-access-database $db = $client->selectDatabase('test_database'); // end-access-database +// Accesses the "test_collection" collection // start-access-collection $collection = $client->test_database->selectCollection('test_collection'); +//$collection->insertOne(['name' => 'first doc']); // end-access-collection +// Explicitly creates the "example_collection" collection // start-create-collection $result = $client->test_database->createCollection('example_collection'); +//$db->example_collection->insertOne(['name' => 'second doc']); // end-create-collection +// Lists the collections in the "test_database" database // start-find-collections -foreach ($db->listCollections() as $collectionInfo) { - echo json_encode($collectionInfo), PHP_EOL; +foreach ($client->test_database->listCollections() as $collectionInfo) { + print_r($collectionInfo) . PHP_EOL; } // end-find-collections +// Deletes the "test_collection" collection // start-drop-collection -$db->dropCollection('test_collection'); +$client->test_database->dropCollection('test_collection'); // end-drop-collection +// Sets read and write settings for the "test_database" database // start-database-settings $readPreference = new ReadPreference(ReadPreference::RP_SECONDARY); $readConcern = new ReadConcern(ReadConcern::LOCAL); @@ -38,15 +49,14 @@ 'readConcern' => $readConcern, 'writeConcern' => $writeConcern, ]); - // end-database-settings +// Sets read and write settings for the "test_collection" collection // start-collection-settings $readPreference = new ReadPreference(ReadPreference::RP_PRIMARY); $readConcern = new ReadConcern(ReadConcern::AVAILABLE); $writeConcern = new WriteConcern(WriteConcern::MAJORITY); -// Specify the preferences when selecting a collection $collection = $client->selectCollection('test_database', 'test_collection', [ 'readPreference' => $readPreference, 'readConcern' => $readConcern, @@ -55,6 +65,7 @@ // end-collection-settings +// Instructs the library to prefer New York data center reads using a tag set // start-tag-set $readPreference = new ReadPreference( ReadPreference::RP_SECONDARY, @@ -71,6 +82,8 @@ // end-tag-set +// Instructs the library to distribute reads between members within 35 milliseconds +// of the closest member's ping time // start-local-threshold $options = [ 'replicaSet' => 'repl0', From d2ef21a7cbb3070c550541cf627efbb2836d0ef0 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 11 Sep 2024 11:59:59 -0400 Subject: [PATCH 3/9] phpmethod --- source/databases-collections.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/databases-collections.txt b/source/databases-collections.txt index 645f8ad1..a8061e56 100644 --- a/source/databases-collections.txt +++ b/source/databases-collections.txt @@ -278,9 +278,9 @@ API Documentation To learn more about any of the methods or types discussed in this guide, see the following API documentation: -- `MongoDB\\Client::selectDatabase() <{+api+}/method/MongoDBClient-selectDatabase/>`__ -- `MongoDB\\Client::selectCollection() <{+api+}/method/MongoDBClient-selectCollection/>`__ -- `MongoDB\\Database::selectCollection() <{+api+}/method/MongoDBDatabase-selectCollection/>`__ -- `MongoDB\\Database::createCollection() <{+api+}/method/MongoDBDatabase-createCollection/>`__ -- `MongoDB\\Database::listCollections() <{+api+}/method/MongoDBDatabase-listCollections/>`__ -- `MongoDB\\Database::dropCollection() <{+api+}/method/MongoDBDatabase-dropCollection/>`__ \ No newline at end of file +- :phpmethod:`MongoDB\Client::selectDatabase()` +- :phpmethod:`MongoDB\Client::selectCollection()` +- :phpmethod:`MongoDB\Database::selectCollection()` +- :phpmethod:`MongoDB\Database::createCollection()` +- :phpmethod:`MongoDB\Database::listCollections()` +- :phpmethod:`MongoDB\Database::dropCollection()` \ No newline at end of file From f7d2e7164ed4ab3e7b9b2175f337e36044e8acc9 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 11 Sep 2024 12:03:21 -0400 Subject: [PATCH 4/9] code fix --- source/includes/databases-collections/databases-collections.php | 2 -- 1 file changed, 2 deletions(-) diff --git a/source/includes/databases-collections/databases-collections.php b/source/includes/databases-collections/databases-collections.php index ed0eeca7..0d7d7976 100644 --- a/source/includes/databases-collections/databases-collections.php +++ b/source/includes/databases-collections/databases-collections.php @@ -17,13 +17,11 @@ // Accesses the "test_collection" collection // start-access-collection $collection = $client->test_database->selectCollection('test_collection'); -//$collection->insertOne(['name' => 'first doc']); // end-access-collection // Explicitly creates the "example_collection" collection // start-create-collection $result = $client->test_database->createCollection('example_collection'); -//$db->example_collection->insertOne(['name' => 'second doc']); // end-create-collection // Lists the collections in the "test_database" database From 7ca261ddebdecad201319b2115f9f490238bebac Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 12 Sep 2024 10:12:54 -0400 Subject: [PATCH 5/9] MW feedback --- source/databases-collections.txt | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/source/databases-collections.txt b/source/databases-collections.txt index a8061e56..d05e4b18 100644 --- a/source/databases-collections.txt +++ b/source/databases-collections.txt @@ -88,7 +88,7 @@ The following example creates a collection named ``example_collection``: :end-before: end-create-collection You can specify collection options, such as maximum size and document -validation rules, by passing them as an array parameter to ``createCollection()``. +validation rules, by passing them as an array to the ``createCollection()`` method. For a full list of optional parameters, see the `API documentation <{+api+}/method/MongoDBDatabase-createCollection/#parameters>`__. @@ -151,7 +151,7 @@ The following example deletes the ``test_collection`` collection: Dropping a collection from your database permanently deletes all documents and all indexes within that collection. - Drop a collection only if the data in it is no longer needed. + Drop a collection only if you no longer need the data in it. .. _php-config-read-write: @@ -164,7 +164,7 @@ read and write operations on a replica set by setting a **read concern** and a **write concern**. By default, databases inherit read and write settings from the ``MongoDB\Client`` -instance, and collections inherit them from the database. However, you can change +instance, and collections inherit them from the database. You can change these settings on your database by passing an options array to the ``MongoDB\Client::selectDatabase()``. You can change these settings on your collection by passing an options array to the ``MongoDB\Client::selectCollection()`` method. @@ -179,13 +179,13 @@ or collection, set the following options in the array parameter: concerns, see `MongoDB\\Driver\\ReadConcern <{+php-manual+}/class.mongodb-driver-readconcern>`__ in the extension API documentation. - ``writeConcern``: Sets the write concern. For a list of available write - concerns, see `MongoDB\\Driver\\ReadConcern <{+php-manual+}/class.mongodb-driver-writeconcern>`__ + concerns, see `MongoDB\\Driver\\WriteConcern <{+php-manual+}/class.mongodb-driver-writeconcern>`__ in the extension API documentation. .. tip:: - To learn more about the read and write settings, see the following guides in the - MongoDB Server manual: + To learn more about read preferences and read and write concerns, see the + following guides in the MongoDB Server manual: - :manual:`Read Preference ` - :manual:`Read Concern ` @@ -195,7 +195,7 @@ Database Configuration Example ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following example shows how to set the read preference, read concern, and -write preference of a database called ``test_database`` by passing an options +write concern of a database called ``test_database`` by passing an options array to ``selectDatabase()``: .. literalinclude:: /includes/databases-collections/databases-collections.php @@ -208,7 +208,7 @@ Collection Configuration Example ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following example shows how to set the read preference, read concern, and -write preference of a collection called ``test_collection`` by passing an options +write concern of a collection called ``test_collection`` by passing an options array to ``selectCollection()``: .. literalinclude:: /includes/databases-collections/databases-collections.php @@ -225,11 +225,11 @@ In {+mdb-server+}, you can apply key-value :manual:`tags members according to any criteria you choose. You can then use those tags to target one or more members for a read operation. -By default, the {+php-library+} ignores tags when choosing a member -to read from. To instruct the {+php-library+} to prefer certain tags, -pass them as a parameter to your ``MongoDB\Driver\ReadPreference`` class -constructor. Then, set the ``MongoDB\Driver\ReadPreference`` object as -the value of the ``readPreference`` database option. +The library uses only those members whose ping times are within the local +threshold of the nearest member for queries. By default, the local threshold +is 15 milliseconds of latency. To distribute reads among members with +higher latencies, pass an options array to the ``MongoDB\Client`` constructor that +sets the ``localThresholdMS`` option. The following code example sets the ``readPreference`` option to a tag set that instructs ``test_database`` to prefer reads from the New York data @@ -249,7 +249,7 @@ If multiple replica-set members match the read preference and tag sets you speci the {+php-library+} reads from the nearest replica-set members, chosen according to their ping time. -By default, the library uses only those members whose ping times are within 15 milliseconds +By default, the library only uses members whose ping times are within 15 milliseconds of the nearest member for queries. To distribute reads between members with higher latencies, pass an options array to the ``MongoDB\Client`` constructor that sets the ``localThresholdMS`` option. @@ -262,7 +262,7 @@ The following example specifies a local threshold of 35 milliseconds: :start-after: start-local-threshold :end-before: end-local-threshold -In the preceding example, the {+php-library+} distributes reads between matching members +In the preceding example, the {+php-library+} distributes reads among matching members within 35 milliseconds of the closest member's ping time. .. note:: From 7641f90b85c5a12bfa5b539b2cdce720b745c879 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 12 Sep 2024 10:50:24 -0400 Subject: [PATCH 6/9] fix --- source/databases-collections.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/databases-collections.txt b/source/databases-collections.txt index d05e4b18..3b613ce4 100644 --- a/source/databases-collections.txt +++ b/source/databases-collections.txt @@ -225,11 +225,11 @@ In {+mdb-server+}, you can apply key-value :manual:`tags members according to any criteria you choose. You can then use those tags to target one or more members for a read operation. -The library uses only those members whose ping times are within the local -threshold of the nearest member for queries. By default, the local threshold -is 15 milliseconds of latency. To distribute reads among members with -higher latencies, pass an options array to the ``MongoDB\Client`` constructor that -sets the ``localThresholdMS`` option. +By default, the {+php-library+} ignores tags when choosing a member +to read from. To instruct the {+php-library+} to prefer certain tags, +pass them as a parameter to your ``MongoDB\Driver\ReadPreference`` class +constructor. Then, set the ``MongoDB\Driver\ReadPreference`` object as +the value of the ``readPreference`` database option. The following code example sets the ``readPreference`` option to a tag set that instructs ``test_database`` to prefer reads from the New York data From c814318d90580383be7cd2b2431761bbb299b514 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 12 Sep 2024 17:04:32 -0400 Subject: [PATCH 7/9] MW feedback 2 --- source/databases-collections.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/databases-collections.txt b/source/databases-collections.txt index 3b613ce4..42d7b651 100644 --- a/source/databases-collections.txt +++ b/source/databases-collections.txt @@ -249,7 +249,7 @@ If multiple replica-set members match the read preference and tag sets you speci the {+php-library+} reads from the nearest replica-set members, chosen according to their ping time. -By default, the library only uses members whose ping times are within 15 milliseconds +By default, the library uses only members whose ping times are within 15 milliseconds of the nearest member for queries. To distribute reads between members with higher latencies, pass an options array to the ``MongoDB\Client`` constructor that sets the ``localThresholdMS`` option. From 6ff3578d8a55f241c8f83379371c8b7ca4cdddff Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 16 Sep 2024 17:19:33 -0400 Subject: [PATCH 8/9] JM feedback --- source/databases-collections.txt | 59 +++++++++++++++---- .../databases-collections.php | 21 +++++-- 2 files changed, 62 insertions(+), 18 deletions(-) diff --git a/source/databases-collections.txt b/source/databases-collections.txt index 42d7b651..4165b76d 100644 --- a/source/databases-collections.txt +++ b/source/databases-collections.txt @@ -45,6 +45,24 @@ The following example accesses a database named ``test_database``: :start-after: start-access-database :end-before: end-access-database +Alternatively, you can implicitly call the ``MongoDB\Client::__get()`` magic method on +a client object. This method allows you to select a database by using the syntax for +accessing a class property. The following example uses this shorthand syntax to access +the ``test_database`` database: + +.. literalinclude:: /includes/databases-collections/databases-collections.php + :language: php + :dedent: + :start-after: start-access-database-short + :end-before: end-access-database-short + +.. tip:: + + To learn more about ``__get()`` and PHP magic methods, see the following resources: + + - :phpmethod:`MongoDB\Client::__get()` in the API documentation + - `Magic Methods <{+php-manual+}/language.oop5.magic.php>`__ in the PHP manual + .. _php-db-coll-access-collection: Access a Collection @@ -71,6 +89,20 @@ The following example accesses a collection named ``test_collection`` by using t MongoDB implicitly creates the collection when you first insert data into it. +Alternatively, you can implicitly call the ``MongoDB\Database::__get()`` magic method on +a database object. This method allows you to select a collection by using the syntax for +accessing a class property. The following example uses this shorthand syntax to access +the ``test_collection`` collection: + +.. literalinclude:: /includes/databases-collections/databases-collections.php + :language: php + :dedent: + :start-after: start-access-collection-short + :end-before: end-access-collection-short + +To learn more, see the :phpmethod:`MongoDB\Database::__get()` +API documentation. + .. _php-db-coll-create-collection: Create a Collection @@ -100,7 +132,7 @@ You can query for a list of collections in a database by calling the cursor containing all collections in the database and their associated metadata. The following example calls the ``listCollections()`` method and iterates over -the returned cursor to print the collections from the :ref:`php-db-coll-access-collection` +the returned iterator to print the collections from the :ref:`php-db-coll-access-collection` and :ref:`php-db-coll-create-collection` examples: .. io-code-block:: @@ -129,9 +161,6 @@ and :ref:`php-db-coll-create-collection` examples: ... ) -For more information about iterating over a cursor, see the :ref:`php-cursors` -guide. - Delete a Collection ------------------- @@ -164,22 +193,23 @@ read and write operations on a replica set by setting a **read concern** and a **write concern**. By default, databases inherit read and write settings from the ``MongoDB\Client`` -instance, and collections inherit them from the database. You can change -these settings on your database by passing an options array to the -``MongoDB\Client::selectDatabase()``. You can change these settings on your collection -by passing an options array to the ``MongoDB\Client::selectCollection()`` method. +instance. Collections inherit these settings from the ``MongoDB\Client`` or +``MongoDB\Database`` instance on which the ``selectCollection()`` method is called. +You can change these settings by passing an options array to the +``MongoDB\Client::selectDatabase()``, ``MongoDB\Client::selectCollection()``, or +``MongoDB\Database::selectCollection()`` methods. To change the read preference, read concern, and write concern of your database or collection, set the following options in the array parameter: - ``readPreference``: Sets the read preference. For a list of available read - preferences, see `MongoDB\\Driver\\ReadPreference <{+php-manual+}/class.mongodb-driver-readpreference>`__ + preferences, see :php:`MongoDB\Driver\ReadPreference ` in the extension API documentation. - ``readConcern``: Sets the read concern. For a list of available read - concerns, see `MongoDB\\Driver\\ReadConcern <{+php-manual+}/class.mongodb-driver-readconcern>`__ + concerns, see :php:`MongoDB\Driver\ReadConcern ` in the extension API documentation. - ``writeConcern``: Sets the write concern. For a list of available write - concerns, see `MongoDB\\Driver\\WriteConcern <{+php-manual+}/class.mongodb-driver-writeconcern>`__ + concerns, see :php:`MongoDB\Driver\WriteConcern ` in the extension API documentation. .. tip:: @@ -217,8 +247,11 @@ array to ``selectCollection()``: :start-after: start-collection-settings :end-before: end-collection-settings +Advanced Read Configurations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Tag Sets -~~~~~~~~ +```````` In {+mdb-server+}, you can apply key-value :manual:`tags ` to replica-set @@ -243,7 +276,7 @@ center (``'dc' => 'sf'``): :end-before: end-tag-set Local Threshold -~~~~~~~~~~~~~~~ +``````````````` If multiple replica-set members match the read preference and tag sets you specify, the {+php-library+} reads from the nearest replica-set members, chosen according to diff --git a/source/includes/databases-collections/databases-collections.php b/source/includes/databases-collections/databases-collections.php index 0d7d7976..dae6975a 100644 --- a/source/includes/databases-collections/databases-collections.php +++ b/source/includes/databases-collections/databases-collections.php @@ -1,12 +1,11 @@ selectDatabase('test_database'); // end-access-database +// Invokes the __get() method to access the "test_database" database +// start-access-database-short +$db = $client->test_database; +// end-access-database-short + // Accesses the "test_collection" collection // start-access-collection $collection = $client->test_database->selectCollection('test_collection'); // end-access-collection +// Invokes the __get() method to access the "test_collection" collection +// start-access-collection-short +$collection = $db->test_collection; +// end-access-collection-short + // Explicitly creates the "example_collection" collection // start-create-collection $result = $client->test_database->createCollection('example_collection'); @@ -63,13 +72,15 @@ // end-collection-settings -// Instructs the library to prefer New York data center reads using a tag set +// Instructs the library to prefer reads from secondary replica set members +// located in New York but fall back to those in San Francisco // start-tag-set $readPreference = new ReadPreference( ReadPreference::RP_SECONDARY, [ ['dc' => 'ny'], ['dc' => 'sf'], + [], ], ); @@ -86,8 +97,8 @@ $options = [ 'replicaSet' => 'repl0', 'readPreference' => new ReadPreference(ReadPreference::RP_SECONDARY_PREFERRED), - 'localThresholdMS' => 35 + 'localThresholdMS' => 35, ]; $client = new Client('', [], $options); -// end-local-threshold \ No newline at end of file +// end-local-threshold From e91a587f27632f558537b96290178eb13acd56f3 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 17 Sep 2024 11:06:41 -0400 Subject: [PATCH 9/9] JM feedback 2 --- source/databases-collections.txt | 11 +++++++---- .../databases-collections/databases-collections.php | 3 ++- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/source/databases-collections.txt b/source/databases-collections.txt index 4165b76d..1a650dc9 100644 --- a/source/databases-collections.txt +++ b/source/databases-collections.txt @@ -264,10 +264,13 @@ pass them as a parameter to your ``MongoDB\Driver\ReadPreference`` class constructor. Then, set the ``MongoDB\Driver\ReadPreference`` object as the value of the ``readPreference`` database option. -The following code example sets the ``readPreference`` option to a tag set -that instructs ``test_database`` to prefer reads from the New York data -center (``'dc' => 'ny'``) and to fall back to the San Francisco data -center (``'dc' => 'sf'``): +This code example sets the ``readPreference`` option to a tag set +that instructs ``test_database`` to prefer reads from secondary replica set +members in the following order: + +1. Members from the New York data center (``['dc' => 'ny']``) +#. Members from the San Francisco data center (``['dc' => 'sf']``) +#. Any secondary members (``[]``) .. literalinclude:: /includes/databases-collections/databases-collections.php :language: php diff --git a/source/includes/databases-collections/databases-collections.php b/source/includes/databases-collections/databases-collections.php index dae6975a..eb4dde74 100644 --- a/source/includes/databases-collections/databases-collections.php +++ b/source/includes/databases-collections/databases-collections.php @@ -73,7 +73,8 @@ // end-collection-settings // Instructs the library to prefer reads from secondary replica set members -// located in New York but fall back to those in San Francisco +// located in New York, followed by a secondary in San Francisco, and +// lastly fall back to any secondary. // start-tag-set $readPreference = new ReadPreference( ReadPreference::RP_SECONDARY,