diff --git a/docs/includes/usage-examples/FindManyTest.php b/docs/includes/usage-examples/FindManyTest.php new file mode 100644 index 000000000..18324c62d --- /dev/null +++ b/docs/includes/usage-examples/FindManyTest.php @@ -0,0 +1,44 @@ + 'Centennial', + 'runtime' => 1256, + ], + [ + 'title' => 'Baseball', + 'runtime' => 1140, + ], + [ + 'title' => 'Basketball', + 'runtime' => 600, + ], + ]); + + // begin-find + $movies = Movie::where('runtime', '>', 900) + ->orderBy('_id') + ->get(); + // end-find + + $this->assertEquals(2, $movies->count()); + } +} diff --git a/docs/usage-examples.txt b/docs/usage-examples.txt index be29ee9ac..629ba5eca 100644 --- a/docs/usage-examples.txt +++ b/docs/usage-examples.txt @@ -72,6 +72,7 @@ calls the controller function and returns the result to a web interface. :maxdepth: 1 /usage-examples/findOne + /usage-examples/find /usage-examples/insertOne /usage-examples/insertMany /usage-examples/updateOne diff --git a/docs/usage-examples/find.txt b/docs/usage-examples/find.txt new file mode 100644 index 000000000..3e9115661 --- /dev/null +++ b/docs/usage-examples/find.txt @@ -0,0 +1,85 @@ +.. _laravel-find-usage: + +======================= +Find Multiple Documents +======================= + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: find many, retrieve, code example + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +You can retrieve multiple documents from a collection by creating a query +builder using a method such as ``Model::where()`` or by using the ``DB`` +facade, and then chaining the ``get()`` method to retrieve the result. + +Pass a query filter to the ``where()`` method to retrieve documents that meet a +set of criteria. When you call the ``get()`` method, MongoDB returns the +matching documents according to their :term:`natural order` in the database or +according to the sort order that you can specify by using the ``orderBy()`` +method. + +To learn more about query builder methods, see the :ref:`laravel-query-builder` +guide. + +Example +------- + +This usage example performs the following actions: + +- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the + ``sample_mflix`` database +- Retrieves and prints documents from the ``movies`` collection that match a query filter + +The example calls the following methods on the ``Movie`` model: + +- ``where()``: matches documents in which the value of the ``runtime`` field is greater than ``900`` +- ``orderBy()``: sorts matched documents by their ascending ``_id`` values +- ``get()``: retrieves the query results as a Laravel collection object + +.. io-code-block:: + :copyable: true + + .. input:: ../includes/usage-examples/FindManyTest.php + :start-after: begin-find + :end-before: end-find + :language: php + :dedent: + + .. output:: + :language: json + :visible: false + + // Results are truncated + + [ + { + "_id": ..., + "runtime": 1256, + "title": "Centennial", + ..., + }, + { + "_id": ..., + "runtime": 1140, + "title": "Baseball", + ..., + }, + ... + ] + +For instructions on editing your Laravel application to run the usage example, see the +:ref:`Usage Examples landing page `. + +.. tip:: + + To learn about other ways to retrieve documents with {+odm-short+}, see the + :ref:`laravel-fundamentals-retrieve` guide.