From f45455b66f0b5808801e15b0d606d51ba34ba0d5 Mon Sep 17 00:00:00 2001
From: Chris Cho <chris.cho@mongodb.com>
Date: Wed, 10 Apr 2024 11:57:22 -0400
Subject: [PATCH 01/15] DOCSP-35968: Transactions docs

---
 .../fundamentals/transactions/Account.php     |  13 ++
 .../transactions/TransactionsTest.php         | 147 ++++++++++++++++
 docs/transactions.txt                         | 159 +++++++++++++-----
 3 files changed, 275 insertions(+), 44 deletions(-)
 create mode 100644 docs/includes/fundamentals/transactions/Account.php
 create mode 100644 docs/includes/fundamentals/transactions/TransactionsTest.php

diff --git a/docs/includes/fundamentals/transactions/Account.php b/docs/includes/fundamentals/transactions/Account.php
new file mode 100644
index 000000000..72b903a50
--- /dev/null
+++ b/docs/includes/fundamentals/transactions/Account.php
@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Models;
+
+use MongoDB\Laravel\Eloquent\Model;
+
+class Account extends Model
+{
+    protected $connection = 'mongodb';
+    protected $fillable = ['number', 'balance'];
+}
diff --git a/docs/includes/fundamentals/transactions/TransactionsTest.php b/docs/includes/fundamentals/transactions/TransactionsTest.php
new file mode 100644
index 000000000..cf8d7fbae
--- /dev/null
+++ b/docs/includes/fundamentals/transactions/TransactionsTest.php
@@ -0,0 +1,147 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers;
+
+use Exception;
+use Illuminate\Support\Facades\DB;
+use MongoDB\Laravel\Tests\TestCase;
+use App\Models\Account;
+
+class TransactionsTest extends TestCase
+{
+    /**
+     * @runInSeparateProcess
+     * @preserveGlobalState disabled
+     */
+    public function testTransactionCallback(): void
+    {
+        require_once __DIR__ . '/Account.php';
+
+        Account::truncate();
+
+        Account::insert([
+            [
+                'number' => 223344,
+                'balance' => 5000,
+            ],
+            [
+                'number' => 776655,
+                'balance' => 100,
+            ]
+        ]);
+
+        // begin transaction callback
+        DB::transaction(function() {
+            $transferAmount = 200;
+
+            $sender = Account::where('number', 223344)->first();
+            $sender->balance -= $transferAmount;
+            $sender->save();
+
+            $receiver = Account::where('number', 776655)->first();
+            $receiver->balance += $transferAmount;
+            $receiver->save();
+        });
+        // end transaction callback
+
+        $sender = Account::where('number', 223344)->first();
+        $receiver = Account::where('number', 776655)->first();
+
+        $this->assertEquals(4800, $sender->balance);
+        $this->assertEquals(300, $receiver->balance);
+    }
+
+    public function testTransactionCommit(): void
+    {
+        require_once __DIR__ . '/Account.php';
+
+        Account::truncate();
+
+        Account::insert([
+          [
+            'number' => 223344,
+            'balance' => 5000,
+          ],
+          [
+            'number' => 776655,
+            'balance' => 100,
+          ]
+        ]);
+
+        // begin transaction commit
+        DB::beginTransaction();
+        $oldAccount = Account::where('number', 223344)->first();
+
+        $newAccount = Account::where('number', 776655)->first();
+        $newAccount->balance += $oldAccount->balance;
+        $newAccount->save();
+
+        $oldAccount->delete();
+        DB::commit();
+        // end transaction commit
+
+        $acct1 = Account::where('number', 223344)->first();
+        $acct2 = Account::where('number', 776655)->first();
+
+        $this->assertNull($acct1);
+        $this->assertEquals(5100, $acct2->balance);
+    }
+
+
+    public function testTransactionRollback(): void
+    {
+        require_once __DIR__ . '/Account.php';
+
+        Account::truncate();
+        Account::insert([
+          [
+            'number' => 223344,
+            'balance' => 200,
+          ],
+          [
+            'number' => 776655,
+            'balance' => 0,
+          ],
+          [
+            'number' => 990011,
+            'balance' => 0,
+          ]
+        ]);
+
+        // begin transaction rollback
+        try {
+            DB::beginTransaction();
+
+            $sender = Account::where('number', 223344)->first();
+            $receiverA = Account::where('number', 776655)->first();
+            $receiverB = Account::where('number', 990011)->first();
+
+            $amountA = 100;
+            $amountB = 200;
+
+            $sender->balance -= $amountA;
+            $receiverA->balance += $amountA;
+
+            $sender->balance -= $amountB;
+            $receiverB->balance += $amountB;
+
+            if ($sender->balance < 0) {
+                DB::rollback();
+                echo 'Insufficient balance. Rolled back the transaction.';
+            } else {
+                DB::commit();
+            }
+        }
+        // end transaction rollback
+
+        $sender = Account::where('number', 223344)->first();
+        $receiver = Account::where('number', 776655)->first();
+
+        $this->assertEquals(280, $sender->balance);
+        $this->assertEquals(300, $receiver->balance);
+    }
+
+
+}
diff --git a/docs/transactions.txt b/docs/transactions.txt
index ee70f8c8b..3528b8f54 100644
--- a/docs/transactions.txt
+++ b/docs/transactions.txt
@@ -9,71 +9,142 @@ Transactions
    :values: tutorial
 
 .. meta::
