Merge 4.2 into 4.3

docs/includes/usage-examples/InsertOneTest.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers;
+
+use App\Models\Movie;
+use MongoDB\Laravel\Tests\TestCase;
+
+class InsertOneTest extends TestCase
+{
+    /**
+     * @runInSeparateProcess
+     * @preserveGlobalState disabled
+     */
+    public function testInsertOne(): void
+    {
+        require_once __DIR__ . '/Movie.php';
+
+        Movie::truncate();
+
+        // begin-insert-one
+        $movie = Movie::create([
+            'title' => 'Marriage Story',
+            'year' => 2019,
+            'runtime' => 136,
+        ]);
+
+        echo $movie->toJson();
+        // end-insert-one
+
+        $this->assertInstanceOf(Movie::class, $movie);
+        $this->expectOutputRegex('/^{"title":"Marriage Story","year":2019,"runtime":136,"updated_at":".{27}","created_at":".{27}","_id":"[a-z0-9]{24}"}$/');
+    }
+}

docs/includes/usage-examples/RunCommandTest.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers;
+
+use Illuminate\Support\Facades\DB;
+use MongoDB\Driver\Cursor;
+use MongoDB\Laravel\Tests\TestCase;
+
+class RunCommandTest extends TestCase
+{
+    public function testRunCommand(): void
+    {
+        // begin-command
+        $cursor = DB::connection('mongodb')
+            ->command(['listCollections' => 1]);
+
+        foreach ($cursor as $coll) {
+            echo $coll['name'] . "<br>\n";
+        }
+
+        // end-command
+
+        $this->assertNotNull($cursor);
+        $this->assertInstanceOf(Cursor::class, $cursor);
+        $this->expectOutputRegex('/<br>/');
+    }
+}

docs/includes/usage-examples/UpdateManyTest.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers;
+
+use App\Models\Movie;
+use MongoDB\Laravel\Tests\TestCase;
+
+class UpdateManyTest extends TestCase
+{
+    /**
+     * @runInSeparateProcess
+     * @preserveGlobalState disabled
+     */
+    public function testUpdateMany(): void
+    {
+        require_once __DIR__ . '/Movie.php';
+
+        Movie::truncate();
+        Movie::insert([
+            [
+                'title' => 'Hollywood',
+                'imdb' => [
+                    'rating' => 9.1,
+                    'votes' => 511,
+                ],
+            ],
+            [
+                'title' => 'The Shawshank Redemption',
+                'imdb' => [
+                    'rating' => 9.3,
+                    'votes' => 1513145,
+                ],
+            ],
+        ]);
+
+        // begin-update-many
+        $updates = Movie::where('imdb.rating', '>', 9.0)
+            ->update(['acclaimed' => true]);
+
+        echo 'Updated documents: ' . $updates;
+        // end-update-many
+
+        $this->assertEquals(2, $updates);
+        $this->expectOutputString('Updated documents: 2');
+    }
+}

docs/index.txt

@@ -61,6 +61,7 @@ Fundamentals
 To learn how to perform the following tasks by using {+odm-short+},
 see the following content:
 
+- :ref:`Manage Databases and Collections <laravel-db-coll>`
 - :ref:`laravel-fundamentals-read-ops`
 - :ref:`laravel-fundamentals-write-ops`
 - :ref:`laravel-eloquent-models`
@@ -75,6 +76,12 @@ Issues & Help
 Learn how to report bugs, contribute to the library, and find
 more resources in the :ref:`laravel-issues-and-help` section.
 
+Feature Compatibility
+---------------------
+
+Learn about Laravel features that {+odm-short+} supports in the
+:ref:`laravel-feature-compat` section.
+
 Compatibility
 -------------
 

docs/usage-examples.txt

@@ -72,9 +72,12 @@ calls the controller function and returns the result to a web interface.
    :maxdepth: 1
 
    /usage-examples/findOne
+   /usage-examples/insertOne
    /usage-examples/insertMany
    /usage-examples/updateOne
+   /usage-examples/updateMany
    /usage-examples/deleteOne
    /usage-examples/deleteMany
    /usage-examples/count
    /usage-examples/distinct
+   /usage-examples/runCommand

docs/usage-examples/deleteOne.txt

@@ -32,6 +32,7 @@ This usage example performs the following actions:
 - Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the
   ``sample_mflix`` database
 - Deletes a document from the ``movies`` collection that matches a query filter
+- Prints the number of deleted documents
 
 The example calls the following methods on the ``Movie`` model:
 

docs/usage-examples/findOne.txt

@@ -19,8 +19,9 @@ 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.
+  ``sample_mflix`` database
+- Retrieves a document from the ``movies`` collection that matches a query filter
+- Prints the retrieved document
 
 The example calls the following methods on the ``Movie`` model:
 

docs/usage-examples/insertOne.txt

