diff --git a/snooty.toml b/snooty.toml index a08a8d41..507f09d6 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" diff --git a/source/includes/read/retrieve.php b/source/includes/read/retrieve.php new file mode 100644 index 00000000..a6ee53b5 --- /dev/null +++ b/source/includes/read/retrieve.php @@ -0,0 +1,40 @@ +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 +$results = $collection->find( + ['number_of_employees' => 1000], + ['limit' => 5] +); + +foreach ($results as $doc) { + echo json_encode($doc) . "\n"; +} +// end-modify 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.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..2820e32c --- /dev/null +++ b/source/read/retrieve.txt @@ -0,0 +1,244 @@ +.. _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 +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`. + +.. _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:: + :copyable: + + .. 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:: + :copyable: + + .. 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 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``. The example uses the +``limit`` option to return a maximum of ``5`` results: + +.. literalinclude:: /includes/read/retrieve.php + :language: php + :emphasize-lines: 3 + :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