DOCSP-41963: Databases and collections

source/databases-collections.txt

@@ -0,0 +1,286 @@
+.. _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 </core/document/>` 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
+
+      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. 
+
+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 </core/read-preference/>`
+   - :manual:`Read Concern </reference/read-concern/>`
+   - :manual:`Write Concern </reference/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
+</core/read-preference-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 ``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'``):
+
+.. 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 </reference/program/mongos/#std-option-mongos.--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:
+
+- :phpmethod:`MongoDB\Client::selectDatabase()`
+- :phpmethod:`MongoDB\Client::selectCollection()`
+- :phpmethod:`MongoDB\Database::selectCollection()`
+- :phpmethod:`MongoDB\Database::createCollection()`
+- :phpmethod:`MongoDB\Database::listCollections()`
+- :phpmethod:`MongoDB\Database::dropCollection()`

source/includes/databases-collections/databases-collections.php

@@ -0,0 +1,93 @@
+<?php
+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');
+// end-access-collection
+
+// Explicitly creates the "example_collection" collection
+// start-create-collection
+$result = $client->test_database->createCollection('example_collection');
+// end-create-collection
+
+// Lists the collections in the "test_database" database
+// start-find-collections
+foreach ($client->test_database->listCollections() as $collectionInfo) {
+    print_r($collectionInfo) . PHP_EOL;
+}
+// end-find-collections
+
+// Deletes the "test_collection" collection
+// start-drop-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);
+$writeConcern = new WriteConcern(WriteConcern::MAJORITY);
+
+$db = $client->selectDatabase('test_database', [
+    'readPreference' => $readPreference,
+    '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);
+
+$collection = $client->selectCollection('test_database', 'test_collection', [
+    'readPreference' => $readPreference,
+    'readConcern' => $readConcern,
+    'writeConcern' => $writeConcern,
+]);
+
+// 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,
+    [
+        ['dc' => 'ny'],
+        ['dc' => 'sf'],
+    ],
+);
+
+$db = $client->selectDatabase(
+    'test_database',
+    ['readPreference' => $readPreference],
+);
+
+// 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',
+    'readPreference' => new ReadPreference(ReadPreference::RP_SECONDARY_PREFERRED),
+    'localThresholdMS' => 35
+];
+
+$client = new Client('<connection string>', [], $options);
+// end-local-threshold

source/index.txt

@@ -11,6 +11,7 @@ MongoDB PHP Library
    :titlesonly:
 
    Get Started </get-started>
+   /databases-collections
    /read
    /write
    /aggregation