@@ -0,0 +1,73 @@
+.. _laravel-insert-one-usage:
+
+=================
+Insert a Document
+=================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: insert one, add one, code example
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+You can insert a document into a collection by calling the ``create()`` method on
+an Eloquent model or query builder.
+
+To insert a document, pass the data you need to insert as a document containing
+the fields and values to the ``create()`` method.
+
+Example
+-------
+
+This usage example performs the following actions:
+
+- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the
+  ``sample_mflix`` database
+- Inserts a document into the ``movies`` collection
+
+The example calls the ``create()`` method to insert a document that contains the following
+information:
+
+- ``title`` value of ``"Marriage Story"``
+- ``year`` value of ``2019``
+- ``runtime`` value of ``136``
+
+.. io-code-block::
+   :copyable: true
+
+   .. input:: ../includes/usage-examples/InsertOneTest.php
+      :start-after: begin-insert-one
+      :end-before: end-insert-one
+      :language: php
+      :dedent:
+
+   .. output::
+      :language: json
+      :visible: false
+
+      {
+          "title": "Marriage Story",
+          "year": 2019,
+          "runtime": 136,
+          "updated_at": "...",
+          "created_at": "...",
+          "_id": "..."
+      }
+
+To learn how to edit your Laravel application to run the usage example, see the
+:ref:`Usage Examples landing page <laravel-usage-examples>`.
+
+.. tip::
+
+   You can also use the ``save()`` or ``insert()`` methods to insert a document into a collection.
+   To learn more  about insert operations, see the :ref:`laravel-fundamentals-insert-documents` section
+   of the Write Operations guide.
+
+

docs/usage-examples/runCommand.txt

@@ -0,0 +1,53 @@
+.. _laravel-run-command-usage:
+
+=============
+Run a Command
+=============
+
+You can run a MongoDB command directly on a database by calling the ``command()``
+method on a database connection instance.
+
+To run a command, call the ``command()`` method and pass it a document that
+contains the command and its parameters.
+
+Example
+-------
+
+This usage example performs the following actions on the database connection
+instance that uses the ``sample_mflix`` database:
+
+- Creates a database connection instance that references the ``sample_mflix`` 
+  database
+- Specifies a command to retrieve a list of collections and views in the
+  ``sample_mflix``  database
+- Prints the value of the ``name`` field of each result returned by the command
+
+The example calls the ``command()`` method to run the ``listCollections`` command. This method
+returns a cursor that contains a result document for each collection in the database.
+
+.. io-code-block::
+
+   .. input:: ../includes/usage-examples/RunCommandTest.php
+      :start-after: begin-command
+      :end-before: end-command
+      :language: php
+      :dedent:
+
+   .. output::
+      :language: console
+      :visible: false
+
+      sessions
+      movies
+      theaters
+      comments
+      embedded_movies
+      users
+
+To learn how to edit your Laravel application to run the usage example, see the
+:ref:`Usage Examples landing page <laravel-usage-examples>`.
+
+.. tip::
+
+   To learn more about running MongoDB database commands, see
+   :manual:`Database Commands </reference/command/>` in the {+server-docs-name+}.

docs/usage-examples/updateMany.txt

@@ -0,0 +1,67 @@
+.. _laravel-update-one-usage:
+
+=========================
+Update Multiple Documents
+=========================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: update many, modify, code example
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+You can update multiple documents in a collection by calling the ``update()`` method
+on a query builder.
+
+Pass a query filter to the ``where()`` method to retrieve documents that meet a
+set of criteria. Then, update the matching documents by passing your intended
+document changes to the ``update()`` method.
+
+Example
+-------
+
+This usage example performs the following actions:
+
+- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the
+  ``sample_mflix`` database
+- Updates documents from the ``movies`` collection that match a query filter
+- Prints the number of updated documents
+
+The example calls the following methods on the ``Movie`` model:
+
+- ``where()``: matches documents in which the value of the ``imdb.rating`` nested field
+  is greater than ``9``.
+- ``update()``: updates the matching documents by adding an ``acclaimed`` field and setting
+  its value to ``true``. This method returns the number of documents that were successfully
+  updated.
+
+.. io-code-block::
+   :copyable: true
+
+   .. input:: ../includes/usage-examples/UpdateManyTest.php
+      :start-after: begin-update-many
+      :end-before: end-update-many
+      :language: php
+      :dedent:
+
+   .. output::
+      :language: console
+      :visible: false
+
+      Updated documents: 20
+
+To learn how to edit your Laravel application to run the usage example, see the
+:ref:`Usage Examples landing page <laravel-usage-examples>`.
+
+.. tip::
+
+   To learn more about updating data with {+odm-short+}, see the :ref:`laravel-fundamentals-modify-documents`
+   section of the Write Operations guide.
+

docs/usage-examples/updateOne.txt

@@ -30,8 +30,9 @@ Example
 This usage example performs the following actions:
 
 - Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the
-  ``sample_mflix`` database.
-- Updates a document from the ``movies`` collection that matches a query filter.
+  ``sample_mflix`` database
+- Updates a document from the ``movies`` collection that matches a query filter
+- Prints the number of updated documents
 
 The example calls the following methods on the ``Movie`` model: