Transaction Manager Common Transactions Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require aeatech/transaction-manager-common-transactions
   

   Ensure your project uses Laravel 8+ (or compatible) and PHP 8.0+.

2. Basic Usage Import the transaction classes in your service or repository:

   use AEATech\TransactionManager\CommonTransactions\Transaction\BaseTransaction;
   use AEATech\TransactionManager\CommonTransactions\Transaction\TransactionBuilder;
   

3. First Use Case: Simple Transaction

   $transaction = TransactionBuilder::create()
       ->addQuery('INSERT INTO users (name, email) VALUES (?, ?)', ['John Doe', 'john@example.com'])
       ->addQuery('UPDATE accounts SET balance = balance - 100 WHERE user_id = ?', [1])
       ->build();
   
   $result = $transaction->execute($connection);
   

Where to Look First

• TransactionBuilder: Core class for constructing transactions.
• BaseTransaction: Abstract class defining the transaction interface.
• TransactionResult: Class for handling execution outcomes (success/failure).

Implementation Patterns

Workflow: Transaction Construction

1. Query Chaining Use addQuery() to chain SQL operations atomically:

   $transaction = TransactionBuilder::create()
       ->addQuery('BEGIN TRANSACTION;')
       ->addQuery('INSERT INTO orders (user_id, amount) VALUES (?, ?)', [$userId, $amount])
       ->addQuery('UPDATE users SET balance = balance - ? WHERE id = ?', [$amount, $userId])
       ->addQuery('COMMIT;')
       ->build();
   

2. Parameterized Queries Always use placeholders (?) for security:

   $transaction->addQuery('DELETE FROM temp_data WHERE created_at < ?', [$cutoffDate]);
   

Integration Tips

• Laravel Eloquent Integration Use DB::transaction() as a wrapper:

  DB::transaction(function () use ($transaction) {
      $transaction->execute($this->connection);
  });
  

• Custom Dialect Support Extend BaseTransaction for dialect-specific syntax (e.g., BEGIN TRANSACTION vs. START TRANSACTION):

  class MySQLTransaction extends BaseTransaction {
      public function getStartQuery(): string {
          return 'START TRANSACTION';
      }
  }
  

• Error Handling Catch TransactionException for rollback logic:

  try {
      $transaction->execute($connection);
  } catch (TransactionException $e) {
      Log::error('Transaction failed: ' . $e->getMessage());
      // Retry or notify admin
  }
  

Gotchas and Tips

Pitfalls

1. Connection Leaks Ensure transactions are always committed/rolled back:

   // ❌ Avoid implicit commits (e.g., via Eloquent outside transaction)
   User::create(['name' => 'Test']); // May commit early!
   

2. Nested Transactions This package does not support nested transactions by default. Use a dialect-specific adapter (e.g., pdo_mysql) if needed.

3. Parameter Binding Incorrect binding (e.g., mixing ? with named placeholders) may cause SQL errors:

   // ❌ Fails if dialect expects `?` placeholders
   $transaction->addQuery('SELECT * FROM users WHERE id = :id', ['id' => 1]);
   

Debugging

• Log Queries Enable Laravel’s query logging to inspect transaction SQL:

  DB::enableQueryLog();
  $transaction->execute($connection);
  dd(DB::getQueryLog());
  

• Check Transaction Status Implement a isActive() method in your dialect class to verify transaction state.

Extension Points

1. Custom Transaction Classes Extend BaseTransaction to add pre/post-execution hooks:

   class AuditTransaction extends BaseTransaction {
       public function execute(Connection $connection) {
           $this->logStart($connection);
           parent::execute($connection);
           $this->logEnd($connection);
       }
   }
   

2. Dialect-Specific Adapters Override getStartQuery(), getCommitQuery(), and getRollbackQuery() for non-standard SQL dialects.

3. Retry Logic Add a retry() method to handle transient failures:

   public function execute(Connection $connection, int $retries = 3) {
       try {
           parent::execute($connection);
       } catch (Exception $e) {
           if ($retries > 0) {
               sleep(1);
               $this->execute($connection, $retries - 1);
           }
           throw $e;
       }
   }
   

Configuration Quirks

• Default Isolation Levels The package does not enforce isolation levels. Configure via your DB connection:

  'default' => [
      'driver' => 'mysql',
      'transactions' => [
          'isolation_level' => 'serializable',
      ],
  ],