-   :keywords: php framework, odm, code example
+   :keywords: php framework, odm, rollback, commit, callback, code example, acid, atomic, consistent, isolated, durable
 
-MongoDB transactions require the following software and topology:
+Overview
+--------
+
+In this guide, you can learn how to perform a **transaction** in MongoDB by
+using the {+odm-long+}. Transactions let you run a sequence of write operations
+that update the data only when the transaction is committed.
+
+If the transaction fails, the PHP library which manages MongoDB operations
+for {+odm-short+} discards all the data changes made within the transaction
+before they become visible. This property of transactions is called
+**atomicity**.
+
+MongoDB performs write operations on single documents atomically. If you
+need atomicity for write operations on multiple documents or need data
+consistency across multiple documents for your operations, run them in a
+multi-document transaction.
+
+Multi-document transactions are **ACID compliant** because MongoDB
+guarantees that the data involved in your transaction operations remains
+consistent, even if the driver encounters unexpected errors.
+
+Learn how to perform transactions in the following sections of this guide:
+
+- :ref:`laravel-trasnactions-requirements`
+- :ref:`laravel-transaction-callback`
+- :ref:`laravel-transaction-commit`
+- :ref:`laravel-transaction-rollback`
+
+To learn more about transactions in MongoDB, see :server:`Transactions </core/transactions/>`
+in the {+server-docs-name+}.
+
+.. _laravel-trasnactions-requirements:
+
+Requirements and Limitations
+----------------------------
+
+To perform transactions in MongoDB, you must be using the following MongoDB
+version and topology:
 
 - MongoDB version 4.0 or later
 - A replica set deployment or sharded cluster
 
-You can find more information :manual:`in the MongoDB docs </core/transactions/>`
+Specific versions of MongoDB have the following limitations:
+
+- In MongoDB versions 4.2 and earlier, write operations performed within a
+  transaction must be on collections that already exist. In MongoDB versions
+  4.4 and later, the server automatically creates collections as necessary when
+  you perform write operations in a transaction. To learn more about this
+  limitation, see :manual:`Create Collections and Indexes in a Transaction </core/transactions/#create-collections-and-indexes-in-a-transaction>`
+  in the {+server-docs-name+}.
+- MongoDB does not support nested transactions. If you attempt to start a 
+  transaction within another one, the extension raises a ``RuntimeException``.
+  To learn more about this limitation, see :manual:`Transactions and Sessions </core/transactions/#transactions-and-sessions>`
+  in the {+server-docs-name+}.
+- The {+odm-long+} does not support the database testing traits
+  ``Illuminate\Foundation\Testing\DatabaseTransactions`` and ``Illuminate\Foundation\Testing\RefreshDatabase``.
+  As a workaround, you can create migrations along with the ``Illuminate\Foundation\Testing\DatabaseMigrations``
+  trait to reset the database after each test.
+
+.. _laravel-transaction-callback:
+
+Run a Transaction in a Callback
+-------------------------------
+
+This section shows how you can run a transaction as a callback.
+
+When using this method of running a transaction, all the code in the
+callback method is run as a single transaction.
 
-.. code-block:: php
+In the following example, the transaction consists of write operations that
+transfer the funds from a bank account, represented by the ``Account`` model,
+to another account:
 
-   DB::transaction(function () {
-       User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => 'john@example.com']);
-       DB::collection('users')->where('name', 'john')->update(['age' => 20]);
-       DB::collection('users')->where('name', 'john')->delete();
-   });
+.. literalinclude:: /includes/fundamentals/transactions/TransactionsTest.php
+   :language: php
+   :dedent:
+   :start-after: begin transaction callback
+   :end-before: end transaction callback
 
-.. code-block:: php
+You can optionally pass the maximum number times to retry a failed transaction 
+as the second parameter as shown in the following code example:
 
-   // begin a transaction
-   DB::beginTransaction();
-   User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => 'john@example.com']);
-   DB::collection('users')->where('name', 'john')->update(['age' => 20]);
-   DB::collection('users')->where('name', 'john')->delete();
+.. code-block::
+   :language: php
+   :copyable: true
+   :emphasize-lines: 4
 
-   // commit changes
-   DB::commit();
+   DB::transaction(function() {
+           // transaction code
+       },
+       retries: 5,
+   );
 
-To abort a transaction, call the ``rollBack`` method at any point during the transaction:
 
-.. code-block:: php
+.. _laravel-transaction-commit:
 
-   DB::beginTransaction();
-   User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => 'john@example.com']);
+Begin and Commit a Transaction
+------------------------------
 
