3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
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 +--------------------------------------------------------------------+
15 * @copyright CiviCRM LLC https://civicrm.org/licensing
16 * @copyright David Strauss <david@fourkitchens.com> (c) 2007
19 * (Note: This has been considerably rewritten; the interface is preserved
20 * for backward compatibility.)
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).
32 * // Some business logic using the helper functions
33 * function my_business_logic() {
34 * CRM_Core_Transaction::create()->run(function($tx) {
36 * if ($error) throw new Exception();
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();
51 * // Some business logic which uses exceptions
52 * // and explicitly manages the transaction.
53 * function my_business_logic() {
54 * $tx = new CRM_Core_Transaction();
57 * } catch (Exception $ex) {
58 * $tx->rollback()->commit();
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.
69 class CRM_Core_Transaction
{
72 * These constants represent phases at which callbacks can be invoked.
74 const PHASE_PRE_COMMIT
= 1;
75 const PHASE_POST_COMMIT
= 2;
76 const PHASE_PRE_ROLLBACK
= 4;
77 const PHASE_POST_ROLLBACK
= 8;
80 * Whether commit() has been called on this instance
81 * of CRM_Core_Transaction
84 private $_pseudoCommitted = FALSE;
87 * Ensure that an SQL transaction is started.
89 * This is a thin wrapper around __construct() which allows more fluent coding.
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
97 public static function create($nest = FALSE) {
98 return new self($nest);
102 * Ensure that an SQL transaction is started.
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
109 public function __construct($nest = FALSE) {
110 \Civi\Core\Transaction\Manager
::singleton()->inc($nest);
113 public function __destruct() {
118 * Immediately commit or rollback.
120 * (Note: Prior to 4.6, return void)
122 * @return \CRM_Core_Exception this
124 public function commit() {
125 if (!$this->_pseudoCommitted
) {
126 $this->_pseudoCommitted
= TRUE;
127 \Civi\Core\Transaction\Manager
::singleton()->dec();
135 public static function rollbackIfFalse($flag) {
136 $frame = \Civi\Core\Transaction\Manager
::singleton()->getFrame();
137 if ($flag === FALSE && $frame !== NULL) {
138 $frame->setRollbackOnly();
143 * Mark the transaction for rollback.
145 * (Note: Prior to 4.6, return void)
146 * @return \CRM_Core_Transaction
148 public function rollback() {
149 $frame = \Civi\Core\Transaction\Manager
::singleton()->getFrame();
150 if ($frame !== NULL) {
151 $frame->setRollbackOnly();
157 * Execute a function ($callable) within the scope of a transaction. If
158 * $callable encounters an unhandled exception, then rollback the transaction.
160 * After calling run(), the CRM_Core_Transaction object is "used up"; do not
163 * @param string $callable
164 * Should exception one parameter (CRM_Core_Transaction $tx).
165 * @return CRM_Core_Transaction
168 public function run($callable) {
172 catch (Exception
$ex) {
173 $this->rollback()->commit();
181 * Force an immediate rollback, regardless of how many any
182 * CRM_Core_Transaction objects are waiting for
185 * Only rollback if the transaction API has been called.
187 * This is only appropriate when it is _certain_ that the
188 * callstack will not wind-down normally -- e.g. before
191 public static function forceRollbackIfEnabled() {
192 if (\Civi\Core\Transaction\Manager
::singleton()->getFrame() !== NULL) {
193 \Civi\Core\Transaction\Manager
::singleton()->forceRollback();
200 public static function willCommit() {
201 $frame = \Civi\Core\Transaction\Manager
::singleton()->getFrame();
202 return ($frame === NULL) ?
TRUE : !$frame->isRollbackOnly();
206 * Determine whether there is a pending transaction.
208 public static function isActive() {
209 $frame = \Civi\Core\Transaction\Manager
::singleton()->getFrame();
210 return ($frame !== NULL);
214 * Add a transaction callback.
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.
223 * Pre-condition: isActive()
226 * A constant; one of: self::PHASE_{PRE,POST}_{COMMIT,ROLLBACK}.
227 * @param string $callback
229 * @param mixed $params
230 * Optional values to pass to callback.
231 * See php manual call_user_func_array for details.
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);