From 0c9c6e5e4982988c6190f8b9128cd2606092c835 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 12 Aug 2024 12:10:21 -0400 Subject: [PATCH 01/10] DOCSP-41975: Retrieve data --- snooty.toml | 1 + source/includes/read/retrieve.php | 42 ++++++ source/read.txt | 11 ++ source/read/retrieve.txt | 243 ++++++++++++++++++++++++++++++ 4 files changed, 297 insertions(+) create mode 100644 source/includes/read/retrieve.php create mode 100644 source/read.txt create mode 100644 source/read/retrieve.txt diff --git a/snooty.toml b/snooty.toml index a08a8d41..afabcaf9 100644 --- a/snooty.toml +++ b/snooty.toml @@ -24,3 +24,4 @@ php-library = "MongoDB PHP Library" [constants] php-library = "MongoDB PHP Library" +api = "https://www.mongodb.com/docs/php-library/current/reference" \ No newline at end of file diff --git a/source/includes/read/retrieve.php b/source/includes/read/retrieve.php new file mode 100644 index 00000000..b34f7a4e --- /dev/null +++ b/source/includes/read/retrieve.php @@ -0,0 +1,42 @@ +"; +$client = new MongoDB\Client($uri); + +// start-db-coll +$db = $client->sample_training; +$collection = $db->companies; +// end-db-coll + +// Finds one document with a "name" value of "LinkedIn" +// start-find-one +$document = $collection->findOne(['name' => 'LinkedIn']); +echo json_encode($document) . "\n"; +// end-find-one + +// Finds documents with a "founded_year" value of 1970 +// start-find-many +$results = $collection->find(['founded_year' => 1970]); +// end-find-many + +// Prints documents with a "founded_year" value of 1970 +// start-cursor +foreach ($results as $doc) { + echo json_encode($doc) . "\n"; +} +// end-cursor + +// Finds and prints up to 5 documents with a "number_of_employees" value of 1000 +// start-modify +$options = [ + 'limit' => 5, +]; + +$results = $collection->find(['number_of_employees' => 1000], $options); + +foreach ($results as $doc) { + echo json_encode($doc) . "\n"; +} +// end-modify +?> \ No newline at end of file diff --git a/source/read.txt b/source/read.txt new file mode 100644 index 00000000..eb974b7f --- /dev/null +++ b/source/read.txt @@ -0,0 +1,11 @@ +.. _php-read: + +====================== +Read Data from MongoDB +====================== + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /read/retrieve \ No newline at end of file diff --git a/source/read/retrieve.txt b/source/read/retrieve.txt new file mode 100644 index 00000000..f023cef4 --- /dev/null +++ b/source/read/retrieve.txt @@ -0,0 +1,243 @@ +.. _php-retrieve: + +============= +Retrieve Data +============= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code examples, read, query, cursor + +Overview +-------- + +In this guide, you can learn how to use the {+php-library+} to retrieve +data from a MongoDB collection by using **read operations**. You can call the +``MongoDB\Collection::find()`` or ``MongoDB\Collection::findOne()`` method +on a collection to retrieve documents that match a set of criteria. + +Sample Data +~~~~~~~~~~~ + +The examples in this guide use the ``companies`` collection in the ``sample_training`` +database from the :atlas:`Atlas sample datasets `. To access this collection +from your PHP application, instantiate a ``MongoDB\Client`` that connects to an Atlas cluster +and assign the following values to your ``db`` and ``collection`` variables: + +.. literalinclude:: /includes/read/retrieve.php + :language: php + :dedent: + :start-after: start-db-coll + :end-before: end-db-coll + +To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the +:atlas:`Get Started with Atlas ` guide. + +.. _php-retrieve-find: + +Find Documents +-------------- + +The {+php-library+} includes two methods for retrieving documents from a collection: +``MongoDB\Collection::findOne()`` and ``MongoDB\Collection::find()``. These methods +take a **query filter** and return one or more matching documents. A query filter is +an object that specifies the documents you want to retrieve in your query. + +.. TODO: To learn more about query filters, see :ref:`php-specify-query`. + +.. _php-retrieve-find-one: + +Find One Document +~~~~~~~~~~~~~~~~~ + +To find a single document in a collection, call the ``MongoDB\Collection::findOne()`` +method and pass a query filter that specifies the criteria of the document you want to find. + +The ``findOne()`` method returns an ``array``, ``object``, or ``null`` value. If the +query filter matches a document, the method returns an ``array|object`` instance containing +the document. The return type depends on the value of the ``typeMap`` option. If the query +filter does not match any documents, the method returns ``null``. + +.. tip:: + + To learn more about ``findOne()`` options, such as ``typeMap``, see the :ref:`php-retrieve-modify` + section of this guide. + +If the query filter matches more than one document, the ``findOne()`` method returns the *first* +matching document from the retrieved results. + +The following example uses the ``findOne()`` method to find the first document in which +the ``name`` field has the value ``"LinkedIn"``: + +.. io-code-block:: + + .. input:: /includes/read/retrieve.php + :start-after: start-find-one + :end-before: end-find-one + :language: php + :dedent: + + .. output:: + + {"_id":{"$oid":"..."},"name":"LinkedIn","permalink":"linkedin","crunchbase_url": + "http:\/\/www.crunchbase.com\/company\/linkedin","homepage_url":"http:\/\/linkedin.com", + ... + } + +.. tip:: Sort Order + + The ``findOne()`` method returns the first document in + :manual:`natural order ` + on disk if no sort criteria is specified. + +.. _php-retrieve-find-multiple: + +Find Multiple Documents +~~~~~~~~~~~~~~~~~~~~~~~ + +To find multiple documents in a collection, pass a query filter to the +``MongoDB\Collection::find()`` method that specifies the criteria of the +documents you want to retrieve. + +The following example uses the ``find()`` method to find all documents in which +the ``founded_year`` field has the value ``1970``: + +.. literalinclude:: /includes/read/retrieve.php + :language: php + :dedent: + :start-after: start-find-many + :end-before: end-find-many + +The ``find()`` method returns an instance of ``MongoDB\Driver\Cursor``, which you can +iterate over to see the matching documents. A cursor is a mechanism that allows an +application to iterate over database results while holding only a subset of them in +memory at a given time. Cursors are useful when your ``find()`` method returns a large +amount of documents. + +You can iterate over the documents in a cursor by using a ``foreach`` loop, as shown in +the following example: + +.. io-code-block:: + + .. input:: /includes/read/retrieve.php + :start-after: start-cursor + :end-before: end-cursor + :language: php + :dedent: + + .. output:: + + {"_id":{"$oid":"..."},"name":"Mitsubishi Motors","permalink":"mitsubishi-motors", + "crunchbase_url":"http:\/\/www.crunchbase.com\/company\/mitsubishi-motors", + ... } + + {"_id":{"$oid":"..."},"name":"Western Digital","permalink":"western-digital", + "crunchbase_url":"http:\/\/www.crunchbase.com\/company\/western-digital", + ... } + + {"_id":{"$oid":"..."},"name":"Celarayn","permalink":"celarayn","crunchbase_url": + "http:\/\/www.crunchbase.com\/company\/celarayn", + ... } + +.. note:: Find All Documents + + To find all documents in a collection, pass an empty filter + to the ``find()`` method: + + .. code-block:: php + + $cursor = $collection->find([]); + +.. _php-retrieve-modify: + +Modify Find Behavior +~~~~~~~~~~~~~~~~~~~~ + +You can modify the behavior of the ``MongoDB\Collection::find()`` and +``MongoDB\Collection::findOne()`` methods by passing an array that specifies +option values as a parameter. The following table describes some of the options +you can set in the array: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Option + - Description + + * - ``batchSize`` + - | The number of documents to return per batch. The default value is ``101``. + | **Type**: ``integer`` + + * - ``collation`` + - | The collation to use for the operation. The default value is the collation + specified for the collection. + | **Type**: ``array|object`` + + * - ``comment`` + - | The comment to attach to the operation. + | **Type**: any BSON type + + * - ``cursorType`` + - | The type of cursor to use for the operation. The default value is + ``MongoDB\Operation\Find::NON_TAILABLE``. + | **Type**: ``MongoDB\Operation\Find`` + + * - ``limit`` + - | The maximum number of documents the operation can return. + | **Type**: ``integer`` + + * - ``skip`` + - | The number of documents to skip before returning results. + | **Type**: ``integer`` + + * - ``sort`` + - | The order in which the operation returns matching documents. + | **Type**: ``array|object`` + + * - ``typeMap`` + - | The type map to apply to cursors, which determines how BSON documents + are converted to PHP values. The default value is the collection's type map. + | **Type**: ``array`` + +The following example uses the ``find()`` method to find all documents in which +the ``number_of_employees`` field has the value ``1000`` and instructs the +operation to return a maximum of ``5`` results: + +.. literalinclude:: /includes/read/retrieve.php + :language: php + :dedent: + :start-after: start-modify + :end-before: end-modify + +For a full list of options, see the API documentation for the +`findOne() {+api+}/method/MongoDBCollection-findOne/#parameters`__ and +`find() {+api+}/method/MongoDBCollection-find/#parameters`__ parameters. + +.. _php-retrieve-additional-information: + +Additional Information +---------------------- + +.. TODO: + To learn more about query filters, see :ref:`php-specify-query`. + For runnable code examples of retrieving documents with the {+php-library+}, + see :ref:`php-read`. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: + +- `findOne() {+api+}/method/MongoDBCollection-findOne/`__ +- `find() {+api+}/method/MongoDBCollection-find/`__ \ No newline at end of file From eac404d209dfce878544893af785ebfa0b34de64 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 12 Aug 2024 12:23:05 -0400 Subject: [PATCH 02/10] fixes --- source/index.txt | 1 + source/read/retrieve.txt | 11 +++++------ 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/source/index.txt b/source/index.txt index 244f3eb2..26734024 100644 --- a/source/index.txt +++ b/source/index.txt @@ -12,6 +12,7 @@ MongoDB PHP Library Installation Get Started + /read /tutorial /upgrade /reference diff --git a/source/read/retrieve.txt b/source/read/retrieve.txt index f023cef4..238280f6 100644 --- a/source/read/retrieve.txt +++ b/source/read/retrieve.txt @@ -90,8 +90,7 @@ the ``name`` field has the value ``"LinkedIn"``: {"_id":{"$oid":"..."},"name":"LinkedIn","permalink":"linkedin","crunchbase_url": "http:\/\/www.crunchbase.com\/company\/linkedin","homepage_url":"http:\/\/linkedin.com", - ... - } + ... } .. tip:: Sort Order @@ -220,8 +219,8 @@ operation to return a maximum of ``5`` results: :end-before: end-modify For a full list of options, see the API documentation for the -`findOne() {+api+}/method/MongoDBCollection-findOne/#parameters`__ and -`find() {+api+}/method/MongoDBCollection-find/#parameters`__ parameters. +`findOne() <{+api+}/method/MongoDBCollection-findOne/#parameters>`__ and +`find() <{+api+}/method/MongoDBCollection-find/#parameters>`__ parameters. .. _php-retrieve-additional-information: @@ -239,5 +238,5 @@ API Documentation To learn more about any of the methods or types discussed in this guide, see the following API documentation: -- `findOne() {+api+}/method/MongoDBCollection-findOne/`__ -- `find() {+api+}/method/MongoDBCollection-find/`__ \ No newline at end of file +- `findOne() <{+api+}/method/MongoDBCollection-findOne/>`__ +- `find() <{+api+}/method/MongoDBCollection-find/>`__ \ No newline at end of file From 98bdd22ab0b1c432d7395e1100855824d8dc2fc7 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 12 Aug 2024 13:28:57 -0400 Subject: [PATCH 03/10] quotes --- source/read/retrieve.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/read/retrieve.txt b/source/read/retrieve.txt index 238280f6..12ee6bf8 100644 --- a/source/read/retrieve.txt +++ b/source/read/retrieve.txt @@ -76,7 +76,7 @@ If the query filter matches more than one document, the ``findOne()`` method ret matching document from the retrieved results. The following example uses the ``findOne()`` method to find the first document in which -the ``name`` field has the value ``"LinkedIn"``: +the ``name`` field has the value ``'LinkedIn'``: .. io-code-block:: From 0c072217dbd608a754e4e7f2df50dd90a09b6289 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 12 Aug 2024 13:29:31 -0400 Subject: [PATCH 04/10] code fix --- source/includes/read/retrieve.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/includes/read/retrieve.php b/source/includes/read/retrieve.php index b34f7a4e..b01288d4 100644 --- a/source/includes/read/retrieve.php +++ b/source/includes/read/retrieve.php @@ -1,5 +1,5 @@ "; $client = new MongoDB\Client($uri); From 6b68a97570dfb9a941d280b3d67a4b561e5fc565 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 Aug 2024 14:44:57 -0400 Subject: [PATCH 05/10] JS feedback --- source/read/retrieve.txt | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/source/read/retrieve.txt b/source/read/retrieve.txt index 12ee6bf8..3a4bb000 100644 --- a/source/read/retrieve.txt +++ b/source/read/retrieve.txt @@ -49,8 +49,8 @@ Find Documents The {+php-library+} includes two methods for retrieving documents from a collection: ``MongoDB\Collection::findOne()`` and ``MongoDB\Collection::find()``. These methods -take a **query filter** and return one or more matching documents. A query filter is -an object that specifies the documents you want to retrieve in your query. +take a **query filter** and return one or more matching documents. A query filter +specifies the search criteria that the driver uses to retrieve documents in your query. .. TODO: To learn more about query filters, see :ref:`php-specify-query`. @@ -79,6 +79,7 @@ The following example uses the ``findOne()`` method to find the first document i the ``name`` field has the value ``'LinkedIn'``: .. io-code-block:: + :copyable: .. input:: /includes/read/retrieve.php :start-after: start-find-one @@ -126,6 +127,7 @@ You can iterate over the documents in a cursor by using a ``foreach`` loop, as s the following example: .. io-code-block:: + :copyable: .. input:: /includes/read/retrieve.php :start-after: start-cursor @@ -163,7 +165,7 @@ Modify Find Behavior You can modify the behavior of the ``MongoDB\Collection::find()`` and ``MongoDB\Collection::findOne()`` methods by passing an array that specifies -option values as a parameter. The following table describes some of the options +option values as a parameter. The following table describes some options you can set in the array: .. list-table:: @@ -209,8 +211,8 @@ you can set in the array: | **Type**: ``array`` The following example uses the ``find()`` method to find all documents in which -the ``number_of_employees`` field has the value ``1000`` and instructs the -operation to return a maximum of ``5`` results: +the ``number_of_employees`` field has the value ``1000``. The example uses the +``limit`` option to return a maximum of ``5`` results: .. literalinclude:: /includes/read/retrieve.php :language: php From b950042913be99254d33f7aa62b9107e86e1d3af Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 16 Aug 2024 11:32:46 -0400 Subject: [PATCH 06/10] JT feedback --- source/includes/read/retrieve.php | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/source/includes/read/retrieve.php b/source/includes/read/retrieve.php index b01288d4..84b60221 100644 --- a/source/includes/read/retrieve.php +++ b/source/includes/read/retrieve.php @@ -1,7 +1,7 @@ "; +$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); // start-db-coll @@ -29,14 +29,12 @@ // Finds and prints up to 5 documents with a "number_of_employees" value of 1000 // start-modify -$options = [ - 'limit' => 5, -]; - -$results = $collection->find(['number_of_employees' => 1000], $options); +$results = $collection->find( + ['number_of_employees' => 1000], + ['limit' => 5] +); foreach ($results as $doc) { echo json_encode($doc) . "\n"; } -// end-modify -?> \ No newline at end of file +// end-modify \ No newline at end of file From 42a4f150392236f0114151725cbb03e645c5853e Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 16 Aug 2024 11:34:22 -0400 Subject: [PATCH 07/10] code format --- source/read/retrieve.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/source/read/retrieve.txt b/source/read/retrieve.txt index 3a4bb000..d4f7566c 100644 --- a/source/read/retrieve.txt +++ b/source/read/retrieve.txt @@ -217,6 +217,7 @@ the ``number_of_employees`` field has the value ``1000``. The example uses the .. literalinclude:: /includes/read/retrieve.php :language: php :dedent: + :emphasize-lines: 3 :start-after: start-modify :end-before: end-modify From da6c7e41a44347f78ea1345b32493b8cae2f85ec Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 16 Aug 2024 11:41:27 -0400 Subject: [PATCH 08/10] fix --- source/read/retrieve.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/source/read/retrieve.txt b/source/read/retrieve.txt index d4f7566c..2820e32c 100644 --- a/source/read/retrieve.txt +++ b/source/read/retrieve.txt @@ -216,7 +216,6 @@ the ``number_of_employees`` field has the value ``1000``. The example uses the .. literalinclude:: /includes/read/retrieve.php :language: php - :dedent: :emphasize-lines: 3 :start-after: start-modify :end-before: end-modify From dcb449c63eba4aacc45716669d303af72d35f418 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 16 Aug 2024 14:13:10 -0400 Subject: [PATCH 09/10] JT feedback 2 --- source/includes/read/retrieve.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/includes/read/retrieve.php b/source/includes/read/retrieve.php index 84b60221..a6ee53b5 100644 --- a/source/includes/read/retrieve.php +++ b/source/includes/read/retrieve.php @@ -37,4 +37,4 @@ foreach ($results as $doc) { echo json_encode($doc) . "\n"; } -// end-modify \ No newline at end of file +// end-modify From 2a51311100bbb3eaeaeba38a5a1a0931c8ab4578 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 19 Aug 2024 10:20:21 -0400 Subject: [PATCH 10/10] edit --- snooty.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/snooty.toml b/snooty.toml index afabcaf9..507f09d6 100644 --- a/snooty.toml +++ b/snooty.toml @@ -24,4 +24,4 @@ php-library = "MongoDB PHP Library" [constants] php-library = "MongoDB PHP Library" -api = "https://www.mongodb.com/docs/php-library/current/reference" \ No newline at end of file +api = "https://www.mongodb.com/docs/php-library/current/reference"