-   // Abort the transaction, discarding any data created as part of it
-   DB::rollBack();
+This section shows how to start and commit a transaction.
 
+To use this method of starting and committing a transaction, call the
+``DB::beginTransaction()`` to start the transaction. Then, call the
+``DB::commit()`` method to end the transaction, which applies all the updates
+performed within the transaction.
 
-.. note::
+In the following example, the balance from the first account is moved to the
+second account, after which the first account is deleted:
 
-   Transactions in MongoDB cannot be nested. DB::beginTransaction() function 
-   will start new transactions in a new created or existing session and will
-   raise the RuntimeException when transactions already exist. See more in 
-   MongoDB official docs :manual:`Transactions and Sessions </core/transactions/#transactions-and-sessions>`.
+.. literalinclude:: /includes/fundamentals/transactions/TransactionsTest.php
+   :language: php
+   :dedent:
+   :start-after: begin transaction callback
+   :end-before: end transaction callback
 
-.. code-block:: php
+.. _laravel-transaction-rollback:
 
-   DB::beginTransaction();
-   User::create(['name' => 'john', 'age' => 20, 'title' => 'admin']);
+Roll Back a Transaction
+-----------------------
 
-   // This call to start a nested transaction will raise a RuntimeException
-   DB::beginTransaction();
-   DB::collection('users')->where('name', 'john')->update(['age' => 20]);
-   DB::commit();
-   DB::rollBack();
+This section shows how to roll back a transaction. A rollback reverts all the
+write operations performed within that transaction.
 
-Database Testing
-----------------
+To perform the roll back, call the ``DB::rollback()`` function anytime before
+the transaction is committed.
 
-For testing, the traits ``Illuminate\Foundation\Testing\DatabaseTransactions``
-and ``Illuminate\Foundation\Testing\RefreshDatabase`` are not yet supported.
-Instead, create migrations and use the ``DatabaseMigrations`` trait to reset 
-the database after each test:
+In the following example, the transaction consists of write operations that
+transfer funds from one account, represented by the ``Account`` model, to
+multiple other accounts. If the sender account has insufficient funds, the
+transaction is rolled back and none of the models are updated:
 
-.. code-block:: php
+.. literalinclude:: /includes/fundamentals/transactions/TransactionsTest.php
+   :language: php
+   :dedent:
+   :start-after: begin transaction callback
+   :end-before: end transaction callback
 
-   use Illuminate\Foundation\Testing\DatabaseMigrations;

From 024cbfe556323d9659caf0ac8a50933761864ab4 Mon Sep 17 00:00:00 2001
From: ccho-mongodb <ccho-mongodb@users.noreply.github.com>
Date: Thu, 11 Apr 2024 02:24:36 +0000
Subject: [PATCH 02/15] apply phpcbf formatting

---
 .../transactions/TransactionsTest.php         | 51 +++++++++----------
 1 file changed, 24 insertions(+), 27 deletions(-)

diff --git a/docs/includes/fundamentals/transactions/TransactionsTest.php b/docs/includes/fundamentals/transactions/TransactionsTest.php
index cf8d7fbae..992758c33 100644
--- a/docs/includes/fundamentals/transactions/TransactionsTest.php
+++ b/docs/includes/fundamentals/transactions/TransactionsTest.php
@@ -4,10 +4,9 @@
 
 namespace App\Http\Controllers;
 
-use Exception;
+use App\Models\Account;
 use Illuminate\Support\Facades\DB;
 use MongoDB\Laravel\Tests\TestCase;
-use App\Models\Account;
 
 class TransactionsTest extends TestCase
 {
@@ -29,11 +28,11 @@ public function testTransactionCallback(): void
             [
                 'number' => 776655,
                 'balance' => 100,
-            ]
+            ],
         ]);
 
         // begin transaction callback
-        DB::transaction(function() {
+        DB::transaction(function () {
             $transferAmount = 200;
 
             $sender = Account::where('number', 223344)->first();
@@ -60,14 +59,14 @@ public function testTransactionCommit(): void
         Account::truncate();
 
         Account::insert([
-          [
-            'number' => 223344,
-            'balance' => 5000,
-          ],
-          [
-            'number' => 776655,
-            'balance' => 100,
-          ]
+            [
+                'number' => 223344,
+                'balance' => 5000,
+            ],
+            [
+                'number' => 776655,
+                'balance' => 100,
+            ],
         ]);
 
         // begin transaction commit
@@ -89,25 +88,24 @@ public function testTransactionCommit(): void
         $this->assertEquals(5100, $acct2->balance);
     }
 
-
     public function testTransactionRollback(): void
     {
         require_once __DIR__ . '/Account.php';
 
         Account::truncate();
         Account::insert([
-          [
-            'number' => 223344,
-            'balance' => 200,
-          ],
-          [
-            'number' => 776655,
-            'balance' => 0,
-          ],
-          [
-            'number' => 990011,
-            'balance' => 0,
-          ]
+            [
+                'number' => 223344,
+                'balance' => 200,
+            ],
+            [
+                'number' => 776655,
+                'balance' => 0,
+            ],
+            [
+                'number' => 990011,
+                'balance' => 0,
+            ],
         ]);
 
         // begin transaction rollback
@@ -134,6 +132,7 @@ public function testTransactionRollback(): void
                 DB::commit();
             }
         }
+
         // end transaction rollback
 
         $sender = Account::where('number', 223344)->first();
@@ -142,6 +141,4 @@ public function testTransactionRollback(): void
         $this->assertEquals(280, $sender->balance);
         $this->assertEquals(300, $receiver->balance);
     }
-
-
 }

