DOCSP-35978: Insert multiple usage example

docs/includes/usage-examples/InsertManyTest.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers;
+
+use App\Models\Movie;
+use MongoDB\Laravel\Tests\TestCase;
+
+class InsertManyTest extends TestCase
+{
+    /**
+     * @runInSeparateProcess
+     * @preserveGlobalState disabled
+     */
+    public function testInsertMany(): void
+    {
+        require_once __DIR__ . '/Movie.php';
+
+        Movie::truncate();
+
+        // begin-insert-many
+        $result = Movie::insert([
+            [
+                'title' => 'Anatomy of a Fall',
+                'year' => 2023,
+            ],
+            [
+                'title' => 'The Boy and the Heron',
+                'year' => 2023,
+            ],
+            [
+                'title' => 'Passages',
+                'year' => 2023,
+            ],
+        ]);
+
+        echo 'Insert operation success: ' . $result;
+        // end-insert-many
+
+        $this->assertTrue($result);
+        $this->expectOutputString('Insert operation success: 1');
+    }
+}

docs/usage-examples.txt

@@ -74,3 +74,4 @@ calls the controller function and returns the result to a web interface.
    /usage-examples/findOne
    /usage-examples/updateOne
    /usage-examples/deleteOne
+   /usage-examples/insertMany

docs/usage-examples/insertMany.txt

@@ -0,0 +1,62 @@
+.. _laravel-insert-many-usage:
+
+=========================
+Insert Multiple Documents
+=========================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: insert many, add, create, bulk, code example
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+You can insert multiple documents into a collection by calling the ``insert()``
+method on an Eloquent model or a query builder.
+
+To insert multiple documents, call the ``insert()`` method and specify the documents' field
+values as an array inside the method call. 
+
+Example
+-------
+
+This usage example performs the following actions:
+
+- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the
+  ``sample_mflix`` database
+- Inserts documents into the ``movies`` collection
+- Prints the result of the insert operation
+
+The example calls the ``insert()`` method to insert documents in which the value of the
+``year`` field is ``2023``. This method returns a value of ``1`` if the operation is successful
+and throws an exception if the operation is unsuccessful.
+
+.. io-code-block::
+   :copyable: true
+
+   .. input:: ../includes/usage-examples/InsertManyTest.php
+      :start-after: begin-insert-many
+      :end-before: end-insert-many
+      :language: php
+      :dedent:
+
+   .. output::
+      :language: console
+      :visible: false
+
+      Insert operation success: 1
+
+For instructions on editing your Laravel application to run the usage example, see the
+:ref:`Usage Example landing page <laravel-usage-examples>`.
+
+.. tip::
+
+   To learn more  about insert operations, see the :ref:`laravel-fundamentals-insert-documents` section
+   of the Write Operations guide.
+