From a5f2990d863a997a1c5179b979b32d94043c0938 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Mon, 23 Sep 2024 18:57:22 -0400 Subject: [PATCH 1/8] DOCSP-41973 Read Landing Page --- source/read.txt | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/source/read.txt b/source/read.txt index 0b6f6c78..bfcbb1a0 100644 --- a/source/read.txt +++ b/source/read.txt @@ -16,3 +16,25 @@ Read Data from MongoDB /read/specify-a-query /read/distinct /read/change-streams + +Overview +-------- + +On this page, you can see copyable code examples that show common +{+driver-short+} methods for retrieving documents. + +.. tip:: + + To learn more about any of the methods shown on this page, see the link + provided in each section. + +To use an example from this page, copy the code example into the +:ref:`sample application ` or your own application. +Be sure to replace all placeholders, such as ````, with +the relevant values for your MongoDB deployment. + +.. _php-read-sample: + + + + From f11a3024d648ccf4a222b066e2bfc6e22cd933aa Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 24 Sep 2024 18:38:55 -0400 Subject: [PATCH 2/8] full page with ex --- .../usage-examples/read-code-examples.php | 67 ++++++++++ source/read.txt | 115 ++++++++++++++++++ source/read/retrieve.txt | 2 +- 3 files changed, 183 insertions(+), 1 deletion(-) create mode 100644 source/includes/usage-examples/read-code-examples.php diff --git a/source/includes/usage-examples/read-code-examples.php b/source/includes/usage-examples/read-code-examples.php new file mode 100644 index 00000000..8b73bc15 --- /dev/null +++ b/source/includes/usage-examples/read-code-examples.php @@ -0,0 +1,67 @@ +sample_mflix->movies; + +// Find One +// start-find-one +$document = $collection->findOne(['year' => 1994]); +echo json_encode($document) , "\n"; +// end-find-one + +// Find Multiple +// start-find-multiple +$resultsMultiple = $collection->find(['year' => 1970]); +foreach ($resultsMultiple as $doc) { + echo json_encode($doc) , "\n"; +} +// end-find-multiple + +// Count Document +// start-count +$result = $collection->countDocuments([]); +echo "Number of documents: " . $result; +// end-count + +// Count Specific Documents +// start-count-specific +$result = $collection->countDocuments(['year' => 2010]); +echo "Number of companies founded in 2010: " . $result; +// end-count-specific + +// Estimated Count +// start-count-estimate +$result = $collection->estimatedDocumentCount(); +echo "Estimated number of documents: " . $result; +// end-count-estimate + +// Distinct Values +// start-distinct +$results = $collection->distinct('year', []); +foreach ($results as $value) { + echo json_encode($value) . PHP_EOL; +} +// end-distinct + +// Data Changes +// start-change-stream +$changeStream = $collection->watch(); + +for ($changeStream->rewind(); true; $changeStream->next()) { + if ( ! $changeStream->valid()) { + continue; + } + $event = $changeStream->current(); + echo toJSON($event) . PHP_EOL; + + if ($event['operationType'] === 'invalidate') { + break; + } +} +// end-change-stream \ No newline at end of file diff --git a/source/read.txt b/source/read.txt index bfcbb1a0..c380d508 100644 --- a/source/read.txt +++ b/source/read.txt @@ -4,6 +4,12 @@ Read Data from MongoDB ====================== +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + .. toctree:: :titlesonly: :maxdepth: 1 @@ -35,6 +41,115 @@ the relevant values for your MongoDB deployment. .. _php-read-sample: +.. include:: /includes/usage-examples/sample-app-intro.rst + +.. literalinclude:: /includes/usage-examples/sample-app.php + :language: php + :dedent: + :linenos: + :emphasize-lines: 10-12 + +Find One +-------- + +The following code shows how to retrieve a single document from a collection +that matches the specified criteria: + +.. literalinclude:: /includes/usage-examples/read-code-examples.php + :start-after: start-find-one + :end-before: end-find-one + :language: php + :dedent: + +To learn more about the ``findOne()`` method, see the :ref:`php-retrieve-find-one` +section in the Retrieve Data guide. + +Find Multiple +------------- + +The following code shows how to retrieve all documents from a collection +that match the specified criteria: + +.. literalinclude:: /includes/usage-examples/read-code-examples.php + :start-after: start-find-multiple + :end-before: end-find-multiple + :language: php + :dedent: + +To learn more about the ``find()`` method, see the :ref:`php-retrieve-find-multiple` +section in the Retrieve Data guide. + +Count Documents in a Collection +------------------------------- + +The following code shows how to count the number of documents in +a collection: + +.. literalinclude:: /includes/usage-examples/read-code-examples.php + :start-after: start-count + :end-before: end-count + :language: php + :dedent: + +To learn more about the ``countDocuments()`` method, see the +:ref:`php-accurate-count` section in the Count Documents guide. + +Count Documents Returned from a Query +------------------------------------- + +The following code shows how to count documents in a collection +that match the specified criteria: + +.. literalinclude:: /includes/usage-examples/read-code-examples.php + :start-after: start-count-specific + :end-before: end-count-specific + :language: php + :dedent: + +To learn more about the ``countDocuments()`` method, see the +:ref:`php-accurate-count` section in the Count Documents guide. + +Estimated Document Count +------------------------ + +The following code shows how to retrieve an estimated count of the +number of documents in a collection: + +.. literalinclude:: /includes/usage-examples/read-code-examples.php + :start-after: start-count-estimate + :end-before: end-count-estimate + :language: php + :dedent: + +To learn more about the ``estimatedDocumentCount()`` method, see the +:ref:`php-estimated-count` section in the Count Documents guide. + +Retrieve Distinct Values +------------------------ + +The following code shows how to retrieve the unique values of a field +for documents that match the specified criteria: + +.. literalinclude:: /includes/usage-examples/read-code-examples.php + :start-after: start-distinct + :end-before: end-distinct + :language: php + :dedent: + +To learn more about the ``distinct()`` method, see the +:ref:`php-distinct` guide. + +Monitor Data Changes +-------------------- +The following code shows how to monitor and print changes to a +collection: +.. literalinclude:: /includes/usage-examples/read-code-examples.php + :start-after: start-change-stream + :end-before: end-change-stream + :language: php + :dedent: +To learn more about the ``watch()`` method, see the +:ref:`php-change-streams` guide. diff --git a/source/read/retrieve.txt b/source/read/retrieve.txt index cd1507db..283c29aa 100644 --- a/source/read/retrieve.txt +++ b/source/read/retrieve.txt @@ -52,7 +52,7 @@ The {+php-library+} includes two methods for retrieving documents from a collect 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`. +To learn more about query filters, see :ref:`php-specify-query`. .. _php-retrieve-find-one: From fc6dfda1655b4c74862595fb76d3667270541fc6 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 24 Sep 2024 18:44:26 -0400 Subject: [PATCH 3/8] add page --- snooty.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/snooty.toml b/snooty.toml index 938cdc0d..248b1c64 100644 --- a/snooty.toml +++ b/snooty.toml @@ -22,6 +22,7 @@ toc_landing_pages = [ "/reference/class/MongoDBModelDatabaseInfo", "/reference/class/MongoDBModelIndexInfo", "/get-started", + "/read", "/write", "/indexes" ] From 1680c76d32ba48f57424e55e0c5a4c405a365aaa Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 24 Sep 2024 18:49:23 -0400 Subject: [PATCH 4/8] meta --- source/read.txt | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/source/read.txt b/source/read.txt index c380d508..2af56092 100644 --- a/source/read.txt +++ b/source/read.txt @@ -10,6 +10,14 @@ Read Data from MongoDB :depth: 2 :class: singlecol +.. facet:: + :name: genre + :values: reference + +.. meta:: + :description: Learn how to use the PHP Library to read data to MongoDB. + :keywords: usage examples, save, crud, read, code example + .. toctree:: :titlesonly: :maxdepth: 1 From e236d7ab24e5fc124b1b81c97674ef72e8c8de1b Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 25 Sep 2024 13:09:24 -0400 Subject: [PATCH 5/8] edit sample app intro --- source/includes/usage-examples/sample-app-intro.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/includes/usage-examples/sample-app-intro.rst b/source/includes/usage-examples/sample-app-intro.rst index cee5f2d7..a17549fe 100644 --- a/source/includes/usage-examples/sample-app-intro.rst +++ b/source/includes/usage-examples/sample-app-intro.rst @@ -4,7 +4,9 @@ Sample Application You can use the following sample application to test the code examples on this page. To use the sample application, perform the following steps: -1. Ensure you have the {+php-library+} installed in your project. +1. Ensure you have the {+php-library+} installed in your project. To learn more + about installing the {+php-library+}, see the + :ref:`Download and Install ` guide. #. Copy the following code and paste it into a new ``.php`` file. #. Copy a code example from this page and paste it on the specified lines in the file. From ac0e57d1470a122190db0f1dc77e78673bc1fe52 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 25 Sep 2024 13:18:27 -0400 Subject: [PATCH 6/8] change links in count sections --- source/read.txt | 4 ++-- source/read/count.txt | 4 ++++ 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/source/read.txt b/source/read.txt index 2af56092..69728dd9 100644 --- a/source/read.txt +++ b/source/read.txt @@ -100,7 +100,7 @@ a collection: :dedent: To learn more about the ``countDocuments()`` method, see the -:ref:`php-accurate-count` section in the Count Documents guide. +:ref:`php-count-all` section in the Count Documents guide. Count Documents Returned from a Query ------------------------------------- @@ -115,7 +115,7 @@ that match the specified criteria: :dedent: To learn more about the ``countDocuments()`` method, see the -:ref:`php-accurate-count` section in the Count Documents guide. +:ref:`php-count-specific` section in the Count Documents guide. Estimated Document Count ------------------------ diff --git a/source/read/count.txt b/source/read/count.txt index 5b825a78..d4516602 100644 --- a/source/read/count.txt +++ b/source/read/count.txt @@ -58,6 +58,8 @@ pass a query filter to the ``countDocuments()`` method. To learn more about specifying a query, see the :ref:`php-specify-query` guide. +.. _php-count-all: + Count All Documents ~~~~~~~~~~~~~~~~~~~ @@ -78,6 +80,8 @@ the ``countDocuments()`` method, as shown in the following example: Number of documents: 9500 +.. _php-count-specific: + Count Specific Documents ~~~~~~~~~~~~~~~~~~~~~~~~ From 23738fde94b2abe39e96b4fc60fa07aafc4186e5 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 25 Sep 2024 14:09:34 -0400 Subject: [PATCH 7/8] update sample app intro --- source/read.txt | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/source/read.txt b/source/read.txt index 69728dd9..edc62a13 100644 --- a/source/read.txt +++ b/source/read.txt @@ -43,9 +43,11 @@ On this page, you can see copyable code examples that show common provided in each section. To use an example from this page, copy the code example into the -:ref:`sample application ` or your own application. -Be sure to replace all placeholders, such as ````, with -the relevant values for your MongoDB deployment. +:ref:`sample application ` or your own application. +Make sure to set the ``MONGODB_URI`` environment variable to the +connection string for your MongoDB deployment, and replace the +```` and ```` placeholders with values for your +target namespace. .. _php-read-sample: From 36b360c208b0df8139eb2b85ca9c203cb17a0cc9 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 26 Sep 2024 16:06:45 -0400 Subject: [PATCH 8/8] tech review --- source/includes/usage-examples/read-code-examples.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/includes/usage-examples/read-code-examples.php b/source/includes/usage-examples/read-code-examples.php index 8b73bc15..e6203cdf 100644 --- a/source/includes/usage-examples/read-code-examples.php +++ b/source/includes/usage-examples/read-code-examples.php @@ -43,7 +43,7 @@ // Distinct Values // start-distinct -$results = $collection->distinct('year', []); +$results = $collection->distinct('year'); foreach ($results as $value) { echo json_encode($value) . PHP_EOL; } @@ -64,4 +64,4 @@ break; } } -// end-change-stream \ No newline at end of file +// end-change-stream