DOCSP-35962: sorts

docs/fundamentals/read-operations.txt

@@ -188,6 +188,8 @@ method:
 
 - :ref:`laravel-skip-limit` uses the ``skip()`` method to set the number of documents
   to skip and the ``take()`` method to set the total number of documents to return
+- :ref:`laravel-sort` uses the ``orderBy()`` method to return query
+  results in a specified order based on field values
 - :ref:`laravel-retrieve-one` uses the ``first()`` method to return the first document
   that matches the query filter
 
@@ -269,6 +271,106 @@ documents.
             Plot: A sci-fi update of the famous 6th Century poem. In a beseiged land, Beowulf must
             battle against the hideous creature Grendel and his vengeance seeking mother.
 
+.. _laravel-sort:
+
+Sort Query Results
+~~~~~~~~~~~~~~~~~~
+
+To order query results based on the values of specified fields, use the ``where()`` method
+followed by the ``orderBy()`` method.
+
+You can set an **ascending** or **descending** sort direction on
+results. By default, the ``orderBy()`` method sets an ascending sort on
+the supplied field name, but you can explicitly specify an ascending
+sort by passing ``'asc'`` as the second parameter. To
+specify a descending sort, pass ``'desc'`` as the second parameter.
+
+If your documents contain duplicate values in a specific field, you can
+handle the tie by specifying additional fields to sort on. This ensures consistent
+results if the additional fields contain unique values.
+
+This example queries for documents in which the value of the ``countries`` field contains
+``'Indonesia'`` and orders results first by an ascending sort on the
+``year`` field, then a descending sort on the ``title`` field.
+
+.. tabs::
+
+   .. tab:: Query Syntax
+      :tabid: query-syntax
+
+      Use the following syntax to specify the query:
+
+      .. code-block:: php
+
+         $movies = Movie::where('countries', 'Indonesia')
+             ->orderBy('year')
+             ->orderBy('title', 'desc')
+             ->get();
+
+   .. tab:: Controller Method
+      :tabid: controller
+
+      To see the query results in the ``browse_movies`` view, edit the ``show()`` function
+      in the ``MovieController.php`` file to resemble the following code:
+
+      .. io-code-block::
+         :copyable: true
+
+         .. input::
+            :language: php
+
+            class MovieController
+            {
+                public function show()
+                {
+                    $movies = Movie::where('countries', 'Indonesia')
+                        ->orderBy('year')
+                        ->orderBy('title', 'desc')
+                        ->get();
+
+                    return view('browse_movies', [
+                        'movies' => $movies
+                    ]);
+                }
+            }
+
+         .. output::
+            :language: none
+            :visible: false
+
+            Title: Joni's Promise
+            Year: 2005
+            Runtime: 83
+            IMDB Rating: 7.6
+            IMDB Votes: 702
+            Plot: A film delivery man promises ...
+
+            Title: Gie
+            Year: 2005
+            Runtime: 147
+            IMDB Rating: 7.5
+            IMDB Votes: 470
+            Plot: Soe Hok Gie is an activist who lived in the sixties ...
+
+            Title: Requiem from Java
+            Year: 2006
+            Runtime: 120
+            IMDB Rating: 6.6
+            IMDB Votes: 316
+            Plot: Setyo (Martinus Miroto) and Siti (Artika Sari Dewi)
+            are young married couple ...
+
+            ...
+
+.. tip::
+
+   To learn more about sorting, see the following resources:
+
+   - :manual:`Natural order </reference/glossary/#std-term-natural-order>`
+     in the Server manual glossary
+   - `Ordering, Grouping, Limit and Offset <https://laravel.com/docs/10.x/queries#ordering-grouping-limit-and-offset>`__
+     in the Laravel documentation
+
 .. _laravel-retrieve-one:
 
 Return the First Result
@@ -337,10 +439,5 @@ field.
 
 .. tip::
 
-   To learn more about sorting, see the following resources:
-
-   - :manual:`Natural order </reference/glossary/#std-term-natural-order>`
-     in the Server manual glossary
-   - `Ordering, Grouping, Limit and Offset <https://laravel.com/docs/10.x/queries#ordering-grouping-limit-and-offset>`__
-     in the Laravel documentation
-
+   To learn more about the ``orderBy()`` method, see the
+   :ref:`laravel-sort` section of this guide.