From d8cc216894485b951f4f1b90ee45e84a9ade796e Mon Sep 17 00:00:00 2001
From: Chris Cho <chris.cho@mongodb.com>
Date: Wed, 10 Apr 2024 22:32:44 -0400
Subject: [PATCH 03/15] add on this page, fix rst

---
 docs/transactions.txt | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/docs/transactions.txt b/docs/transactions.txt
index 3528b8f54..03be048de 100644
--- a/docs/transactions.txt
+++ b/docs/transactions.txt
@@ -11,6 +11,12 @@ Transactions
 .. meta::
    :keywords: php framework, odm, rollback, commit, callback, code example, acid, atomic, consistent, isolated, durable
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
 Overview
 --------
 
@@ -39,7 +45,7 @@ Learn how to perform transactions in the following sections of this guide:
 - :ref:`laravel-transaction-commit`
 - :ref:`laravel-transaction-rollback`
 
-To learn more about transactions in MongoDB, see :server:`Transactions </core/transactions/>`
+To learn more about transactions in MongoDB, see :manual:`Transactions </core/transactions/>`
 in the {+server-docs-name+}.
 
 .. _laravel-trasnactions-requirements:
@@ -93,9 +99,7 @@ to another account:
 You can optionally pass the maximum number times to retry a failed transaction 
 as the second parameter as shown in the following code example:
 
-.. code-block::
-   :language: php
-   :copyable: true
+.. code-block:: php
    :emphasize-lines: 4
 
    DB::transaction(function() {

From 7d7becd8781431824af48b3f619fb9cfe6f99887 Mon Sep 17 00:00:00 2001
From: Chris Cho <chris.cho@mongodb.com>
Date: Wed, 10 Apr 2024 22:35:33 -0400
Subject: [PATCH 04/15] fix test

---
 .../transactions/TransactionsTest.php         | 33 +++++++++----------
 1 file changed, 15 insertions(+), 18 deletions(-)

diff --git a/docs/includes/fundamentals/transactions/TransactionsTest.php b/docs/includes/fundamentals/transactions/TransactionsTest.php
index 992758c33..e408ec31d 100644
--- a/docs/includes/fundamentals/transactions/TransactionsTest.php
+++ b/docs/includes/fundamentals/transactions/TransactionsTest.php
@@ -109,30 +109,27 @@ public function testTransactionRollback(): void
         ]);
 
         // begin transaction rollback
-        try {
-            DB::beginTransaction();
+        DB::beginTransaction();
 
-            $sender = Account::where('number', 223344)->first();
-            $receiverA = Account::where('number', 776655)->first();
-            $receiverB = Account::where('number', 990011)->first();
+        $sender = Account::where('number', 223344)->first();
+        $receiverA = Account::where('number', 776655)->first();
+        $receiverB = Account::where('number', 990011)->first();
 
-            $amountA = 100;
-            $amountB = 200;
+        $amountA = 100;
+        $amountB = 200;
 
-            $sender->balance -= $amountA;
-            $receiverA->balance += $amountA;
+        $sender->balance -= $amountA;
+        $receiverA->balance += $amountA;
 
-            $sender->balance -= $amountB;
-            $receiverB->balance += $amountB;
+        $sender->balance -= $amountB;
+        $receiverB->balance += $amountB;
 
-            if ($sender->balance < 0) {
-                DB::rollback();
-                echo 'Insufficient balance. Rolled back the transaction.';
-            } else {
-                DB::commit();
-            }
+        if ($sender->balance < 0) {
+            DB::rollback();
+            echo 'Insufficient balance. Rolled back the transaction.';
+        } else {
+            DB::commit();
         }
-
         // end transaction rollback
 
         $sender = Account::where('number', 223344)->first();

From 24e4c90d1c566b75c8845bb5033f9d910ccc8688 Mon Sep 17 00:00:00 2001
From: Chris Cho <chris.cho@mongodb.com>
Date: Wed, 10 Apr 2024 22:37:51 -0400
Subject: [PATCH 05/15] fix tests

---
 .../fundamentals/transactions/TransactionsTest.php     | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/docs/includes/fundamentals/transactions/TransactionsTest.php b/docs/includes/fundamentals/transactions/TransactionsTest.php
index e408ec31d..a7f1c7d6d 100644
--- a/docs/includes/fundamentals/transactions/TransactionsTest.php
+++ b/docs/includes/fundamentals/transactions/TransactionsTest.php
@@ -125,17 +125,19 @@ public function testTransactionRollback(): void
         $receiverB->balance += $amountB;
 
         if ($sender->balance < 0) {
+            // insufficient balance, roll back the transaction
             DB::rollback();
-            echo 'Insufficient balance. Rolled back the transaction.';
         } else {
             DB::commit();
         }
         // end transaction rollback
 
         $sender = Account::where('number', 223344)->first();
-        $receiver = Account::where('number', 776655)->first();
+        $receiverA = Account::where('number', 776655)->first();
+        $receiverB = Account::where('number', 990011)->first();
 
-        $this->assertEquals(280, $sender->balance);
-        $this->assertEquals(300, $receiver->balance);
+        $this->assertEquals(200, $sender->balance);
+        $this->assertEquals(0, $receiverA->balance);
+        $this->assertEquals(0, $receiverB->balance);
     }
 }

