DOCSP-38327: add qb examples to usage exs

rustagir · rustagir · commit 87ffd838911b · 2025-01-30T09:29:00.000-05:00
diff --git a/docs/includes/usage-examples/CountTest.php b/docs/includes/usage-examples/CountTest.php
@@ -29,12 +29,20 @@ public function testCount(): void
             ],
         ]);
 
-        // begin-count
+        // begin-eloquent-count
         $count = Movie::where('genres', 'Biography')
             ->count();
 
         echo 'Number of documents: ' . $count;
-        // end-count
+        // end-eloquent-count
+
+        // begin-qb-count
+        $count = DB::table('movies')
+            ->where('genres', 'Biography')
+            ->count();
+
+        echo 'Number of documents: ' . $count;
+        // end-qb-count
 
         $this->assertEquals(2, $count);
         $this->expectOutputString('Number of documents: 2');
diff --git a/docs/includes/usage-examples/DeleteManyTest.php b/docs/includes/usage-examples/DeleteManyTest.php
@@ -29,12 +29,20 @@ public function testDeleteMany(): void
             ],
         ]);
 
-        // begin-delete-many
+        // begin-eloquent-delete-many
         $deleted = Movie::where('year', '<=', 1910)
             ->delete();
 
         echo 'Deleted documents: ' . $deleted;
-        // end-delete-many
+        // end-eloquent-delete-many
+
+        // begin-qb-delete-many
+        $deleted = DB::table('movies')
+            ->where('year', '<=', 1910)
+            ->delete();
+
+        echo 'Deleted documents: ' . $deleted;
+        // end-qb-delete-many
 
         $this->assertEquals(2, $deleted);
         $this->expectOutputString('Deleted documents: 2');
diff --git a/docs/includes/usage-examples/operation-description.rst b/docs/includes/usage-examples/operation-description.rst
@@ -1,2 +1,3 @@
-|operator-description| by creating a query builder, using a method such
-as ``Model::where()`` or the ``DB`` facade to match documents in a collection, and then calling |result-operation|.
+|operator-description| by using a method such as ``Model::where()`` or
+methods from the ``DB`` facade to match documents, and then calling
+|result-operation|.
diff --git a/docs/usage-examples.txt b/docs/usage-examples.txt
@@ -43,6 +43,10 @@ operations. Each usage example includes the following components:
 - Example code that you can run from an application controller
 - Output displayed by the print statement
 
+To learn more about the operations demonstrated in the usage examples,
+see the :ref:`laravel-fundamentals-read-ops` and
+:ref:`laravel-fundamentals-write-ops` guides.
+
 How to Use the Usage Examples
 -----------------------------
 
diff --git a/docs/usage-examples/count.txt b/docs/usage-examples/count.txt
@@ -25,35 +25,79 @@ Count Documents
 
    .. replacement:: result-operation
 
-      the ``count()`` method to retrieve the results.
+      the ``count()`` method to retrieve the results
 
 Example
 -------
 
-This usage example performs the following actions:
-
-- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the
-  ``sample_mflix`` database
-- Counts the documents from the ``movies`` collection that match a query filter
-- Prints the matching document count
-
-The example calls the following methods on the ``Movie`` model:
-
-- ``where()``: Matches documents in which the value of the ``genres`` field includes ``"Biography"``.
-- ``count()``: Counts the number of matching documents. This method returns an integer value.
-
-.. io-code-block::
-
-   .. input:: ../includes/usage-examples/CountTest.php
-      :start-after: begin-count
-      :end-before: end-count
-      :language: php
-      :dedent:
-
-   .. output::
-      :language: console
-      :visible: false
-
-      Number of documents: 1267
+Select from the following :guilabel:`Eloquent` and :guilabel:`Query
+Builder` tabs to view usage examples for the same operation that use
+each corresponding query syntax:
+
+.. tabs::
+
+   .. tab:: Eloquent
+      :tabid: eloquent-model-count
+
+      This example performs the following actions:
+      
+      - Uses the ``Movie`` Eloquent model to represent the ``movies``
+        collection in the ``sample_mflix`` database
+      - Counts the documents from the ``movies`` collection that match a
+        query filter
+      - Prints the matching document count
+      
+      The example calls the following methods on the ``Movie`` model:
+      
+      - ``where()``: Matches documents in which the value of the
+        ``genres`` field includes ``"Biography"``
+      - ``count()``: Counts the number of matching documents and returns
+        the count as an integer
+      
+      .. io-code-block::
+      
+         .. input:: ../includes/usage-examples/CountTest.php
+            :start-after: begin-eloquent-count
+            :end-before: end-eloquent-count
+            :language: php
+            :dedent:
+      
+         .. output::
+            :language: console
+            :visible: false
+      
+            Number of documents: 1267
+
+   .. tab:: Query Builder
+      :tabid: query-builder-count
+
+      This example performs the following actions:
+      
+      - Accesses the ``movies`` collection by calling the ``table()``
+        method from the ``DB`` facade
+      - Counts the documents from the ``movies`` collection that match a
+        query filter
+      - Prints the matching document count
+      
+      The example calls the following query builder methods:
+      
+      - ``where()``: Matches documents in which the value of the
+        ``genres`` field includes ``"Biography"``
+      - ``count()``: Counts the number of matching documents and returns
+        the count as an integer
+      
+      .. io-code-block::
+      
+         .. input:: ../includes/usage-examples/CountTest.php
+            :start-after: begin-qb-count
+            :end-before: end-qb-count
+            :language: php
+            :dedent:
+      
+         .. output::
+            :language: console
+            :visible: false
+      
+            Number of documents: 1267
 
 .. include:: /includes/usage-examples/fact-edit-laravel-app.rst
