Merge 4.1 into 4.2

docs/includes/usage-examples/FindOneTest.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers;
+
+use App\Models\Movie;
+use MongoDB\Laravel\Tests\TestCase;
+
+class FindOneTest extends TestCase
+{
+    /**
+     * @runInSeparateProcess
+     * @preserveGlobalState disabled
+     */
+    public function testFindOne(): void
+    {
+        require_once __DIR__ . '/Movie.php';
+
+        Movie::truncate();
+        Movie::insert([
+            ['title' => 'The Shawshank Redemption', 'directors' => ['Frank Darabont', 'Rob Reiner']],
+        ]);
+
+        // begin-find-one
+        $movie = Movie::where('directors', 'Rob Reiner')
+          ->orderBy('_id')
+          ->first();
+
+        echo $movie->toJson();
+        // end-find-one
+
+        $this->assertInstanceOf(Movie::class, $movie);
+        $this->expectOutputRegex('/^{"_id":"[a-z0-9]{24}","title":"The Shawshank Redemption","directors":\["Frank Darabont","Rob Reiner"\]}$/');
+    }
+}

docs/usage-examples.txt

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

docs/usage-examples/findOne.txt

@@ -0,0 +1,74 @@
+.. _laravel-find-one-usage:
+
+===============
+Find a Document
+===============
+
+You can retrieve a single document from a collection by calling the ``where()`` and
+``first()`` methods on an Eloquent model or a query builder.
+
+Pass a query filter to the ``where()`` method and then call the ``first()`` method to
+return one document in the collection that matches the filter. If multiple documents match
+the query filter, ``first()`` returns the first matching document according to the documents'
+: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 a document from the ``movies`` collection that matches a query filter.
+
+The example calls the following methods on the ``Movie`` model:
+
+- ``where()``: matches documents in which the value of the ``directors`` field includes ``'Rob Reiner'``.
+- ``orderBy()``: sorts matched documents by their ascending ``_id`` values.
+- ``first()``: retrieves only the first matching document.
+
+.. io-code-block::
+
+   .. input:: ../includes/usage-examples/FindOneTest.php
+      :start-after: begin-find-one
+      :end-before: end-find-one
+      :language: php
+      :dedent:
+
+   .. output::
+      :language: console
+      :visible: false
+
+      // Result is truncated
+
+      {
+         "_id": "573a1398f29313caabce94a3",
+         "plot": "Spinal Tap, one of England's loudest bands, is chronicled by film director
+         Marty DeBergi on what proves to be a fateful tour.",
+         "genres": [
+            "Comedy",
+            "Music"
+         ],
+         "runtime": 82,
+         "metacritic": 85,
+         "rated": "R",
+         "cast": [
+            "Rob Reiner",
+            "Kimberly Stringer",
+            "Chazz Dominguez",
+            "Shari Hall"
+         ],
+         "poster": "https://m.media-amazon.com/images/M/MV5BMTQ2MTIzMzg5Nl5BMl5BanBnXkFtZTgwOTc5NDI1MDE@._V1_SY1000_SX677_AL_.jpg",
+         "title": "This Is Spinal Tap",
+         ...
+      }
+
+
+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