wip

mongodb · Jan 30, 2025 · a69ed4b · a69ed4b
1 parent 111b290
commit a69ed4b
Show file tree

Hide file tree

Showing 8 changed files with 323 additions and 135 deletions.
diff --git a/docs/includes/usage-examples/DeleteManyTest.php b/docs/includes/usage-examples/DeleteManyTest.php
@@ -37,15 +37,15 @@ public function testDeleteMany(): void
         echo 'Deleted documents: ' . $deleted;
         // end-eloquent-delete-many
 
+        $this->assertEquals(2, $deleted);
+        $this->expectOutputString('Deleted documents: 2');
+
         // 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/DeleteOneTest.php b/docs/includes/usage-examples/DeleteOneTest.php
@@ -35,6 +35,9 @@ public function testDeleteOne(): void
         echo 'Deleted documents: ' . $deleted;
         // end-eloquent-delete-one
 
+        $this->assertEquals(1, $deleted);
+        $this->expectOutputString('Deleted documents: 1');
+
         // begin-qb-delete-one
         $deleted = DB::table('movies')
             ->where('title', 'Quiz Show')
@@ -44,8 +47,5 @@ public function testDeleteOne(): void
 
         echo 'Deleted documents: ' . $deleted;
         // end-qb-delete-one
-
-        $this->assertEquals(1, $deleted);
-        $this->expectOutputString('Deleted documents: 1');
     }
 }
diff --git a/docs/includes/usage-examples/FindManyTest.php b/docs/includes/usage-examples/FindManyTest.php
@@ -5,6 +5,7 @@
 namespace App\Http\Controllers;
 
 use App\Models\Movie;
+use Illuminate\Support\Facades\DB;
 use MongoDB\Laravel\Tests\TestCase;
 
 class FindManyTest extends TestCase
@@ -33,11 +34,18 @@ public function testFindMany(): void
             ],
         ]);
 
-        // begin-find
+        // begin-eloquent-find
         $movies = Movie::where('runtime', '>', 900)
             ->orderBy('_id')
             ->get();
-        // end-find
+        // end-eloquent-find
+
+        // begin-qb-find
+        $movies = DB::table('movies')
+            ->where('runtime', '>', 900)
+            ->orderBy('_id')
+            ->get();
+        // end-qb-find
 
         $this->assertEquals(2, $movies->count());
     }

diff --git a/docs/includes/usage-examples/FindOneTest.php b/docs/includes/usage-examples/FindOneTest.php
@@ -5,6 +5,7 @@
 namespace App\Http\Controllers;
 
 use App\Models\Movie;
+use Illuminate\Support\Facades\DB;
 use MongoDB\Laravel\Tests\TestCase;
 
 class FindOneTest extends TestCase
@@ -22,15 +23,24 @@ public function testFindOne(): void
             ['title' => 'The Shawshank Redemption', 'directors' => ['Frank Darabont', 'Rob Reiner']],
         ]);
 
-        // begin-find-one
+        // begin-eloquent-find-one
         $movie = Movie::where('directors', 'Rob Reiner')
           ->orderBy('_id')
           ->first();
 
         echo $movie->toJson();
-        // end-find-one
+        // end-eloquent-find-one
 
         $this->assertInstanceOf(Movie::class, $movie);
         $this->expectOutputRegex('/^{"_id":"[a-z0-9]{24}","title":"The Shawshank Redemption","directors":\["Frank Darabont","Rob Reiner"\]}$/');
+
+        // begin-qb-find-one
+        $movie = DB::table('movies')
+          ->where('directors', 'Rob Reiner')
+          ->orderBy('_id')
+          ->first();
+
+        echo $movie->toJson();
+        // end-qb-find-one
     }
 }
diff --git a/docs/includes/usage-examples/InsertManyTest.php b/docs/includes/usage-examples/InsertManyTest.php
@@ -6,6 +6,7 @@
 
 use App\Models\Movie;
 use DateTimeImmutable;
+use Illuminate\Support\Facades\DB;
 use MongoDB\BSON\UTCDateTime;
 use MongoDB\Laravel\Tests\TestCase;
 
@@ -21,7 +22,7 @@ public function testInsertMany(): void
 
         Movie::truncate();
 
