Transactions

.github/workflows/build-ci.yml

@@ -36,18 +36,14 @@ jobs:
             matrix:
                 include:
                     - { os: ubuntu-latest, php: 8.0, mongodb: '4.0', experimental: false }
-                    - { os: ubuntu-latest, php: 8.0, mongodb: 4.2, experimental: false }
-                    - { os: ubuntu-latest, php: 8.0, mongodb: 4.4, experimental: false }
+                    - { os: ubuntu-latest, php: 8.0, mongodb: '4.2', experimental: false }
+                    - { os: ubuntu-latest, php: 8.0, mongodb: '4.4', experimental: false }
                     - { os: ubuntu-latest, php: 8.0, mongodb: '5.0', experimental: false }
                     - { os: ubuntu-latest, php: 8.1, mongodb: '4.0', experimental: false }
-                    - { os: ubuntu-latest, php: 8.1, mongodb: 4.2, experimental: false }
-                    - { os: ubuntu-latest, php: 8.1, mongodb: 4.4, experimental: false }
+                    - { os: ubuntu-latest, php: 8.1, mongodb: '4.2', experimental: false }
+                    - { os: ubuntu-latest, php: 8.1, mongodb: '4.4', experimental: false }
                     - { os: ubuntu-latest, php: 8.1, mongodb: '5.0', experimental: false }
         services:
-            mongo:
-                image: mongo:${{ matrix.mongodb }}
-                ports:
-                    - 27017:27017
             mysql:
                 image: mysql:5.7
                 ports:
@@ -59,6 +55,15 @@ jobs:
 
         steps:
             -   uses: actions/checkout@v2
+            -   name: Creating MongoDB replica
+                run: |
+                    docker run --name mongodb -p 27017:27017 -e MONGO_INITDB_DATABASE=unittest --detach mongo:${{ matrix.mongodb }} mongod --replSet rs
+                    until docker exec --tty mongodb mongo 127.0.0.1:27017 --eval "db.serverStatus()"; do
+                    sleep 1
+                    done
+                    sudo docker exec --tty mongodb mongo 127.0.0.1:27017 --eval "rs.initiate({\"_id\":\"rs\",\"members\":[{\"_id\":0,\"host\":\"127.0.0.1:27017\" }]})"
+                env:
+                    MONGO_HOST: 0.0.0.0
             -   name: "Installing php"
                 uses: shivammathur/setup-php@v2
                 with:
@@ -88,6 +93,7 @@ jobs:
                 run: |
                     ./vendor/bin/phpunit --coverage-clover coverage.xml
                 env:
+                    MONGO_VERSION: ${{ matrix.mongodb }})
                     MONGO_HOST: 0.0.0.0
                     MYSQL_HOST: 0.0.0.0
                     MYSQL_PORT: 3307

README.md

@@ -37,6 +37,7 @@ This package adds functionalities to the Eloquent model and Query builder for Mo
   - [Query Builder](#query-builder)
     - [Basic Usage](#basic-usage-2)
     - [Available operations](#available-operations)
+  - [Transaction](#transaction)
   - [Schema](#schema)
     - [Basic Usage](#basic-usage-3)
     - [Geospatial indexes](#geospatial-indexes)
@@ -979,6 +980,46 @@ If you are familiar with [Eloquent Queries](http://laravel.com/docs/queries), th
 ### Available operations
 To see the available operations, check the [Eloquent](#eloquent) section.
 
+Transaction
+-------
+Transaction requires MongoDB version ^4.0 as well as deployment of replica set or sharded clusters. You can find more information [in the MongoDB docs](https://docs.mongodb.com/manual/core/transactions/)
+
+### Basic Usage
+
+Transaction supports all operations.
+
+```php
+DB::transaction(function () {
+    User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => '[email protected]']);
+    DB::collection('users')->where('name', 'john')->update(['age' => 20]);
+    DB::collection('users')->where('name', 'john')->delete();
+});
+```
+
+```php
+// begin a transaction
+DB::beginTransaction();
+User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => '[email protected]']);
+DB::collection('users')->where('name', 'john')->update(['age' => 20]);
+DB::collection('users')->where('name', 'john')->delete();
+
+// you can commit your changes
+DB::commit();
+
+// you can also rollback them
+//DB::rollBack();
+```
+**NOTE:** The Transactions in MongoDb does not support nested transactions. 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 [Transactions and Sessions](https://www.mongodb.com/docs/manual/core/transactions/#transactions-and-sessions)
+```php
+// This code will rise RuntimeException
+DB::beginTransaction();
+    User::create(['name' => 'john', 'age' => 20, 'title' => 'admin']);
+    DB::beginTransaction()
+        DB::collection('users')->where('name', 'john')->update(['age' => 20]);
+    DB::commit()
+DB::rollBack();
+```
+
 Schema
 ------
 The database driver also has (limited) schema builder support. You can easily manipulate collections and set indexes.

docker-compose.yml

@@ -10,12 +10,16 @@ services:
             - .:/code
         working_dir: /code
         depends_on:
-          - mongodb
-          - mysql
+            - mongodb
+            - mongo_repl_init
+            - mysql
+        stdin_open: true
+        tty: true
 
     mysql:
         container_name: mysql
         image: mysql:5.7
+        platform: "linux/amd64"
         ports:
             - 3306:3306
         environment:
@@ -27,8 +31,18 @@ services:
 
     mongodb:
         container_name: mongodb
-        image: mongo
+        image: mongo:6.0
         ports:
-            - 27017:27017
-        logging:
-            driver: none
+            - "27017:27017"
+        entrypoint: [ "/usr/bin/mongod", "--quiet", "--bind_ip_all", "--replSet", "rs" ]
+
+    mongo_repl_init:
+        image: mongo:6.0
+        depends_on:
+            - mongodb
+        environment:
+            - MONGO=mongodb
+            - RS=rs
+        volumes:
+            - ./:/scripts
+        entrypoint: [ "sh", "-c", "./scripts/mongo-replset-init.sh" ]

mongo-replset-init.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+mongodbHost="${MONGO}"
+rs=${RS}
+port=${PORT:-27017}
+
+echo "Waiting for startup.."
+until mongo --host ${mongodbHost}:${port} --eval 'quit(db.runCommand({ ping: 1 }).ok ? 0 : 2)' &>/dev/null; do
+  printf '.'
+  sleep 1
+done
+
+echo "Started.."
+
+echo setup.sh time now: `date +"%T" `
+mongosh --host ${mongodbHost}:${port} <<EOF
+   var cfg = {
+        "_id": ${rs},
+        "protocolVersion": 1,
+        "members": [
+            {
+                "_id": 0,
+                "host": "${mongodbHost}:${port}"
+            },
+        ]
+    };
+    rs.initiate(cfg, { force: true });
+EOF

phpunit.xml.dist

@@ -19,6 +19,9 @@
             <file>tests/QueryBuilderTest.php</file>
             <file>tests/QueryTest.php</file>
         </testsuite>
+        <testsuite name="transaction">
+            <file>tests/TransactionTest.php</file>
+        </testsuite>
         <testsuite name="model">
             <file>tests/ModelTest.php</file>
             <file>tests/RelationsTest.php</file>
@@ -35,7 +38,7 @@
         </testsuite>
     </testsuites>
     <php>
-        <env name="MONGO_HOST" value="mongodb"/>
+        <env name="MONGO_HOST" value="localhost"/>
         <env name="MONGO_DATABASE" value="unittest"/>
         <env name="MONGO_PORT" value="27017"/>
         <env name="MYSQL_HOST" value="mysql"/>

src/Concerns/TransactionManager.php

@@ -0,0 +1,104 @@
+<?php
+
+namespace Jenssegers\Mongodb\Concerns;
+
+use Closure;
+use MongoDB\Driver\Exception\RuntimeException;
+use MongoDB\Driver\Session;
+use function MongoDB\with_transaction;
+
+trait TransactionManager
+{
+    /**
+     * A list of transaction session.
+     */
+    protected ?Session $session = null;
+
+    /**
+     * Get the existing session or null.
+     */
+    public function getSession(): ?Session
+    {
+        return $this->session;
+    }
+
+    private function getSessionOrThrow(): Session
+    {
+        $session = $this->getSession();
+
+        if ($session === null) {
+            throw new RuntimeException('There is no active session.');
+        }
+
+        return $session;
+    }
+
+    /**
+     * Use the existing or create new session and start a transaction in session.
+     *
+     * In version 4.0, MongoDB supports multi-document transactions on replica sets.
+     * In version 4.2, MongoDB introduces distributed transactions, which adds support for multi-document transactions on sharded clusters and incorporates the existing support for multi-document transactions on replica sets.
+     *
+     * @see https://docs.mongodb.com/manual/core/transactions/
+     */
+    public function beginTransaction(array $options = []): void
+    {
+        $session = $this->getSession();
+
+        if ($session === null) {
+            $session = $this->connection->startSession();
+            $this->session = $session;
+        }
+
+        $session->startTransaction($options);
+    }
+
+    /**
+     * Commit transaction in this session and close this session.
+     */
+    public function commit(): void
+    {
+        $this->getSessionOrThrow()->commitTransaction();
+    }
+
+    /**
+     * Rollback transaction in this session and close this session.
+     */
+    public function rollBack($toLevel = null): void
+    {
+        $this->getSessionOrThrow()->abortTransaction();
+    }
+
+    /**
+     * Static transaction function realize the with_transaction functionality provided by MongoDB.
+     *
+     * @param int $attempts
+     */
+    public function transaction(Closure $callback, $attempts = 1, array $options = []): mixed
+    {
+        $attemptsLeft = $attempts;
+        $callbackResult = null;
+        $session = $this->getSession();
+
+        if ($session === null) {
+            $session = $this->connection->startSession();
+            $this->session = $session;
+        }
+
+        $callbackFunction = function (Session $session) use ($callback, &$attemptsLeft, &$callbackResult) {
+            $attemptsLeft--;
+
+            if ($attemptsLeft < 0) {
+                $session->abortTransaction();
+
+                return;
+            }
+
+            $callbackResult = $callback();
+        };
+
+        with_transaction($session, $callbackFunction, $options);
+
+        return $callbackResult;
+    }
+}