DOCSP-41973 Read Landing Page

snooty.toml

@@ -23,6 +23,7 @@ toc_landing_pages = [
     "/reference/class/MongoDBModelIndexInfo",
     "/get-started",
     "/connect",
+    "/read",
     "/databases-collections",
     "/write",
     "/indexes",

source/includes/usage-examples/read-code-examples.php

@@ -0,0 +1,67 @@
+<?php
+
+require_once __DIR__ . '/vendor/autoload.php';
+
+use MongoDB\Client;
+
+$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);
+
+$collection = $client->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

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 <php-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.

source/read.txt

@@ -4,6 +4,20 @@
 Read Data from MongoDB
 ======================
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :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
@@ -16,3 +30,136 @@
    /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 <php-index-sample>` or your own application.
+Make sure to set the ``MONGODB_URI`` environment variable to the
+connection string for your MongoDB deployment, and replace the
+``<database>`` and ``<collection>`` placeholders with values for your
+target namespace.
+
+.. _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-count-all` 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-count-specific` 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.   

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
 ~~~~~~~~~~~~~~~~~~~~~~~~
 

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: