DOCSP-35948 write operations - insert documents (#2804)

* DOCSP-35948: Write operations

Author: Chris Cho

docs/fundamentals.txt

@@ -0,0 +1,25 @@
+.. _laravel_fundamentals:
+
+============
+Fundamentals
+============
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: php framework, odm
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+   /fundamentals/read-operations
+   /fundamentals/write-operations
+
+Learn how to use the {+odm-long+} to perform the following tasks:
+
+- :ref:`Read Operations <laravel-fundamentals-read-ops>`
+- :ref:`Write Operations <laravel-fundamentals-write-ops>`
+

docs/retrieve.txt renamed to docs/fundamentals/read-operations.txt

@@ -1,8 +1,9 @@
 .. _laravel-fundamentals-retrieve:
+.. _laravel-fundamentals-read-ops:
 
-==============
-Retrieve Data
-==============
+===============
+Read Operations
+===============
 
 .. facet::
    :name: genre

docs/fundamentals/write-operations.txt

@@ -0,0 +1,142 @@
+.. _laravel-fundamentals-write-ops:
+
+================
+Write Operations
+================
+
+.. facet::
+   :name: genre
+   :values: tutorial
+
+.. meta::
+   :keywords: insert, insert one, update, update one, upsert, delete, delete many, code example, mass assignment, eloquent model
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to use {+odm-short+} to perform
+**write operations** on your MongoDB collections. Write operations include
+inserting, updating, and deleting data based on specified criteria.
+
+This guide shows you how to perform the following tasks:
+
+- :ref:`laravel-fundamentals-insert-documents`
+- Modify Documents
+- Delete Documents
+
+.. _laravel-fundamentals-insert-documents:
+
+Insert Documents
+----------------
+
+In this section, you can learn how to insert documents into MongoDB collections
+from your Laravel application by using the {+odm-long+}.
+
+When you insert the documents, ensure the data does not violate any
+unique indexes on the collection. When inserting the first document of a
+collection or creating a new collection, MongoDB automatically creates a
+unique index on the ``_id`` field.
+
+For more information on creating indexes on MongoDB collections by using the
+Laravel schema builder, see the :ref:`laravel-eloquent-indexes` section
+of the Schema Builder documentation.
+
+This section uses the following example model class to demonstrate how to
+use Eloquent models to perform insert operations:
+
+.. literalinclude:: /includes/fundamentals/write-operations/Concert.php
+   :language: php
+   :dedent:
+   :caption: Concert.php
+
+.. tip::
+
+   The ``$fillable`` attribute lets you use Laravel mass assignment for insert
+   operations. To learn more about mass assignment, see :ref:`laravel-model-mass-assignment`
+   in the Eloquent Model Class documentation.
+
+   The ``$casts`` attribute instructs Laravel to convert attributes to common
+   data types. To learn more, see `Attribute Casting <https://laravel.com/docs/{+laravel-docs-version+}/eloquent-mutators#attribute-casting>`__
+   in the Laravel documentation.
+
+To learn more about Eloquent models in {+odm-short+}, see the :ref:`laravel-eloquent-models`
+section.
+
+Insert a Document Examples
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These examples show how to use the ``save()`` Eloquent method to insert an
+instance of a ``Concert`` model as a MongoDB document.
+
+When the ``save()`` method succeeds, you can access the model instance on
+which you called the method. If the operation fails, the model instance is
+assigned ``null``.
+
+This example code performs the following actions:
+
+- Creates a new instance of the ``Concert`` model
+- Assigns string values to the ``performer`` and ``venue`` fields
+- Assigns a date to the ``performanceDate`` field by using the ``Carbon``
+  package
+- Inserts the document by calling the ``save()`` method
+
+.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php
+   :language: php
+   :dedent:
+   :start-after: begin model insert one
+   :end-before: end model insert one
+
+You can retrieve the inserted document's ``_id`` value by accessing the model's
+``id`` member as shown in the following code example:
+
+.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php
+   :language: php
+   :dedent:
+   :start-after: begin inserted id
+   :end-before: end inserted id
+
+If you enable mass assignment by defining either the ``$fillable`` or
+``$guarded`` attributes, you can use the Eloquent model ``create()`` method
+to perform the insert in a single call as shown in the following example:
+
+.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php
+   :language: php
+   :dedent:
+   :start-after: begin model insert one mass assign
+   :end-before: end model insert one mass assign
+
+To learn more about the Carbon PHP API extension, see the
+:github:`Carbon <briannesbitt/Carbon>` GitHub repository.
+
+Insert Multiple Documents Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This example shows how to use the ``insert()`` Eloquent method to insert
+multiple instances of a ``Concert`` model as MongoDB documents. This bulk
+insert method reduces the number of calls your application needs to make
+to save the documents.
+
+When the ``insert()`` method succeeds, it returns the value ``1``. If it
+fails, it throws an exception.
+
+The example code saves multiple models in a single call by passing them as
+an array to the ``insert()`` method:
+
+.. note::
+
+    This example wraps the dates in the `MongoDB\BSON\UTCDateTime <{+phplib-api+}/class.mongodb-bson-utcdatetime.php>`__
+    class to convert it to a type MongoDB can serialize because Laravel
+    skips attribute casting on bulk insert operations.
+
+.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php
+   :language: php
+   :dedent:
+   :start-after: begin model insert many
+   :end-before: end model insert many
+

docs/includes/fundamentals/write-operations/Concert.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace App\Models;
+
+use MongoDB\Laravel\Eloquent\Model;
+
+class Concert extends Model
+{
+    protected $connection = 'mongodb';
+    protected $fillable = ['performer', 'venue', 'performanceDate'];
+    protected $casts = ['performanceDate' => 'datetime'];
+}

docs/includes/fundamentals/write-operations/WriteOperationsTest.php

@@ -0,0 +1,100 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers;
+
+use App\Models\Concert;
+use Carbon\Carbon;
+use MongoDB\BSON\UTCDateTime;
+use MongoDB\Laravel\Tests\TestCase;
+
+use function count;
+
+class WriteOperationsTest extends TestCase
+{
+    /**
+     * @runInSeparateProcess
+     * @preserveGlobalState disabled
+     */
+    public function testModelInsert(): void
+    {
+        require_once __DIR__ . '/Concert.php';
+
+        Concert::truncate();
+
+        // begin model insert one
+        $concert = new Concert();
+        $concert->performer = 'Mitsuko Uchida';
+        $concert->venue = 'Carnegie Hall';
+        $concert->performanceDate = Carbon::create(2024, 4, 1, 20, 0, 0, 'EST');
+        $concert->save();
+        // end model insert one
+
+        // begin inserted id
+        $insertedId = $concert->id;
+        // end inserted id
+
+        $this->assertNotNull($concert);
+        $this->assertNotNull($insertedId);
+
+        $result = Concert::first();
+        $this->assertInstanceOf(Concert::class, $result);
+    }
+
+    /**
+     * @runInSeparateProcess
+     * @preserveGlobalState disabled
+     */
+    public function testModelInsertMassAssign(): void
+    {
+        require_once __DIR__ . '/Concert.php';
+
+        Concert::truncate();
+
+        // begin model insert one mass assign
+        $insertResult = Concert::create([
+            'performer' => 'The Rolling Stones',
+            'venue' => 'Soldier Field',
+            'performanceDate' => Carbon::create(2024, 6, 30, 20, 0, 0, 'CDT'),
+        ]);
+        // end model insert one mass assign
+
+        $this->assertNotNull($insertResult);
+
+        $result = Concert::first();
+        $this->assertInstanceOf(Concert::class, $result);
+    }
+
+    /**
+     * @runInSeparateProcess
+     * @preserveGlobalState disabled
+     */
+    public function testModelInsertMany(): void
+    {
+        require_once __DIR__ . '/Concert.php';
+
+        Concert::truncate();
+
+        // begin model insert many
+        $data = [
+            [
+                'performer' => 'Brad Mehldau',
+                'venue' => 'Philharmonie de Paris',
+                'performanceDate' => new UTCDateTime(Carbon::create(2025, 2, 12, 20, 0, 0, 'CET')),
+            ],
+            [
+                'performer' => 'Billy Joel',
+                'venue' => 'Madison Square Garden',
+                'performanceDate' => new UTCDateTime(Carbon::create(2025, 2, 12, 20, 0, 0, 'CET')),
+            ],
+        ];
+
+        Concert::insert($data);
+        // end model insert many
+
+        $results = Concert::get();
+
+        $this->assertEquals(2, count($results));
+    }
+}

docs/index.txt

@@ -15,7 +15,7 @@ Laravel MongoDB
 
    /quick-start
    Release Notes <https://github.com/mongodb/laravel-mongodb/releases/>
-   /retrieve
+   /fundamentals
    /eloquent-models
    /query-builder
    /user-authentication
@@ -53,7 +53,8 @@ Fundamentals
 To learn how to perform the following tasks by using the {+odm-short+},
 see the following content:
 
-- :ref:`laravel-fundamentals-retrieve`
+- :ref:`laravel-fundamentals-read-ops`
+- :ref:`laravel-fundamentals-write-ops`
 - :ref:`laravel-eloquent-models`
 - :ref:`laravel-query-builder`
 - :ref:`laravel-user-authentication`