www.aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Database/Transaction.php

   1 <?php
   2
   3 namespace Drupal\Core\Database;
   4
   5 /**
   6  * A wrapper class for creating and managing database transactions.
   7  *
   8  * Not all databases or database configurations support transactions. For
   9  * example, MySQL MyISAM tables do not. It is also easy to begin a transaction
  10  * and then forget to commit it, which can lead to connection errors when
  11  * another transaction is started.
  12  *
  13  * This class acts as a wrapper for transactions. To begin a transaction,
  14  * simply instantiate it. When the object goes out of scope and is destroyed
  15  * it will automatically commit. It also will check to see if the specified
  16  * connection supports transactions. If not, it will simply skip any transaction
  17  * commands, allowing user-space code to proceed normally. The only difference
  18  * is that rollbacks won't actually do anything.
  19  *
  20  * In the vast majority of cases, you should not instantiate this class
  21  * directly. Instead, call ->startTransaction(), from the appropriate connection
  22  * object.
  23  */
  24 class Transaction {
  25
  26   /**
  27    * The connection object for this transaction.
  28    *
  29    * @var \Drupal\Core\Database\Connection
  30    */
  31   protected $connection;
  32
  33   /**
  34    * A boolean value to indicate whether this transaction has been rolled back.
  35    *
  36    * @var bool
  37    */
  38   protected $rolledBack = FALSE;
  39
  40   /**
  41    * The name of the transaction.
  42    *
  43    * This is used to label the transaction savepoint. It will be overridden to
  44    * 'drupal_transaction' if there is no transaction depth.
  45    */
  46   protected $name;
  47
  48   public function __construct(Connection $connection, $name = NULL) {
  49     $this->connection = $connection;
  50     // If there is no transaction depth, then no transaction has started. Name
  51     // the transaction 'drupal_transaction'.
  52     if (!$depth = $connection->transactionDepth()) {
  53       $this->name = 'drupal_transaction';
  54     }
  55     // Within transactions, savepoints are used. Each savepoint requires a
  56     // name. So if no name is present we need to create one.
  57     elseif (!$name) {
  58       $this->name = 'savepoint_' . $depth;
  59     }
  60     else {
  61       $this->name = $name;
  62     }
  63     $this->connection->pushTransaction($this->name);
  64   }
  65
  66   public function __destruct() {
  67     // If we rolled back then the transaction would have already been popped.
  68     if (!$this->rolledBack) {
  69       $this->connection->popTransaction($this->name);
  70     }
  71   }
  72
  73   /**
  74    * Retrieves the name of the transaction or savepoint.
  75    */
  76   public function name() {
  77     return $this->name;
  78   }
  79
  80   /**
  81    * Rolls back the current transaction.
  82    *
  83    * This is just a wrapper method to rollback whatever transaction stack we are
  84    * currently in, which is managed by the connection object itself. Note that
  85    * logging (preferable with watchdog_exception()) needs to happen after a
  86    * transaction has been rolled back or the log messages will be rolled back
  87    * too.
  88    *
  89    * @see \Drupal\Core\Database\Connection::rollBack()
  90    * @see watchdog_exception()
  91    */
  92   public function rollBack() {
  93     $this->rolledBack = TRUE;
  94     $this->connection->rollBack($this->name);
  95   }
  96
  97 }