mongodb · norareidy · Apr 4, 2024 · Mar 12, 2024 · Mar 13, 2024 · Mar 13, 2024
@@ -0,0 +1,115 @@
+.. _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 call the ``first()`` method to return
-Pass a query filter to the ``where()`` method and call the ``first()`` method to return
+Pass a query filter to the ``where()`` method and then call the ``first()`` method to return
-Pass a query filter to the ``where()`` method and call the ``first()`` method to return
+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 specified by the
+``orderBy()`` method.
-:term:`natural order` in the database or according to the sort order specified by the
-``orderBy()`` method.
+:term:`natural order` in the database or according to the sort order that you can specify by using the
+``orderBy()`` method.
-:term:`natural order` in the database or according to the sort order specified by the
-``orderBy()`` method.
+: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 retrieving documents, see the :ref:`laravel-fundamentals-retrieve` guide.
+
+Example
+-------
+
+This usage example retrieves a document that matches a query filter from the ``movies``
+collection in the ``sample_mflix`` database. The example uses the ``Movie`` Eloquent model
+to represent the ``movies`` collection.
+
+This example performs the following actions:
+
+- Defines a query filter that matches documents in which the value of the ``directors`` field
+  is ``"Rob Reiner"``
- Defines a query filter that matches documents in which the value of the ``directors`` field
-  is ``"Rob Reiner"``
+- Defines a query filter that matches documents in which the value of the ``directors`` field
+  includes ``"Rob Reiner"``
- Defines a query filter that matches documents in which the value of the ``directors`` field
-  is ``"Rob Reiner"``
+- Defines a query filter that matches documents in which the value of the ``directors`` field
+  includes ``"Rob Reiner"``
+- Retrieves the first document that matches the query filter, according to the sort order
+  specified by the ``orderBy()`` method
+
+To see the find operation code, select the :guilabel:`Controller File Code` tab. To see
+the HTML code that specifies a view, select the :guilabel:`View File Code` tab.
+
+.. tabs::
+
+   .. tab:: Controller File Code
+      :tabid: find-one-controller
+
+      .. io-code-block::
+         :copyable: true
+
+         .. input::
+            :language: php
+
+            class MovieController
+            {
+                 public function show()
+                 {
+                      $movie = Movie::where('directors', 'Rob Reiner')
+                          ->orderBy('_id')
+                          ->first();
+
+                      return view('browse_movies', [
+                          'movie' => $movie
+                      ]);
+                  }
+            }
+
+         .. output::
+            :language: console
+            :visible: false
+
+            Title: This Is Spinal Tap
+            Year: 1984
+            Runtime: 82
+            Director: Rob Reiner
+            Plot: Spinal Tap, one of England's loudest bands, is chronicled by film director
+            Marty DeBergi on what proves to be a fateful tour.
+
+   .. tab:: View File Code
+      :tabid: find-one-view
+
+      .. io-code-block::
+         :copyable: true
+
+         .. input::
+            :language: php
+
+            <!DOCTYPE html>
+            <html>
+            <head>
+            <title>Browse Movies</title>
+            </head>
+            <body>
+            <h2>Movies</h2>
+            <p>
+                Title: {{ $movie->title }}<br>
+                Year: {{ $movie->year }}<br>
+                Runtime: {{ $movie->runtime }}<br>
+                Director: {{ $movie->directors[0] }}<br>
+                Plot: {{ $movie->plot }}<br>
+            </p>
+            </body>
+            </html>
+
+         .. output::
+            :language: console
+            :visible: false
+
+            Title: This Is Spinal Tap
+            Year: 1984
+            Runtime: 82
+            Director: Rob Reiner
+            Plot: Spinal Tap, one of England's loudest bands, is chronicled by film director
+            Marty DeBergi on what proves to be a fateful tour.
+
+To perform the find operation, start your Laravel application by running the following command:
+
+.. code-block:: bash
+
+   php artisan serve
+
+Then, open the URL http://127.0.0.1:8000/browse_movies in your web browser to view the expected
+output.