-        // begin-insert-many
+        // begin-eloquent-insert-many
         $success = Movie::insert([
             [
                 'title' => 'Anatomy of a Fall',
@@ -38,7 +39,27 @@ public function testInsertMany(): void
         ]);
 
         echo 'Insert operation success: ' . ($success ? 'yes' : 'no');
-        // end-insert-many
+        // end-eloquent-insert-many
+
+        // begin-qb-insert-many
+        $success = DB::table('movies')
+            ->insert([
+                [
+                    'title' => 'Anatomy of a Fall',
+                    'release_date' => new UTCDateTime(new DateTimeImmutable('2023-08-23')),
+                ],
+                [
+                    'title' => 'The Boy and the Heron',
+                    'release_date' => new UTCDateTime(new DateTimeImmutable('2023-12-08')),
+                ],
+                [
+                    'title' => 'Passages',
+                    'release_date' => new UTCDateTime(new DateTimeImmutable('2023-06-28')),
+                ],
+            ]);
+
+        echo 'Insert operation success: ' . ($success ? 'yes' : 'no');
+        // end-qb-insert-many
 
         $this->assertTrue($success);
         $this->expectOutputString('Insert operation success: yes');

diff --git a/docs/usage-examples/find.txt b/docs/usage-examples/find.txt
@@ -29,62 +29,121 @@ Find Multiple Documents
 
 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
-matching documents according to their :term:`natural order` in the database or
+matching documents according to their :term:`natural order` in the collection or
 according to the sort order that you can specify by using the ``orderBy()``
 method.
 
-To learn more about query builder methods, see the :ref:`laravel-query-builder`
-guide.
+.. tip::
+
+   To learn about other ways to retrieve documents with the
+   {+odm-short+}, see the :ref:`laravel-fundamentals-retrieve` guide.
 
 Example
 -------
 
-This usage example performs the following actions:
-
-- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the
-  ``sample_mflix`` database
-- Retrieves and prints documents from the ``movies`` collection that match a query filter
-
-The example calls the following methods on the ``Movie`` model:
-
-- ``where()``: matches documents in which the value of the ``runtime`` field is greater than ``900``
-- ``orderBy()``: sorts matched documents by their ascending ``_id`` values
-- ``get()``: retrieves the query results as a Laravel collection object
-
-.. io-code-block::
-   :copyable: true
-
-   .. input:: ../includes/usage-examples/FindManyTest.php
-      :start-after: begin-find
-      :end-before: end-find
-      :language: php
-      :dedent:
-
-   .. output::
-      :language:  json
-      :visible: false
-
-      // Results are truncated
-
-      [
-        {
-          "_id": ...,
-          "runtime": 1256,
-          "title": "Centennial",
-          ...,
-        },
-        {
-          "_id": ...,
-          "runtime": 1140,
-          "title": "Baseball",
-          ...,
-        },
-        ...
-      ]
+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 
+      - Retrieves and prints documents from the ``movies`` collection
+        that match a query filter
+
+      The example calls the following methods on the ``Movie`` model:
+
+      - ``where()``: Matches documents in which the value of the
+        ``runtime`` field is greater than ``900``
+      - ``orderBy()``: Sorts matched documents by their ascending
+        ``_id`` values
+      - ``get()``: Retrieves the query results as a Laravel collection
+        object
+
+      .. io-code-block::
+         :copyable: true
+
+         .. input:: ../includes/usage-examples/FindManyTest.php
+            :start-after: begin-eloquent-find
+            :end-before: end-eloquent-find
+            :language: php
+            :dedent:
+
+         .. output::
+            :language: console
+            :visible: false
+
+            // Results are truncated
+
+            [
+              {
+                "_id": ...,
+                "runtime": 1256,
+                "title": "Centennial",
+                ...,
+              },
+              {
+                "_id": ...,
+                "runtime": 1140,
+                "title": "Baseball",
+                ...,
+              },
+              ...
+            ]
+
+   .. 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
+      - Retrieves and prints documents from the ``movies`` collection
+        that match a query filter
+
+      The example calls the following query builder methods:
+
+      - ``where()``: Matches documents in which the value of the
+        ``runtime`` field is greater than ``900``
+      - ``orderBy()``: Sorts matched documents by their ascending
+        ``_id`` values
+      - ``get()``: Retrieves the query results as a Laravel collection
+        object
+
+      .. io-code-block::
+
+         .. input:: ../includes/usage-examples/FindManyTest.php
+            :start-after: begin-qb-find
+            :end-before: end-qb-find
+            :language: php
+            :dedent:
+
+         .. output::
+            :language: console
+            :visible: false
+
+            // Results are truncated
+
+            [
+              {
+                "_id": ...,
+                "runtime": 1256,
+                "title": "Centennial",
+                ...,
+              },
+              {
+                "_id": ...,
+                "runtime": 1140,
+                "title": "Baseball",
+                ...,
+              },
+              ...
+            ]
 
 .. include:: /includes/usage-examples/fact-edit-laravel-app.rst
-
-.. tip::
-
-   To learn about other ways to retrieve documents with the {+odm-short+}, see the
-   :ref:`laravel-fundamentals-retrieve` guide.