DOCSP-35975: Update many usage example

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(['$set' => ['acclaimed' => true]]);
+
+        echo 'Updated documents: ' . $updates;
+        // end-update-many
+
+        $this->assertEquals(2, $updates);
+        $this->expectOutputString('Updated documents: 2');
+    }
+}

docs/usage-examples.txt

@@ -73,4 +73,5 @@ calls the controller function and returns the result to a web interface.
 
    /usage-examples/findOne
    /usage-examples/updateOne
+   /usage-examples/updateMany
    /usage-examples/deleteOne

docs/usage-examples/updateMany.txt

@@ -0,0 +1,66 @@
+.. _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 an Eloquent model or 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
+
+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``
+
+.. 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 `Updates
+   <https://laravel.com/docs/{+laravel-docs-version+}/eloquent#updates>`__ section of the
+   Laravel documentation.
+