diff --git a/snooty.toml b/snooty.toml index d2d18efa..dcccdff7 100644 --- a/snooty.toml +++ b/snooty.toml @@ -23,6 +23,7 @@ toc_landing_pages = [ "/reference/class/MongoDBModelIndexInfo", "/get-started", "/connect", + "/read", "/databases-collections", "/write", "/indexes", 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..e6203cdf --- /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 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. diff --git a/source/read.txt b/source/read.txt index 0b6f6c78..edc62a13 100644 --- a/source/read.txt +++ b/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 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. +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: + +.. 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. diff --git a/source/read/count.txt b/source/read/count.txt index 20d7dd71..9036e8c5 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 ~~~~~~~~~~~~~~~~~~~~~~~~ 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: