Add support for transactions

Co-authored-by: klinson <klinson@163.com>
Co-authored-by: levon80999 <levonb@ucraft.com>

Author: 3 people

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)
+  - [Transactions](#transactions)
   - [Schema](#schema)
     - [Basic Usage](#basic-usage-3)
     - [Geospatial indexes](#geospatial-indexes)
@@ -968,6 +969,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.
 
+Transactions
+-------
+Transactions require 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' => 'klinsonup@gmail.com']);
+    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' => 'klinsonup@gmail.com']);
+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:** 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 [Transactions and Sessions](https://www.mongodb.com/docs/manual/core/transactions/#transactions-and-sessions)
+```php
+// This code will raise a 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.

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>

src/Concerns/ManagesTransactions.php

@@ -0,0 +1,105 @@
+<?php
+
+namespace Jenssegers\Mongodb\Concerns;
+
+use Closure;
+use MongoDB\Client;
+use MongoDB\Driver\Exception\RuntimeException;
+use MongoDB\Driver\Session;
+use function MongoDB\with_transaction;
+
+trait ManagesTransactions
+{
+    protected ?Session $session = null;
+
+    /**
+     * @return Client
+     */
+    abstract public function getMongoClient();
+
+    public function getSession(): ?Session
+    {
+        return $this->session;
+    }
+
+    private function getSessionOrCreate(): Session
+    {
+        if ($this->session === null) {
+            $this->session = $this->getMongoClient()->startSession();
+        }
+
+        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
+    {
+        $this->getSessionOrCreate()->startTransaction($options);
+        $this->transactions = 1;
+    }
+
+    /**
+     * Commit transaction in this session.
+     */
+    public function commit(): void
+    {
+        $this->getSessionOrThrow()->commitTransaction();
+        $this->transactions = 0;
+    }
+
+    /**
+     * Rollback transaction in this session.
+     */
+    public function rollBack($toLevel = null): void
+    {
+        $this->getSessionOrThrow()->abortTransaction();
+        $this->transactions = 0;
+    }
+
+    /**
+     * 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->getSessionOrCreate();
+
+        $callbackFunction = function (Session $session) use ($callback, &$attemptsLeft, &$callbackResult) {
+            $attemptsLeft--;
+
+            if ($attemptsLeft < 0) {
+                $session->abortTransaction();
+
+                return;
+            }
+
+            $callbackResult = $callback();
+        };
+
+        with_transaction($session, $callbackFunction, $options);
+
+        return $callbackResult;
+    }
+}

src/Connection.php

@@ -5,10 +5,13 @@
 use Illuminate\Database\Connection as BaseConnection;
 use Illuminate\Support\Arr;
 use InvalidArgumentException;
+use Jenssegers\Mongodb\Concerns\ManagesTransactions;
 use MongoDB\Client;
 
 class Connection extends BaseConnection
 {
+    use ManagesTransactions;
+
     /**
      * The MongoDB database handler.
      *
@@ -26,7 +29,7 @@ class Connection extends BaseConnection
     /**
      * Create a new database connection instance.
      *
-     * @param array $config
+     * @param  array  $config
      */
     public function __construct(array $config)
     {
@@ -57,7 +60,7 @@ public function __construct(array $config)
     /**
      * Begin a fluent query against a database collection.
      *
-     * @param string $collection
+     * @param  string  $collection
      * @return Query\Builder
      */
     public function collection($collection)
@@ -70,8 +73,8 @@ public function collection($collection)
     /**
      * Begin a fluent query against a database collection.
      *
-     * @param string $table
-     * @param string|null $as
+     * @param  string  $table
+     * @param  string|null  $as
      * @return Query\Builder
      */
     public function table($table, $as = null)
@@ -82,7 +85,7 @@ public function table($table, $as = null)
     /**
      * Get a MongoDB collection.
      *
-     * @param string $name
+     * @param  string  $name
      * @return Collection
      */
     public function getCollection($name)
@@ -129,9 +132,10 @@ public function getDatabaseName()
     /**
      * Get the name of the default database based on db config or try to detect it from dsn.
      *
-     * @param string $dsn
-     * @param array $config
+     * @param  string  $dsn
+     * @param  array  $config
      * @return string
+     *
      * @throws InvalidArgumentException
      */
     protected function getDefaultDatabaseName($dsn, $config)
@@ -150,9 +154,9 @@ protected function getDefaultDatabaseName($dsn, $config)
     /**
      * Create a new MongoDB connection.
      *
-     * @param string $dsn
-     * @param array $config
-     * @param array $options
+     * @param  string  $dsn
+     * @param  array  $config
+     * @param  array  $options
      * @return \MongoDB\Client
      */
     protected function createConnection($dsn, array $config, array $options)
@@ -186,7 +190,7 @@ public function disconnect()
     /**
      * Determine if the given configuration array has a dsn string.
      *
-     * @param array $config
+     * @param  array  $config
      * @return bool
      */
     protected function hasDsnString(array $config)
@@ -197,7 +201,7 @@ protected function hasDsnString(array $config)
     /**
      * Get the DSN string form configuration.
      *
-     * @param array $config
+     * @param  array  $config
      * @return string
      */
     protected function getDsnString(array $config)
@@ -208,7 +212,7 @@ protected function getDsnString(array $config)
     /**
      * Get the DSN string for a host / port configuration.
      *
-     * @param array $config
+     * @param  array  $config
      * @return string
      */
     protected function getHostDsn(array $config)
@@ -232,7 +236,7 @@ protected function getHostDsn(array $config)
     /**
      * Create a DSN string from a configuration.
      *
-     * @param array $config
+     * @param  array  $config
      * @return string
      */
     protected function getDsn(array $config)
@@ -285,7 +289,7 @@ protected function getDefaultSchemaGrammar()
     /**
      * Set database.
      *
-     * @param \MongoDB\Database $db
+     * @param  \MongoDB\Database  $db
      */
     public function setDatabase(\MongoDB\Database $db)
     {
@@ -295,8 +299,8 @@ public function setDatabase(\MongoDB\Database $db)
     /**
      * Dynamically pass methods to the connection.
      *
-     * @param string $method
-     * @param array $parameters
+     * @param  string  $method
+     * @param  array  $parameters
      * @return mixed
      */
     public function __call($method, $parameters)