Database Transaction Feature

docs/transaction.md

@@ -0,0 +1,68 @@
+# Transaction
+
+**Transaction** class has three properties:
+
+1. `queries`
+2. `queryResultCollection`
+3. `connection`
+
+The <b>Transaction</b> class contains several methods such as :
+
+- `addQuery`
+- `resolveQueries`
+- `compile`
+
+### __constructor
+
+when we create an instance of this class it reserves a database connection using `reserveConnection` method and stores it
+in `connection` property, to use it
+for all transaction queries.
+
+### addQuery
+
+This method takes three arguments :
+
+1. `name`<small>(string)</small>.
+2. `query`<small>(Select|Update|Delete|Insert)</small>.
+3. `callback`<small>(Closure)</small> by default its null.
+
+This method push arguments as an array to **queries** property
+
+**Returns: `Transaction`**
+
+### resolveQueries
+
+this method doesn't take any argument.
+
+This method flow:
+
+- if `queries` is empty, it commits the transaction and return a promise with result of last query.
+- if `queries` is not empty, it shifts the first item of this property and stores it in a variable.
+- we get the query string of the selected query and send a query to database with this query and by using the reserved
+  connection.
+- if the result of query returned `false` we `rollback` the transaction and return a reject promise with
+  `TransactionException` exception.
+- otherwise if selected query has callback, we call and check the callback to be true (we inject two argument to this
+  callback, first the current query result and next the collection of all transaction query results).
+- it the callback is null, or it returns true we call the current method , and it starts from first flow.
+
+**Returns: `Promise`**
+
+### compile
+
+This method doesn't take any argument.
+
+This method flow:
+
+- if `queries` is empty, it throws `TransactionException('There are no queries inside transaction.')`.
+- it starts the transaction.
+- if transaction started, it calls the `resolveQueries` method, otherwise it release the reserved connection.
+
+**Returns: `Promise`**
+
+
+
+
+
+
+

example/transaction.php

@@ -0,0 +1,105 @@
+<?php
+
+use Dotenv\Dotenv;
+use React\EventLoop\Loop;
+use Saraf\QB\QueryBuilder\Contracts\QueryResultCollectionContract;
+use Saraf\QB\QueryBuilder\Core\DBFactory;
+use Saraf\QB\QueryBuilder\Exceptions\DBFactoryException;
+use Saraf\QB\QueryBuilder\Helpers\QueryResult\QueryResult;
+
+include "vendor/autoload.php";
+
+// Loop
+$loop = Loop::get();
+
+// Environments
+$env = Dotenv::createImmutable(__DIR__ . "/../");
+$env->load();
+
+// Env Loader
+$DB_NAME = $_ENV['DB_NAME'];
+$DB_USER = $_ENV['DB_USER'];
+$DB_PASS = $_ENV['DB_PASS'];
+$DB_HOST = $_ENV['DB_HOST'];
+$DB_PORT_READ = $_ENV['DB_PORT_READ'];
+$DB_PORT_WRITE = $_ENV['DB_PORT_WRITE'];
+
+
+try {
+    $dbFactory = new DBFactory(
+        $loop,
+        $DB_HOST,
+        $DB_NAME,
+        $DB_USER,
+        $DB_PASS,
+        $DB_PORT_WRITE,
+        $DB_PORT_READ,
+        5,
+        5,
+        2,
+        2
+    );
+} catch (DBFactoryException $e) {
+    echo $e->getMessage();
+    exit(1);
+}
+
+$tr = $dbFactory->getQueryBuilder()->beginTransaction();
+$tr->addQuery(
+    'selectUser',
+    $dbFactory->getQueryBuilder()
+        ->select()
+        ->from("Users")
+        ->where('id', 1),
+    function (QueryResult $result) {
+        if ($result->count == 0) {
+            return false;
+        }
+        return true;
+    }
+);
+$tr->addQuery('selectBalance',
+    $dbFactory->getQueryBuilder()
+        ->select()
+        ->from('Balances')
+        ->where('userId', 1)
+        ->where('symbol', 'IRT')
+);
+
+$tr->addQuery('insertTransactions',
+    $dbFactory->getQueryBuilder()
+        ->insert()
+        ->into('Transactions')
+        ->setColumns([
+            'userId',
+            'type',
+            'amount'
+        ])
+        ->addRow([
+            1,
+            'WITHDRAW',
+            100_000
+        ]),
+    function (QueryResult $result, QueryResultCollectionContract $contract) {
+        if ($contract->get('selectBalance')->rows[0]['balance'] < 100_000) {
+            return false;
+        }
+
+        return true;
+    }
+);
+
+$tr->addQuery('updateBalance',
+    $dbFactory->getQueryBuilder()
+        ->update()
+        ->table('Balances')
+        ->setUpdate('balance', 'balance - ' . 100_000, false)
+        ->where('userId', 1)
+        ->where('symbol', 'IRT')
+);
+
+$tr->compile()->then(function ($result) {
+    var_dump($result);
+})->catch(function (\Throwable $throwable) {
+    var_dump($throwable->getMessage());
+});

src/QueryBuilder/Clauses/Transaction.php

@@ -0,0 +1,91 @@
+<?php
+
+namespace Saraf\QB\QueryBuilder\Clauses;
+
+use Saraf\QB\QueryBuilder\Core\DBFactory;
+use Saraf\QB\QueryBuilder\Core\DBWorker;
+use Saraf\QB\QueryBuilder\Exceptions\TransactionException;
+use Saraf\QB\QueryBuilder\Helpers\QueryResult\QueryResult;
+use Saraf\QB\QueryBuilder\Helpers\QueryResult\QueryResultCollection;
+use function React\Promise\reject;
+use function React\Promise\resolve;
+
+class Transaction
+{
+    protected array $queries = [];
+    protected QueryResultCollection $queryResultCollection;
+    private ?DBWorker $connection = null;
+
+    public function __construct(
+        protected ?DBFactory $dbFactory = null,
+    )
+    {
+        $this->queryResultCollection = new QueryResultCollection();
+        $this->connection = !is_null($this->dbFactory) ? $this->dbFactory->reserveConnection() : null;
+    }
+
+    public function addQuery(string $name, Select|Update|Delete|Insert $query, ?\Closure $callback = null): static
+    {
+        $this->queries[] = compact('name', 'query', 'callback');
+        return $this;
+    }
+
+    /**
+     * @throws TransactionException
+     */
+    public function compile(): \React\Promise\PromiseInterface
+    {
+        if (count($this->queries) === 0) {
+            throw new TransactionException('There are no queries inside transaction.');
+        }
+
+        return $this->connection->query("START TRANSACTION")
+            ->then(function () {
+                return $this->resolveQueries();
+            })
+            ->finally(function () {
+                $this->dbFactory->releaseConnection($this->connection);
+            });
+    }
+
+    protected function resolveQueries(): \React\Promise\PromiseInterface
+    {
+        if (count($this->queries) === 0) {
+            $this->connection->query('COMMIT');
+            return resolve($this->queryResultCollection->last()->toArray());
+        }
+
+        $queryItem = array_shift($this->queries);
+
+        $query = $queryItem['query'];
+        $callback = $queryItem['callback'];
+        $name = $queryItem['name'];
+
+        return $query->compile()->getQuery()->then(function ($result) use ($query, $callback, $name) {
+            $queryString = $result['query'];
+            return $this->connection->query($queryString)
+                ->then(function ($result) use ($query, $callback, $name, $queryString) {
+                    if (!$result['result']) {
+                        $this->connection->query('ROLLBACK');
+                        return reject(throw new TransactionException('Transaction rolled back due to ' . $result['error']));
+                    }
+
+                    $queryResult = new QueryResult(
+                        $result['result'],
+                        @$result['count'] ?? null,
+                        @$result['rows'] ?? [],
+                        @$result['affectedRows'] ?? null,
+                        @$result['insertId'] ?? null,
+                    );
+
+                    if (is_null($callback) || $callback($queryResult, $this->queryResultCollection)) {
+                        $this->queryResultCollection->add($name, $queryResult);
+                        return $this->resolveQueries();
+                    }
+
+                    $this->connection->query('ROLLBACK');
+                    return reject(throw new TransactionException("Transaction rolled back,callback for query {$queryString} doesn't return true"));
+                });
+        });
+    }
+}

src/QueryBuilder/Contracts/QueryResultCollectionContract.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Saraf\QB\QueryBuilder\Contracts;
+
+use Saraf\QB\QueryBuilder\Helpers\QueryResult\QueryResult;
+
+interface QueryResultCollectionContract
+{
+    public function add(string $name, QueryResult $queryResult): self;
+    public function get(string $name): QueryResult;
+}

src/QueryBuilder/Core/DBFactory.php

@@ -12,6 +12,8 @@
 
 class DBFactory
 {
+    use ReservableConnection;
+
     private array $logs = [];
     private const MAX_CONNECTION_COUNT = 1000000000;
 

src/QueryBuilder/Core/ReservableConnection.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Saraf\QB\QueryBuilder\Core;
+
+trait ReservableConnection
+{
+    public function reserveConnection(): DBWorker
+    {
+        return array_pop($this->writeConnections);
+    }
+
+    public function releaseConnection(DBWorker $connection): void
+    {
+        $this->writeConnections[] = $connection;
+    }
+}

src/QueryBuilder/Exceptions/QueryResultException.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Saraf\QB\QueryBuilder\Exceptions;
+
+class QueryResultException extends \Exception
+{
+
+}

src/QueryBuilder/Exceptions/TransactionException.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Saraf\QB\QueryBuilder\Exceptions;
+
+class TransactionException extends \Exception
+{
+
+}

src/QueryBuilder/Helpers/QueryResult/QueryResult.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace Saraf\QB\QueryBuilder\Helpers\QueryResult;
+
+class QueryResult
+{
+    public function __construct(
+        public bool  $result,
+        public ?int  $count = null,
+        public array $rows = [],
+        public ?int  $affectedRows = null,
+        public ?int  $insertId = null
+    )
+    {
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'result' => $this->result,
+            'count' => $this->count,
+            'rows' => $this->rows,
+            'affectedRows' => $this->affectedRows,
+            'insertId' => $this->insertId
+        ];
+    }
+}