DOCSP-35977: Find multiple usage example

docs/includes/usage-examples/FindManyTest.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers;
+
+use App\Models\Movie;
+use MongoDB\Laravel\Tests\TestCase;
+
+class FindManyTest extends TestCase
+{
+    /**
+     * @runInSeparateProcess
+     * @preserveGlobalState disabled
+     */
+    public function testFindMany(): void
+    {
+        require_once __DIR__ . '/Movie.php';
+
+        Movie::truncate();
+
+        // begin-find
+        $movies = Movie::where('runtime', '>', 800)
+            ->orderBy('_id')
+            ->get();
+
+        foreach ($movies as $m) {
+            echo $m->toJson() . '<br>';
+        }
+
+        // end-find
+
+        $this->assertInstanceOf(Movie::class, $movie);
+    }
+}

docs/usage-examples.txt

@@ -72,4 +72,5 @@ calls the controller function and returns the result to a web interface.
    :maxdepth: 1
 
    /usage-examples/findOne
+   /usage-examples/find
    /usage-examples/updateOne

docs/usage-examples/find.txt

@@ -0,0 +1,107 @@
+.. _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 calling the ``where()`` method
+on an Eloquent model or a query builder.
+
+Pass a query filter to the ``where()`` method to retrieve documents that meet a
+set of criteria. 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.
+
+Example
+-------
+
+This usage example performs the following actions:
+
+- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the
+  ``sample_mflix`` database
+- Retrieves 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 ``800``
+- ``orderBy()``: sorts matched documents by their ascending ``_id`` values
+- ``get()``: retrieves the query results
+
+.. io-code-block::
+   :copyable: true
+
+   .. input:: ../includes/usage-examples/FindManyTest.php
+      :start-after: begin-find
+      :end-before: end-find
+      :language: php
+      :dedent:
+
+   .. output::
+      :language: console
+      :visible: false
+
+      // Results are truncated
+
+      {
+      "_id": "...",
+      "plot": "The economic and cultural growth of Colorado spanning two centuries from the mid-1700s to the late-1970s.",
+      "genres": [
+          "Action",
+          "Adventure",
+          "Drama"
+      ],
+      "runtime": 1256,
+      ...
+      "title": "Centennial",
+      ...
+      }
+
+      {
+      "_id": "...",
+      "plot": "A documentary on the history of the sport with major topics including Afro-American players, player/team
+      owner relations and the resilience of the game.",
+      "genres": [
+          "Documentary",
+          "History",
+          "Sport"
+      ],
+      "runtime": 1140,
+      ...
+      "title": "Baseball",
+      ...
+      }
+
+      {
+      "_id": "...",
+      "plot": "Taken spans five decades and four generations, centering on three families: the Keys, Crawfords, and Clarkes.
+      World War II veteran Russell Keys is plagued by nightmares of his abduction by ...",
+      "genres": [
+          "Drama",
+          "Sci-Fi"
+      ],
+      "runtime": 877,
+      ...
+      "title": "Taken",
+      ...
+      }
+
+For instructions on editing your Laravel application to run the usage example, see the
+:ref:`Usage Example landing page <laravel-usage-examples>`.
+
+.. tip::
+
+   To learn more about retrieving documents with {+odm-short+}, see the
+   :ref:`laravel-fundamentals-retrieve` guide