From 07df2ab1eb085cd02e2a2f9c676a9ef51950bfdf Mon Sep 17 00:00:00 2001
From: ccho-mongodb <ccho-mongodb@users.noreply.github.com>
Date: Thu, 11 Apr 2024 02:40:11 +0000
Subject: [PATCH 06/15] apply phpcbf formatting

---
 docs/includes/fundamentals/transactions/TransactionsTest.php | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/includes/fundamentals/transactions/TransactionsTest.php b/docs/includes/fundamentals/transactions/TransactionsTest.php
index a7f1c7d6d..9ee4f0fc9 100644
--- a/docs/includes/fundamentals/transactions/TransactionsTest.php
+++ b/docs/includes/fundamentals/transactions/TransactionsTest.php
@@ -130,6 +130,7 @@ public function testTransactionRollback(): void
         } else {
             DB::commit();
         }
+
         // end transaction rollback
 
         $sender = Account::where('number', 223344)->first();

From fc6d22f2106f56cd7893929befc773f3332a00f4 Mon Sep 17 00:00:00 2001
From: Chris Cho <chris.cho@mongodb.com>
Date: Wed, 10 Apr 2024 22:44:53 -0400
Subject: [PATCH 07/15] reference code blocks

---
 docs/transactions.txt | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/transactions.txt b/docs/transactions.txt
index 03be048de..7c64daa76 100644
--- a/docs/transactions.txt
+++ b/docs/transactions.txt
@@ -67,7 +67,7 @@ Specific versions of MongoDB have the following limitations:
   you perform write operations in a transaction. To learn more about this
   limitation, see :manual:`Create Collections and Indexes in a Transaction </core/transactions/#create-collections-and-indexes-in-a-transaction>`
   in the {+server-docs-name+}.
-- MongoDB does not support nested transactions. If you attempt to start a 
+- MongoDB does not support nested transactions. If you attempt to start a
   transaction within another one, the extension raises a ``RuntimeException``.
   To learn more about this limitation, see :manual:`Transactions and Sessions </core/transactions/#transactions-and-sessions>`
   in the {+server-docs-name+}.
@@ -96,7 +96,7 @@ to another account:
    :start-after: begin transaction callback
    :end-before: end transaction callback
 
-You can optionally pass the maximum number times to retry a failed transaction 
+You can optionally pass the maximum number times to retry a failed transaction
 as the second parameter as shown in the following code example:
 
 .. code-block:: php
@@ -127,8 +127,8 @@ second account, after which the first account is deleted:
 .. literalinclude:: /includes/fundamentals/transactions/TransactionsTest.php
    :language: php
    :dedent:
-   :start-after: begin transaction callback
-   :end-before: end transaction callback
+   :start-after: begin transaction commit
+   :end-before: end transaction commit
 
 .. _laravel-transaction-rollback:
 
@@ -149,6 +149,6 @@ transaction is rolled back and none of the models are updated:
 .. literalinclude:: /includes/fundamentals/transactions/TransactionsTest.php
    :language: php
    :dedent:
-   :start-after: begin transaction callback
-   :end-before: end transaction callback
+   :start-after: begin transaction rollback
+   :end-before: end transaction rollback
 

From ffc4e951430d41d5ba834a0c27017aea090a9774 Mon Sep 17 00:00:00 2001
From: Chris Cho <chris.cho@mongodb.com>
Date: Wed, 10 Apr 2024 22:53:25 -0400
Subject: [PATCH 08/15] fix for DOCSP-38411: compatibility ref

---
 docs/feature-compatibility.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/feature-compatibility.txt b/docs/feature-compatibility.txt
index b4f0406f3..bbb5767e1 100644
--- a/docs/feature-compatibility.txt
+++ b/docs/feature-compatibility.txt
@@ -136,7 +136,7 @@ The following Eloquent methods are not supported in {+odm-short+}:
      - *Unsupported*
 
    * - Grouping
-     - Partially supported, use :ref:`Aggregation Builders <laravel-query-builder-aggregates>`.
+     - Partially supported, use :ref:`Aggregations <laravel-query-builder-aggregations>`.
 
    * - Limit and Offset
      - ✓

