DOCSP-50607: multiply/divide QB methods (#3403)

* DOCSP-50607: multiply/divide QB methods

* separate mul & div examples

* add versioning

* wip

Author: rustagir

docs/eloquent-models/schema-builder.txt

@@ -117,9 +117,9 @@ in the Laravel documentation.
 Implement Schema Validation
 ---------------------------
 
-You can use the ``jsonSchema()`` method to implement :manual:`schema
-validation </core/schema-validation/>` when using the following schema
-builder methods:
+Starting in {+odm-short+} v5.5, you can use the ``jsonSchema()`` method
+to implement :manual:`schema validation </core/schema-validation/>` when
+using the following schema builder methods:
 
 - ``Schema::create()``: When creating a new collection
 - ``Schema::table()``: When updating collection properties

docs/includes/query-builder/QueryBuilderTest.php

@@ -213,10 +213,10 @@ public function testGroupBy(): void
     {
         // begin query groupBy
         $result = DB::table('movies')
-           ->where('rated', 'G')
-           ->groupBy('runtime')
-           ->orderBy('runtime', 'asc')
-           ->get(['title']);
+            ->where('rated', 'G')
+            ->groupBy('runtime')
+            ->orderBy('runtime', 'asc')
+            ->get(['title']);
         // end query groupBy
 
         $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result);
@@ -420,10 +420,10 @@ public function testWhereRaw(): void
         // begin query raw
         $result = DB::table('movies')
             ->whereRaw([
-                'imdb.votes' => ['$gte' => 1000 ],
+                'imdb.votes' => ['$gte' => 1000],
                 '$or' => [
                     ['imdb.rating' => ['$gt' => 7]],
-                    ['directors' => ['$in' => [ 'Yasujiro Ozu', 'Sofia Coppola', 'Federico Fellini' ]]],
+                    ['directors' => ['$in' => ['Yasujiro Ozu', 'Sofia Coppola', 'Federico Fellini']]],
                 ],
             ])->get();
         // end query raw
@@ -470,7 +470,7 @@ public function testNear(): void
     {
         $this->importTheaters();
 
-       // begin query near
+        // begin query near
         $results = DB::table('theaters')
             ->where('location.geo', 'near', [
                 '$geometry' => [
@@ -588,7 +588,7 @@ public function testUpdateUpsert(): void
                 [
                     'plot' => 'An autobiographical movie',
                     'year' => 1998,
-                    'writers' => [ 'Will Hunting' ],
+                    'writers' => ['Will Hunting'],
                 ],
                 ['upsert' => true],
             );
@@ -597,6 +597,29 @@ public function testUpdateUpsert(): void
         $this->assertIsInt($result);
     }
 
+    public function testMultiplyDivide(): void
+    {
+        // begin multiply divide
+        $result = DB::table('movies')
+            ->where('year', 2001)
+            ->multiply('imdb.votes', 5);
+
+        $result = DB::table('movies')
+            ->where('year', 2001)
+            ->divide('runtime', 2);
+        // end multiply divide
+
+        $this->assertIsInt($result);
+
+        // begin multiply with set
+        $result = DB::table('movies')
+            ->where('year', 1958)
+            ->multiply('runtime', 1.5, ['note' => 'Adds recovered footage.']);
+        // end multiply with set
+
+        $this->assertIsInt($result);
+    }
+
     public function testIncrement(): void
     {
         // begin increment

docs/query-builder.txt

@@ -1169,6 +1169,7 @@ This section includes query builder examples that show how to use the
 following MongoDB-specific write operations:
 
 - :ref:`Upsert a document <laravel-mongodb-query-builder-upsert>`
+- :ref:`Multiply and divide values <laravel-mongodb-query-builder-mul-div>`
 - :ref:`Increment a numerical value <laravel-mongodb-query-builder-increment>`
 - :ref:`Decrement a numerical value <laravel-mongodb-query-builder-decrement>`
 - :ref:`Add an array element <laravel-mongodb-query-builder-push>`
@@ -1252,6 +1253,41 @@ and the ``title`` field and value specified in the ``where()`` query operation:
 The ``update()`` query builder method returns the number of documents that the
 operation updated or inserted.
 
+.. _laravel-mongodb-query-builder-mul-div:
+
+Multiply and Divide Numerical Values Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Starting in {+odm-short+} v5.5, you can perform multiplication and
+division operations on numerical values by using the ``multiply()`` and
+``divide()`` query builder methods.
+
+The following example shows how to use the ``multiply()`` and
+``divide()`` methods to manipulate the values of the
+``imdb.votes`` and ``runtime`` fields:
+
+.. literalinclude:: /includes/query-builder/QueryBuilderTest.php
+   :language: php
+   :dedent:
+   :start-after: begin multiply divide
+   :end-before: end multiply divide
+
+.. tip:: update() Method
+
+   You can perform the same operations by using the ``update()``
+   method and passing an update document that includes the :manual:`$mul
+   </reference/operator/update/mul/>` operator. To learn more about
+   ``update()``, see the :ref:`laravel-fundamentals-write-modify` guide.
+
+You can optionally pass an array parameter to perform a ``$set`` update
+in the same operation, as shown in the following example:
+
+.. literalinclude:: /includes/query-builder/QueryBuilderTest.php
+   :language: php
+   :dedent:
+   :start-after: begin multiply with set
+   :end-before: end multiply with set
+
 .. _laravel-mongodb-query-builder-increment:
 
 Increment a Numerical Value Example