From 8eb9271201795931bc54e4e06e04a31f581485cb Mon Sep 17 00:00:00 2001
From: Nora Reidy <nora.reidy@mongodb.com>
Date: Wed, 3 Apr 2024 10:51:03 -0400
Subject: [PATCH] DOCSP-35974: Update one usage example (#2781)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* DOCSP-35974: Update one usage example

* fixes

* other usage ex changes

* reworking the example

* add tip, spacing

* restructuring

* reword tip

* fixes

* edits

* reword

* add more running info

* small change

* edits

* source constant

* test file

* move test file

* single quotes

* print syntax

* print statement again

* JT feedback

* apply phpcbf formatting

* code

* apply phpcbf formatting

* JT feedback

* Fix UpdateOneTest example

* add to TOC

---------

Co-authored-by: norareidy <norareidy@users.noreply.github.com>
Co-authored-by: Jérôme Tamarelle <jerome@tamarelle.net>
---
 docs/includes/usage-examples/Movie.php        | 12 ++++
 .../includes/usage-examples/UpdateOneTest.php | 48 +++++++++++++
 docs/usage-examples.txt                       |  8 ++-
 docs/usage-examples/updateOne.txt             | 67 +++++++++++++++++++
 4 files changed, 134 insertions(+), 1 deletion(-)
 create mode 100644 docs/includes/usage-examples/Movie.php
 create mode 100644 docs/includes/usage-examples/UpdateOneTest.php
 create mode 100644 docs/usage-examples/updateOne.txt

diff --git a/docs/includes/usage-examples/Movie.php b/docs/includes/usage-examples/Movie.php
new file mode 100644
index 000000000..728a066de
--- /dev/null
+++ b/docs/includes/usage-examples/Movie.php
@@ -0,0 +1,12 @@
+<?php
+
+namespace App\Models;
+
+use MongoDB\Laravel\Eloquent\Model;
+
+class Movie extends Model
+{
+    protected $connection = 'mongodb';
+    protected $collection = 'movies';
+    protected $fillable = ['title', 'year', 'runtime', 'imdb', 'plot'];
+}
diff --git a/docs/includes/usage-examples/UpdateOneTest.php b/docs/includes/usage-examples/UpdateOneTest.php
new file mode 100644
index 000000000..e1f864170
--- /dev/null
+++ b/docs/includes/usage-examples/UpdateOneTest.php
@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers;
+
+use App\Models\Movie;
+use MongoDB\Laravel\Tests\TestCase;
+
+class UpdateOneTest extends TestCase
+{
+    /**
+     * @runInSeparateProcess
+     * @preserveGlobalState disabled
+     */
+    public function testUpdateOne(): void
+    {
+        require_once __DIR__ . '/Movie.php';
+
+        Movie::truncate();
+        Movie::insert([
+            [
+                'title' => 'Carol',
+                'imdb' => [
+                    'rating' => 7.2,
+                    'votes' => 125000,
+                ],
+            ],
+        ]);
+
+        // begin-update-one
+        $updates = Movie::where('title', 'Carol')
+            ->orderBy('_id')
+            ->first()
+            ->update([
+                'imdb' => [
+                    'rating' => 7.3,
+                    'votes' => 142000,
+                ],
+            ]);
+
+        echo 'Updated documents: ' . $updates;
+        // end-update-one
+
+        $this->assertTrue($updates);
+        $this->expectOutputString('Updated documents: 1');
+    }
+}
diff --git a/docs/usage-examples.txt b/docs/usage-examples.txt
index bf14bba4a..08dda77ea 100644
--- a/docs/usage-examples.txt
+++ b/docs/usage-examples.txt
@@ -65,4 +65,10 @@ a result. To run the operation, you can copy the sample code to a controller end
 Laravel application.
 
 To view the expected output of the operation, you can add a web route to your application that
-calls the controller function and returns the result to a web interface.
\ No newline at end of file
+calls the controller function and returns the result to a web interface.
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+   /usage-examples/updateOne
\ No newline at end of file
diff --git a/docs/usage-examples/updateOne.txt b/docs/usage-examples/updateOne.txt
new file mode 100644
index 000000000..f60bd3bad
--- /dev/null
+++ b/docs/usage-examples/updateOne.txt
@@ -0,0 +1,67 @@
+.. _laravel-update-one-usage:
+
+=================
+Update a Document
+=================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: update one, modify, code example
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+You can update a document in a collection by retrieving a single document and calling
+the ``update()`` method on an Eloquent model or a query builder.
+
+Pass a query filter to the ``where()`` method, sort the matching documents, and call the
+``first()`` method to retrieve only the first document. Then, update this matching document
+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 a document from the ``movies`` collection that matches a query filter.
+
+The example calls the following methods on the ``Movie`` model:
+
+- ``where()``: matches documents in which the value of the ``title`` field is ``'Carol'``.
+- ``orderBy()``: sorts matched documents by their ascending ``_id`` values.
+- ``first()``: retrieves only the first matching document.
+- ``update()``: updates the value of the ``imdb.rating`` nested field to from ``6.9`` to
+  ``7.3``. This method also updates the ``imdb.votes`` nested field from ``493`` to ``142000``.
+
+.. io-code-block::
+   :copyable: true
+
+   .. input:: ../includes/usage-examples/UpdateOneTest.php
+      :start-after: begin-update-one
+      :end-before: end-update-one
+      :language: php
+      :dedent:
+
+   .. output::
+      :language: console
+      :visible: false
+
+      Updated documents: 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 updating data with {+odm-short+}, see the `Updates
+   <https://laravel.com/docs/{+laravel-docs-version+}/eloquent#updates>`__ section of the
+   Laravel documentation.
+