diff --git a/source/databases-collections.txt b/source/databases-collections.txt new file mode 100644 index 00000000..1a650dc9 --- /dev/null +++ b/source/databases-collections.txt @@ -0,0 +1,322 @@ +.. _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 + +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 +------------------- + +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. + +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 +------------------- + +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 to the ``createCollection()`` method. +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 iterator 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 + ... + ) + +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 you no longer need the data in it. + +.. _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. 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 :php:`MongoDB\Driver\ReadPreference ` + in the extension API documentation. +- ``readConcern``: Sets the read concern. For a list of available read + concerns, see :php:`MongoDB\Driver\ReadConcern ` + in the extension API documentation. +- ``writeConcern``: Sets the write concern. For a list of available write + concerns, see :php:`MongoDB\Driver\WriteConcern ` + in the extension API documentation. + +.. tip:: + + 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 ` + - :manual:`Write Concern ` + +Database Configuration Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following example shows how to set the read preference, read concern, and +write concern 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 concern 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 + +Advanced Read Configurations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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. + +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 + :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 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 among 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: + +- :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 diff --git a/source/includes/databases-collections/databases-collections.php b/source/includes/databases-collections/databases-collections.php new file mode 100644 index 00000000..eb4dde74 --- /dev/null +++ b/source/includes/databases-collections/databases-collections.php @@ -0,0 +1,105 @@ +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'); +// 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 reads from secondary replica set members +// 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, + [ + ['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('', [], $options); +// end-local-threshold 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