DOCSP-35949 write operations upsert

docs/fundamentals/write-operations.txt

@@ -9,7 +9,7 @@ Write Operations
    :values: tutorial
 
 .. meta::
-   :keywords: insert, insert one, update, update one, upsert, delete, delete many, code example, mass assignment, eloquent model
+   :keywords: insert, insert one, update, update one, upsert, code example, mass assignment, eloquent model
 
 .. contents:: On this page
    :local:
@@ -27,9 +27,31 @@ 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
+- :ref:`laravel-fundamentals-modify-documents`
 - Delete Documents
 
+.. _laravel-fundamentals-write-sample-model:
+
+Sample Model
+~~~~~~~~~~~~
+
+The write operations in this guide reference the following Eloquent model class:
+
+.. 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.
+
 .. _laravel-fundamentals-insert-documents:
 
 Insert Documents
@@ -82,6 +104,8 @@ 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 an array of strings to the ``genre`` field
+- Assigns a number to the ``ticketsSold`` field
 - Assigns a date to the ``performanceDate`` field by using the ``Carbon``
   package
 - Inserts the document by calling the ``save()`` method
@@ -93,7 +117,7 @@ This example code performs the following actions:
    :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:
+``id`` member, as shown in the following code example:
 
 .. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php
    :language: php
@@ -103,7 +127,7 @@ You can retrieve the inserted document's ``_id`` value by accessing the model's
 
 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:
+to perform the insert in a single call, as shown in the following example:
 
 .. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php
    :language: php
@@ -122,15 +146,16 @@ 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.
+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>`__
+    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.
 
@@ -140,3 +165,167 @@ an array to the ``insert()`` method:
    :start-after: begin model insert many
    :end-before: end model insert many
 
+.. _laravel-fundamentals-modify-documents:
+
+Modify Documents
+----------------
+
+In this section, you can learn how to modify documents in your MongoDB
+collection from your Laravel application. Use update operations to modify
+existing documents or to insert a document if no documents match the search
+criteria.
+
+Eloquent lets you specify criteria to retrieve documents, perform updates on
+the returned object collections, and save them.
+
+This section provides examples of the following update operations:
+
+- :ref:`Update a document <laravel-modify-documents-update-one>`
+- :ref:`Update multiple documents <laravel-modify-documents-update-multiple>`
+- :ref:`Update or insert in a single operation <laravel-modify-documents-upsert>`
+
+.. _laravel-modify-documents-update-one:
+
+Update a Document Examples
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can update a document in the following ways:
+
+- Modify an instance of the model and save the changes by calling the ``save()``
+  method.
+- Use the fluent syntax to retrieve a matching document and apply updates to
+  it by calling the ``update()`` method or other helper methods.
+
+The following example shows how to update a document by modifying an instance
+of the model and calling its ``save()`` method:
+
+.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php
+   :language: php
+   :dedent:
+   :start-after: begin model update one save
+   :end-before: end model update one save
+
+When the ``save()`` method succeeds, the model instance on which you called the
+method.
+
+If the operation fails, {+odm-short+} assigns the model instance a null value.
+
+The following example shows how to update a document by using fluent syntax to
+retrieve the first match and apply updates to the matching document:
+
+.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php
+   :language: php
+   :dedent:
+   :start-after: begin model update one fluent
+   :end-before: end model update one fluent
+
+.. note::
+
+   The ``orderBy()`` call sorts the results by the ``_id`` field to
+   guarantee a consistent sort order. To learn more about sorting in MongoDB,
+   see the :manual:`Natural order </reference/glossary/#std-term-natural-order>`
+   glossary entry in the {+server-docs-name+}.
+
+When the ``update()`` method succeeds, the operation returns the number of
+documents updated.
+
+If the retrieve part of the call does not match any documents in the collection,
+{+odm-short+} returns the following error:
+
+.. code-block:: none
+   :copyable: false
+
+   Error: Call to a member function update() on null
+
+.. _laravel-modify-documents-update-multiple:
+
+Update Multiple Documents Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To perform an update on one or more documents, call the ``update()``
+method on a collection of model objects. You can use the fluent syntax to
+retrieve a collection of model objects that match your criteria and then
+pass your updates to the ``update()`` method.
+
+The following example shows how to chain calls to retrieve a collection of
+model objects and apply updates to all matching documents:
+
+.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php
+   :language: php
+   :dedent:
+   :start-after: begin model update multiple
+   :end-before: end model update multiple
+
+When the ``update()`` method succeeds, the operation returns the number of
+documents updated.
+
+If the retrieve part of the call does not match any documents in the
+collection, {+odm-short+} returns the following error:
+
+.. code-block:: none
+   :copyable: false
+
+   Error: Call to a member function update() on null
+
+.. _laravel-modify-documents-upsert:
+
+Update or Insert in a Single Operation
+--------------------------------------
+
+An **upsert** operation lets you perform an update or insert in a single
+operation. This operation streamlines the task of updating a document or
+inserting one if it does not exist.
+
+To specify an upsert in an ``update()`` method, set the ``upsert`` option to
+``true`` as shown in the following code example:
+
+.. code-block:: php
+   :emphasize-lines: 4
+   :copyable: false
+
+   YourModel::where(/* match criteria */)
+      ->update(
+          [/* update data */],
+          ['upsert' => true]);
+
+When the ``update()`` method is chained to a query, it performs one of the
+following actions:
+
+- If the query matches documents, the ``update()`` method modifies the matching
+  documents.
+- If the query matches zero documents, the ``update()`` method inserts a
+  document that contains the update data and the equality match criteria data.
+
+Upsert Example
+~~~~~~~~~~~~~~
+
+This example shows how to pass the ``upsert`` option to the  ``update()``
+method to perform an update or insert in a single operation. Click the
+:guilabel:`VIEW OUTPUT` button to see the example document inserted when no
+matching documents exist:
+
+.. io-code-block::
+
+   .. input:: /includes/fundamentals/write-operations/WriteOperationsTest.php
+      :language: php
+      :dedent:
+      :emphasize-lines: 4
+      :start-after: begin model upsert
+      :end-before: end model upsert
+
+   .. output::
+      :language: json
+      :visible: false
+
+      {
+        "_id": "660c...",
+        "performer": "Jon Batiste",
+        "venue": "Radio City Music Hall",
+        "genres": [
+          "R&B",
+          "soul"
+        ],
+        "ticketsSold": 4000,
+        "updated_at": ...
+      }
+

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

@@ -7,6 +7,6 @@
 class Concert extends Model
 {
     protected $connection = 'mongodb';
-    protected $fillable = ['performer', 'venue', 'performanceDate'];
+    protected $fillable = ['performer', 'venue', 'genres', 'ticketsSold', 'performanceDate'];
     protected $casts = ['performanceDate' => 'datetime'];
 }