diff --git a/docs/includes/usage-examples/FindOneTest.php b/docs/includes/usage-examples/FindOneTest.php new file mode 100644 index 000000000..98452a6a6 --- /dev/null +++ b/docs/includes/usage-examples/FindOneTest.php @@ -0,0 +1,36 @@ + '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"\]}$/'); + } +} diff --git a/docs/usage-examples.txt b/docs/usage-examples.txt index 08dda77ea..2bcd9ac58 100644 --- a/docs/usage-examples.txt +++ b/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 \ No newline at end of file + /usage-examples/findOne + /usage-examples/updateOne diff --git a/docs/usage-examples/findOne.txt b/docs/usage-examples/findOne.txt new file mode 100644 index 000000000..39fde3d56 --- /dev/null +++ b/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 `. + +.. tip:: + + To learn more about retrieving documents with {+odm-short+}, see the + :ref:`laravel-fundamentals-retrieve` guide \ No newline at end of file