From 4caeb1fdc514db28a5380740a0a4b9dc2a3996db Mon Sep 17 00:00:00 2001
From: Chris Cho <chris.cho@mongodb.com>
Date: Wed, 10 Apr 2024 23:02:25 -0400
Subject: [PATCH 09/15] change code boundary names

---
 .../fundamentals/transactions/TransactionsTest.php       | 9 ++++-----
 docs/transactions.txt                                    | 8 ++++----
 2 files changed, 8 insertions(+), 9 deletions(-)

diff --git a/docs/includes/fundamentals/transactions/TransactionsTest.php b/docs/includes/fundamentals/transactions/TransactionsTest.php
index 9ee4f0fc9..c79d03014 100644
--- a/docs/includes/fundamentals/transactions/TransactionsTest.php
+++ b/docs/includes/fundamentals/transactions/TransactionsTest.php
@@ -69,7 +69,7 @@ public function testTransactionCommit(): void
             ],
         ]);
 
-        // begin transaction commit
+        // begin commit transaction
         DB::beginTransaction();
         $oldAccount = Account::where('number', 223344)->first();
 
@@ -79,7 +79,7 @@ public function testTransactionCommit(): void
 
         $oldAccount->delete();
         DB::commit();
-        // end transaction commit
+        // end commit transaction
 
         $acct1 = Account::where('number', 223344)->first();
         $acct2 = Account::where('number', 776655)->first();
@@ -108,7 +108,7 @@ public function testTransactionRollback(): void
             ],
         ]);
 
-        // begin transaction rollback
+        // begin rollback transaction
         DB::beginTransaction();
 
         $sender = Account::where('number', 223344)->first();
@@ -130,8 +130,7 @@ public function testTransactionRollback(): void
         } else {
             DB::commit();
         }
-
-        // end transaction rollback
+        // end rollback transaction
 
         $sender = Account::where('number', 223344)->first();
         $receiverA = Account::where('number', 776655)->first();
diff --git a/docs/transactions.txt b/docs/transactions.txt
index 7c64daa76..f3facfb35 100644
--- a/docs/transactions.txt
+++ b/docs/transactions.txt
@@ -127,8 +127,8 @@ second account, after which the first account is deleted:
 .. literalinclude:: /includes/fundamentals/transactions/TransactionsTest.php
    :language: php
    :dedent:
-   :start-after: begin transaction commit
-   :end-before: end transaction commit
+   :start-after: begin commit transaction
+   :end-before: end commit transaction
 
 .. _laravel-transaction-rollback:
 
@@ -149,6 +149,6 @@ transaction is rolled back and none of the models are updated:
 .. literalinclude:: /includes/fundamentals/transactions/TransactionsTest.php
    :language: php
    :dedent:
-   :start-after: begin transaction rollback
-   :end-before: end transaction rollback
+   :start-after: begin rollback transaction
+   :end-before: end rollback transaction
 

From 6773a8215896fe4ee44b7001c53980e4f74a9c1b Mon Sep 17 00:00:00 2001
From: ccho-mongodb <ccho-mongodb@users.noreply.github.com>
Date: Thu, 11 Apr 2024 03:04:20 +0000
Subject: [PATCH 10/15] apply phpcbf formatting

---
 docs/includes/fundamentals/transactions/TransactionsTest.php | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/includes/fundamentals/transactions/TransactionsTest.php b/docs/includes/fundamentals/transactions/TransactionsTest.php
index c79d03014..ec8687992 100644
--- a/docs/includes/fundamentals/transactions/TransactionsTest.php
+++ b/docs/includes/fundamentals/transactions/TransactionsTest.php
@@ -130,6 +130,7 @@ public function testTransactionRollback(): void
         } else {
             DB::commit();
         }
+
         // end rollback transaction
 
         $sender = Account::where('number', 223344)->first();

From 98c7afe50334ff757c59fbb4952ae0eda9b1399b Mon Sep 17 00:00:00 2001
From: Chris Cho <chris.cho@mongodb.com>
Date: Wed, 10 Apr 2024 23:07:42 -0400
Subject: [PATCH 11/15] add emphasize lines

---
 docs/transactions.txt | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/transactions.txt b/docs/transactions.txt
index f3facfb35..007132ffa 100644
--- a/docs/transactions.txt
+++ b/docs/transactions.txt
@@ -127,6 +127,7 @@ second account, after which the first account is deleted:
 .. literalinclude:: /includes/fundamentals/transactions/TransactionsTest.php
    :language: php
    :dedent:
+   :emphasize-lines: 1,9
    :start-after: begin commit transaction
    :end-before: end commit transaction
 
@@ -149,6 +150,7 @@ transaction is rolled back and none of the models are updated:
 .. literalinclude:: /includes/fundamentals/transactions/TransactionsTest.php
    :language: php
    :dedent:
+   :emphasize-lines: 1,18,20
    :start-after: begin rollback transaction
    :end-before: end rollback transaction
 

