DOCSP-41741: incrementEach and decrementEach (#3088)

* DOCSP-41741: incrementEach and decrementEach

* clarify v4.8

* edits

Author: norareidy

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

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