diff --git a/docs/usage-examples/deleteMany.txt b/docs/usage-examples/deleteMany.txt
@@ -17,48 +17,90 @@ Delete Multiple Documents
    :depth: 1
    :class: singlecol
 
-You can delete multiple documents in a collection by calling the ``delete()`` method on an
-object collection or a query builder.
+You can delete multiple documents in a collection by calling the
+``delete()`` method on an object collection or a query builder.
 
-To delete multiple documents, pass a query filter to the ``where()`` method. Then, delete the
-matching documents by calling the ``delete()`` method.
-
-Example
--------
-
-This usage example performs the following actions:
-
-- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the
-  ``sample_mflix`` database
-- Deletes documents from the ``movies`` collection that match a query filter
-- Prints the number of deleted documents
-
-The example calls the following methods on the ``Movie`` model:
-
-- ``where()``: matches documents in which the value of the ``year`` field is less than or
-  equal to ``1910``.
-- ``delete()``: deletes the matched documents. This method returns the number
-  of documents that the method successfully deletes.
-
-.. io-code-block::
-   :copyable: true
-
-   .. input:: ../includes/usage-examples/DeleteManyTest.php
-      :start-after: begin-delete-many
-      :end-before: end-delete-many
-      :language: php
-      :dedent:
-
-   .. output::
-      :language: console
-      :visible: false
-
-      Deleted documents: 7
-
-.. include:: /includes/usage-examples/fact-edit-laravel-app.rst
+To delete multiple documents, pass a query filter to the ``where()``
+method. Then, delete the matching documents by calling the ``delete()``
+method.
 
 .. tip::
 
    To learn more about deleting documents with the {+odm-short+}, see the :ref:`laravel-fundamentals-delete-documents`
    section of the Write Operations guide.
 
+Example
+-------
+
+Select from the following :guilabel:`Eloquent` and :guilabel:`Query
+Builder` tabs to view usage examples for the same operation that use
+each corresponding query syntax:
+
+.. tabs::
+
+   .. tab:: Eloquent
+      :tabid: eloquent-model-count
+
+      This example performs the following actions:
+      
+      - Uses the ``Movie`` Eloquent model to represent the ``movies``
+        collection in the ``sample_mflix`` database 
+      - Deletes documents from the ``movies`` collection that match a
+        query filter
+      - Prints the number of deleted documents
+      
+      The example calls the following methods on the ``Movie`` model:
+      
+      - ``where()``: Matches documents in which the value of the
+        ``year`` field is less than or equal to ``1910``
+      - ``delete()``: Deletes the matched documents and returns the
+        number of documents successfully deleted
+      
+      .. io-code-block::
+         :copyable: true
+      
+         .. input:: ../includes/usage-examples/DeleteManyTest.php
+            :start-after: begin-eloquent-delete-many
+            :end-before: end-eloquent-delete-many
+            :language: php
+            :dedent:
+      
+         .. output::
+            :language: console
+            :visible: false
+      
+            Deleted documents: 7
+
+   .. tab:: Query Builder
+      :tabid: query-builder-count
+
+      This example performs the following actions:
+      
+      - Accesses the ``movies`` collection by calling the ``table()``
+        method from the ``DB`` facade
+      - Deletes documents from the ``movies`` collection that match a
+        query filter
+      - Prints the number of deleted documents
+      
+      The example calls the following query builder methods:
+      
+      - ``where()``: Matches documents in which the value of the
+        ``year`` field is less than or equal to ``1910``
+      - ``delete()``: Deletes the matched documents and returns the
+        number of documents successfully deleted
+      
+      .. io-code-block::
+      
+         .. input:: ../includes/usage-examples/DeleteManyTest.php
+            :start-after: begin-qb-delete-many
+            :end-before: end-qb-delete-many
+            :language: php
+            :dedent:
+      
+         .. output::
+            :language: console
+            :visible: false
+      
+            Deleted documents: 7
+
+.. include:: /includes/usage-examples/fact-edit-laravel-app.rst
diff --git a/docs/usage-examples/find.txt b/docs/usage-examples/find.txt
@@ -25,7 +25,7 @@ Find Multiple Documents
 
    .. replacement:: result-operation
 
-      the ``get()`` method to retrieve the results.
+      the ``get()`` method to retrieve the results
 
 Pass a query filter to the ``where()`` method to retrieve documents that meet a
 set of criteria. When you call the ``get()`` method, MongoDB returns the
diff --git a/docs/usage-examples/findOne.txt b/docs/usage-examples/findOne.txt
@@ -19,7 +19,7 @@ Find a Document
 
    .. replacement:: result-operation
 
-      the ``first()`` method to return one document.
+      the ``first()`` method to return one document
 
 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