From 1792004b950d224f4e96fa5aee3c2ff4f86cd830 Mon Sep 17 00:00:00 2001
From: Chris Cho <chris.cho@mongodb.com>
Date: Wed, 10 Apr 2024 23:30:35 -0400
Subject: [PATCH 12/15] updates, grammar fixes

---
 docs/transactions.txt | 41 +++++++++++++++++++++--------------------
 1 file changed, 21 insertions(+), 20 deletions(-)

diff --git a/docs/transactions.txt b/docs/transactions.txt
index 007132ffa..eba985b51 100644
--- a/docs/transactions.txt
+++ b/docs/transactions.txt
@@ -22,25 +22,26 @@ Overview
 
 In this guide, you can learn how to perform a **transaction** in MongoDB by
 using the {+odm-long+}. Transactions let you run a sequence of write operations
-that update the data only when the transaction is committed.
+that update the data only after the transaction is committed.
 
-If the transaction fails, the PHP library which manages MongoDB operations
-for {+odm-short+} discards all the data changes made within the transaction
-before they become visible. This property of transactions is called
-**atomicity**.
+If the transaction fails, the PHP library that manages MongoDB operations
+for {+odm-short+} ensures that MongoDB discards all the changes made within
+the transaction before they become visible. This property of transactions
+that ensures that all changes within a transaction are either applied or
+discarded is called **atomicity**.
 
 MongoDB performs write operations on single documents atomically. If you
-need atomicity for write operations on multiple documents or need data
-consistency across multiple documents for your operations, run them in a
-multi-document transaction.
+need atomicity in write operations on multiple documents or data consistency
+across multiple documents for your operations, run them in a multi-document
+transaction.
 
 Multi-document transactions are **ACID compliant** because MongoDB
-guarantees that the data involved in your transaction operations remains
-consistent, even if the driver encounters unexpected errors.
+guarantees that the data in your transaction operations remains consistent,
+even if the driver encounters unexpected errors.
 
 Learn how to perform transactions in the following sections of this guide:
 
-- :ref:`laravel-trasnactions-requirements`
+- :ref:`laravel-transaction-requirements`
 - :ref:`laravel-transaction-callback`
 - :ref:`laravel-transaction-commit`
 - :ref:`laravel-transaction-rollback`
@@ -48,7 +49,7 @@ Learn how to perform transactions in the following sections of this guide:
 To learn more about transactions in MongoDB, see :manual:`Transactions </core/transactions/>`
 in the {+server-docs-name+}.
 
-.. _laravel-trasnactions-requirements:
+.. _laravel-transaction-requirements:
 
 Requirements and Limitations
 ----------------------------
@@ -62,8 +63,8 @@ version and topology:
 Specific versions of MongoDB have the following limitations:
 
 - In MongoDB versions 4.2 and earlier, write operations performed within a
-  transaction must be on collections that already exist. In MongoDB versions
-  4.4 and later, the server automatically creates collections as necessary when
+  transaction must be on existing collections. In MongoDB versions 4.4 and
+  later, the server automatically creates collections as necessary when
   you perform write operations in a transaction. To learn more about this
   limitation, see :manual:`Create Collections and Indexes in a Transaction </core/transactions/#create-collections-and-indexes-in-a-transaction>`
   in the {+server-docs-name+}.
@@ -73,7 +74,7 @@ Specific versions of MongoDB have the following limitations:
   in the {+server-docs-name+}.
 - The {+odm-long+} does not support the database testing traits
   ``Illuminate\Foundation\Testing\DatabaseTransactions`` and ``Illuminate\Foundation\Testing\RefreshDatabase``.
-  As a workaround, you can create migrations along with the ``Illuminate\Foundation\Testing\DatabaseMigrations``
+  As a workaround, you can create migrations with the ``Illuminate\Foundation\Testing\DatabaseMigrations``
   trait to reset the database after each test.
 
 .. _laravel-transaction-callback:
@@ -84,7 +85,7 @@ Run a Transaction in a Callback
 This section shows how you can run a transaction as a callback.
 
 When using this method of running a transaction, all the code in the
-callback method is run as a single transaction.
+callback method runs as a single transaction.
 
 In the following example, the transaction consists of write operations that
 transfer the funds from a bank account, represented by the ``Account`` model,
@@ -96,8 +97,7 @@ to another account:
    :start-after: begin transaction callback
    :end-before: end transaction callback
 
-You can optionally pass the maximum number times to retry a failed transaction
-as the second parameter as shown in the following code example:
+You can optionally pass the maximum number of times to retry a failed transaction as the second parameter as shown in the following code example:
 
 .. code-block:: php
    :emphasize-lines: 4
@@ -137,7 +137,8 @@ Roll Back a Transaction
 -----------------------
 
 This section shows how to roll back a transaction. A rollback reverts all the
-write operations performed within that transaction.
+write operations performed within that transaction. This means that the
+data is reverted to its state before the transaction.
 
 To perform the roll back, call the ``DB::rollback()`` function anytime before
 the transaction is committed.
