From 17bc7e621bee806f57423ab93f775a26a3aa12c5 Mon Sep 17 00:00:00 2001
From: Nora Reidy <nora.reidy@mongodb.com>
Date: Mon, 12 Aug 2024 14:03:44 -0400
Subject: [PATCH] DOCSP-41741: incrementEach and decrementEach (#3088)

* DOCSP-41741: incrementEach and decrementEach

* clarify v4.8

* edits
---
 .../query-builder/QueryBuilderTest.php        | 28 +++++++++++++++
 docs/query-builder.txt                        | 34 +++++++++++++++++++
 2 files changed, 62 insertions(+)

diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php
index c6ef70592..74f576e32 100644
--- a/docs/includes/query-builder/QueryBuilderTest.php
+++ b/docs/includes/query-builder/QueryBuilderTest.php
@@ -555,6 +555,20 @@ public function testIncrement(): void
         $this->assertIsInt($result);
     }
 
+    public function testIncrementEach(): void
+    {
+        // begin increment each
+        $result = DB::table('movies')
+            ->where('title', 'Lost in Translation')
+            ->incrementEach([
+                'awards.wins' => 2,
+                'imdb.votes' => 1050,
+            ]);
+        // end increment each
+
+        $this->assertIsInt($result);
+    }
+
     public function testDecrement(): void
     {
         // begin decrement
@@ -566,6 +580,20 @@ public function testDecrement(): void
         $this->assertIsInt($result);
     }
 
+    public function testDecrementEach(): void
+    {
+        // begin decrement each
+        $result = DB::table('movies')
+            ->where('title', 'Dunkirk')
+            ->decrementEach([
+                'metacritic' => 1,
+                'imdb.rating' => 0.4,
+            ]);
+        // end decrement each
+
+        $this->assertIsInt($result);
+    }
+
     public function testPush(): void
     {
         // begin push
diff --git a/docs/query-builder.txt b/docs/query-builder.txt
index 6b84f9e78..ebe5fd727 100644
--- a/docs/query-builder.txt
+++ b/docs/query-builder.txt
@@ -1125,6 +1125,23 @@ the ``imdb.votes`` field in the matched document:
 The ``increment()`` query builder method returns the number of documents that the
 operation updated.
 
+Starting in {+odm-short+} v4.8, you can also use the ``incrementEach()`` query
+builder method to increment multiple values in a single operation. The following
+example uses the ``incrementEach()`` method to increase the values of the ``awards.wins``
+and ``imdb.votes`` fields in the matched document:
+
+.. literalinclude:: /includes/query-builder/QueryBuilderTest.php
+   :language: php
+   :dedent:
+   :start-after: begin increment each
+   :end-before: end increment each
+
+.. note::
+
+   If you pass a field to the ``increment()`` or ``incrementEach()`` method that
+   has no value or doesn't exist in the matched documents, these methods initialize
+   the specified field to the increment value.
+
 .. _laravel-mongodb-query-builder-decrement:
 
 Decrement a Numerical Value Example
@@ -1143,6 +1160,23 @@ matched document:
 The ``decrement()`` query builder method returns the number of documents that the
 operation updated.
 
+Starting in {+odm-short+} v4.8, you can also use the ``decrementEach()`` query builder
+method to decrement multiple values in a single operation. The following example uses
+the ``decrementEach()`` method to decrease the values of the ``metacritic`` and ``imdb.rating``
+fields in the matched document:
+
+.. literalinclude:: /includes/query-builder/QueryBuilderTest.php
+   :language: php
+   :dedent:
+   :start-after: begin decrement each
+   :end-before: end decrement each
+
+.. note::
+
+   If you pass a field to the ``decrement()`` or ``decrementEach()`` method that
+   has no value or doesn't exist in the matched documents, these methods initialize
+   the specified field to the decrement value.
+
 .. _laravel-mongodb-query-builder-push:
 
 Add an Array Element Example