CRM/Core/Transaction.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   6  | This work is published under the GNU AGPLv3 license with some      |
   7  | permitted exceptions and without any warranty. For full license    |
   8  | and copyright information, see https://civicrm.org/licensing       |
   9  +--------------------------------------------------------------------+
  10  */
  11
  12 /**
  13  *
  14  * @package CRM
  15  * @copyright CiviCRM LLC https://civicrm.org/licensing
  16  * @copyright David Strauss <david@fourkitchens.com> (c) 2007
  17  * $Id$
  18  *
  19  * (Note: This has been considerably rewritten; the interface is preserved
  20  * for backward compatibility.)
  21  *
  22  * Transaction management in Civi is divided among three classes:
  23  *  - CRM_Core_Transaction: API. This binds to __construct() + __destruct()
  24  *    and notifies the transaction manager when it's OK to begin/end a transaction.
  25  *  - Civi\Core\Transaction\Manager: Tracks pending transaction-frames
  26  *  - Civi\Core\Transaction\Frame: A nestable transaction (e.g. based on BEGIN/COMMIT/ROLLBACK
  27  *    or SAVEPOINT/ROLLBACK TO SAVEPOINT).
  28  *
  29  * Examples:
  30  *
  31  * @code
  32  * // Some business logic using the helper functions
  33  * function my_business_logic() {
  34  *   CRM_Core_Transaction::create()->run(function($tx) {
  35  *     ...do work...
  36  *    if ($error) throw new Exception();
  37  *   });
  38  * }
  39  *
  40  * // Some business logic which returns an error-value
  41  * // and explicitly manages the transaction.
  42  * function my_business_logic() {
  43  *   $tx = new CRM_Core_Transaction();
  44  *   ...do work...
  45  *   if ($error) {
  46  *     $tx->rollback();
  47  *     return error_value;
  48  *   }
  49  * }
  50  *
  51  * // Some business logic which uses exceptions
  52  * // and explicitly manages the transaction.
  53  * function my_business_logic() {
  54  *   $tx = new CRM_Core_Transaction();
  55  *   try {
  56  *     ...do work...
  57  *   } catch (Exception $ex) {
  58  *     $tx->rollback()->commit();
  59  *     throw $ex;
  60  *   }
  61  * }
  62  *
  63  * @endcode
  64  *
  65  * Note: As of 4.6, the transaction manager supports both reference-counting and nested
  66  * transactions (SAVEPOINTs). In the past, it only supported reference-counting. The two cases
  67  * may exhibit different systemic effects with respect to unhandled exceptions.
  68  */
  69 class CRM_Core_Transaction {
  70
  71   /**
  72    * These constants represent phases at which callbacks can be invoked.
  73    */
  74   const PHASE_PRE_COMMIT = 1;
  75   const PHASE_POST_COMMIT = 2;
  76   const PHASE_PRE_ROLLBACK = 4;
  77   const PHASE_POST_ROLLBACK = 8;
  78
  79   /**
  80    * Whether commit() has been called on this instance
  81    * of CRM_Core_Transaction
  82    * @var bool
  83    */
  84   private $_pseudoCommitted = FALSE;
  85
  86   /**
  87    * Ensure that an SQL transaction is started.
  88    *
  89    * This is a thin wrapper around __construct() which allows more fluent coding.
  90    *
  91    * @param bool $nest
  92    *   Determines what to do if there's currently an active transaction:.
  93    *   - If true, then make a new nested transaction ("SAVEPOINT")
  94    *   - If false, then attach to the existing transaction
  95    * @return \CRM_Core_Transaction
  96    */
  97   public static function create($nest = FALSE) {
  98     return new self($nest);
  99   }
 100
 101   /**
 102    * Ensure that an SQL transaction is started.
 103    *
 104    * @param bool $nest
 105    *   Determines what to do if there's currently an active transaction:.
 106    *   - If true, then make a new nested transaction ("SAVEPOINT")
 107    *   - If false, then attach to the existing transaction
 108    */
 109   public function __construct($nest = FALSE) {
 110     \Civi\Core\Transaction\Manager::singleton()->inc($nest);
 111   }
 112
 113   public function __destruct() {
 114     $this->commit();
 115   }
 116
 117   /**
 118    * Immediately commit or rollback.
 119    *
 120    * (Note: Prior to 4.6, return void)
 121    *
 122    * @return \CRM_Core_Exception this
 123    */
 124   public function commit() {
 125     if (!$this->_pseudoCommitted) {
 126       $this->_pseudoCommitted = TRUE;
 127       \Civi\Core\Transaction\Manager::singleton()->dec();
 128     }
 129     return $this;
 130   }
 131
 132   /**
 133    * @param $flag
 134    */
 135   public static function rollbackIfFalse($flag) {
 136     $frame = \Civi\Core\Transaction\Manager::singleton()->getFrame();
 137     if ($flag === FALSE && $frame !== NULL) {
 138       $frame->setRollbackOnly();
 139     }
 140   }
 141
 142   /**
 143    * Mark the transaction for rollback.
 144    *
 145    * (Note: Prior to 4.6, return void)
 146    * @return \CRM_Core_Transaction
 147    */
 148   public function rollback() {
 149     $frame = \Civi\Core\Transaction\Manager::singleton()->getFrame();
 150     if ($frame !== NULL) {
 151       $frame->setRollbackOnly();
 152     }
 153     return $this;
 154   }
 155
 156   /**
 157    * Execute a function ($callable) within the scope of a transaction. If
 158    * $callable encounters an unhandled exception, then rollback the transaction.
 159    *
 160    * After calling run(), the CRM_Core_Transaction object is "used up"; do not
 161    * use it again.
 162    *
 163    * @param string $callable
 164    *   Should exception one parameter (CRM_Core_Transaction $tx).
 165    * @return CRM_Core_Transaction
 166    * @throws Exception
 167    */
 168   public function run($callable) {
 169     try {
 170       $callable($this);
 171     }
 172     catch (Exception $ex) {
 173       $this->rollback()->commit();
 174       throw $ex;
 175     }
 176     $this->commit();
 177     return $this;
 178   }
 179
 180   /**
 181    * Force an immediate rollback, regardless of how many any
 182    * CRM_Core_Transaction objects are waiting for
 183    * pseudo-commits.
 184    *
 185    * Only rollback if the transaction API has been called.
 186    *
 187    * This is only appropriate when it is _certain_ that the
 188    * callstack will not wind-down normally -- e.g. before
 189    * a call to exit().
 190    */
 191   public static function forceRollbackIfEnabled() {
 192     if (\Civi\Core\Transaction\Manager::singleton()->getFrame() !== NULL) {
 193       \Civi\Core\Transaction\Manager::singleton()->forceRollback();
 194     }
 195   }
 196
 197   /**
 198    * @return bool
 199    */
 200   public static function willCommit() {
 201     $frame = \Civi\Core\Transaction\Manager::singleton()->getFrame();
 202     return ($frame === NULL) ? TRUE : !$frame->isRollbackOnly();
 203   }
 204
 205   /**
 206    * Determine whether there is a pending transaction.
 207    */
 208   public static function isActive() {
 209     $frame = \Civi\Core\Transaction\Manager::singleton()->getFrame();
 210     return ($frame !== NULL);
 211   }
 212
 213   /**
 214    * Add a transaction callback.
 215    *
 216    * Note: It's conceivable to add callbacks to the main/overall transaction
 217    * (aka $manager->getBaseFrame()) or to the innermost nested transaction
 218    * (aka $manager->getFrame()). addCallback() has been used in the past to
 219    * work-around deadlocks. This may or may not be necessary now -- but it
 220    * seems more consistent (for b/c purposes) to attach callbacks to the
 221    * main/overall transaction.
 222    *
 223    * Pre-condition: isActive()
 224    *
 225    * @param int $phase
 226    *   A constant; one of: self::PHASE_{PRE,POST}_{COMMIT,ROLLBACK}.
 227    * @param string $callback
 228    *   A PHP callback.
 229    * @param mixed $params
 230    *   Optional values to pass to callback.
 231    *          See php manual call_user_func_array for details.
 232    * @param int $id
 233    */
 234   public static function addCallback($phase, $callback, $params = NULL, $id = NULL) {
 235     $frame = \Civi\Core\Transaction\Manager::singleton()->getBaseFrame();
 236     $frame->addCallback($phase, $callback, $params, $id);
 237   }
 238
 239   /**
 240    * Whenever hook_civicrm_post fires, schedule an equivalent
 241    * call to hook_civicrm_postCommit.
 242    *
 243    * @param \Civi\Core\Event\PostEvent $e
 244    * @see CRM_Utils_Hook::post
 245    */
 246   public static function addPostCommit($e) {
 247     // Do we want to dedupe post-commit hooks for the same txn? Setting an ID
 248     // would allow this.
 249     // $id = $e->entity . chr(0) . $e->action . chr(0) . $e->id;
 250     $frame = \Civi\Core\Transaction\Manager::singleton()->getBaseFrame();
 251     if ($frame) {
 252       $frame->addCallback(self::PHASE_POST_COMMIT, ['CRM_Utils_Hook', 'postCommit'], [$e->action, $e->entity, $e->id, $e->object]);
 253     }
 254     else {
 255       \CRM_Utils_Hook::postCommit($e->action, $e->entity, $e->id, $e->object);
 256     }
 257   }
 258
 259 }