@@ -145,7 +146,7 @@ the transaction is committed.
 In the following example, the transaction consists of write operations that
 transfer funds from one account, represented by the ``Account`` model, to
 multiple other accounts. If the sender account has insufficient funds, the
-transaction is rolled back and none of the models are updated:
+transaction is rolled back, and none of the models are updated:
 
 .. literalinclude:: /includes/fundamentals/transactions/TransactionsTest.php
    :language: php

From 9f6dbf049e0778c7633e6ce36d9462f847cfaf59 Mon Sep 17 00:00:00 2001
From: Chris Cho <chris.cho@mongodb.com>
Date: Thu, 11 Apr 2024 09:38:48 -0400
Subject: [PATCH 13/15] list intro update

---
 docs/transactions.txt | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/docs/transactions.txt b/docs/transactions.txt
index eba985b51..93c444f27 100644
--- a/docs/transactions.txt
+++ b/docs/transactions.txt
@@ -60,7 +60,7 @@ version and topology:
 - MongoDB version 4.0 or later
 - A replica set deployment or sharded cluster
 
-Specific versions of MongoDB have the following limitations:
+MongoDB server and {+odm-short+} have the following limitations:
 
 - In MongoDB versions 4.2 and earlier, write operations performed within a
   transaction must be on existing collections. In MongoDB versions 4.4 and
@@ -108,7 +108,6 @@ You can optionally pass the maximum number of times to retry a failed transactio
        retries: 5,
    );
 
-
 .. _laravel-transaction-commit:
 
 Begin and Commit a Transaction

From c17db6f36d7b9d7dbe087c02d5843c4757af42ac Mon Sep 17 00:00:00 2001
From: Chris Cho <chris.cho@mongodb.com>
Date: Thu, 11 Apr 2024 11:05:28 -0400
Subject: [PATCH 14/15] PRR fixes

---
 docs/transactions.txt | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/docs/transactions.txt b/docs/transactions.txt
index 93c444f27..3cb3c2c5b 100644
--- a/docs/transactions.txt
+++ b/docs/transactions.txt
@@ -46,15 +46,17 @@ Learn how to perform transactions in the following sections of this guide:
 - :ref:`laravel-transaction-commit`
 - :ref:`laravel-transaction-rollback`
 
-To learn more about transactions in MongoDB, see :manual:`Transactions </core/transactions/>`
-in the {+server-docs-name+}.
+.. tip::
+
+   To learn more about transactions in MongoDB, see :manual:`Transactions </core/transactions/>`
+   in the {+server-docs-name+}.
 
 .. _laravel-transaction-requirements:
 
 Requirements and Limitations
 ----------------------------
 
-To perform transactions in MongoDB, you must be using the following MongoDB
+To perform transactions in MongoDB, you must use the following MongoDB
 version and topology:
 
 - MongoDB version 4.0 or later
@@ -82,7 +84,7 @@ MongoDB server and {+odm-short+} have the following limitations:
 Run a Transaction in a Callback
 -------------------------------
 
-This section shows how you can run a transaction as a callback.
+This section shows how you can run a transaction in a callback.
 
 When using this method of running a transaction, all the code in the
 callback method runs as a single transaction.
@@ -116,7 +118,7 @@ Begin and Commit a Transaction
 This section shows how to start and commit a transaction.
 
 To use this method of starting and committing a transaction, call the
-``DB::beginTransaction()`` to start the transaction. Then, call the
+``DB::beginTransaction()`` method to start the transaction. Then, call the
 ``DB::commit()`` method to end the transaction, which applies all the updates
 performed within the transaction.
 
@@ -139,7 +141,7 @@ This section shows how to roll back a transaction. A rollback reverts all the
 write operations performed within that transaction. This means that the
 data is reverted to its state before the transaction.
 
-To perform the roll back, call the ``DB::rollback()`` function anytime before
+To perform the rollback, call the ``DB::rollback()`` function anytime before
 the transaction is committed.
 
 In the following example, the transaction consists of write operations that

From 2adbc4bb36f4e6a2a9c93f336b5210f3148859ca Mon Sep 17 00:00:00 2001
From: Chris Cho <chris.cho@mongodb.com>
Date: Thu, 11 Apr 2024 14:33:32 -0400
Subject: [PATCH 15/15] fix elemmatch link

---
 docs/query-builder.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/query-builder.txt b/docs/query-builder.txt
index 9650df09b..5249e2911 100644
--- a/docs/query-builder.txt
+++ b/docs/query-builder.txt
@@ -878,7 +878,7 @@ specified query:
    :end-before: end query elemMatch
 
 To learn more about regular expression queries in MongoDB, see
-the :manual:`$elemMatch operator <reference/operator/query/elemMatch/>`
+the :manual:`$elemMatch operator </reference/operator/query/elemMatch/>`
 in the {+server-docs-name+}.
 
 .. _laravel-query-builder-cursor-timeout: