3 +--------------------------------------------------------------------+
4 | CiviCRM version 4.6 |
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2014 |
7 +--------------------------------------------------------------------+
8 | This file is a part of CiviCRM. |
10 | CiviCRM is free software; you can copy, modify, and distribute it |
11 | under the terms of the GNU Affero General Public License |
12 | Version 3, 19 November 2007 and the CiviCRM Licensing Exception. |
14 | CiviCRM is distributed in the hope that it will be useful, but |
15 | WITHOUT ANY WARRANTY; without even the implied warranty of |
16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
17 | See the GNU Affero General Public License for more details. |
19 | You should have received a copy of the GNU Affero General Public |
20 | License and the CiviCRM Licensing Exception along |
21 | with this program; if not, contact CiviCRM LLC |
22 | at info[AT]civicrm[DOT]org. If you have questions about the |
23 | GNU Affero General Public License or the licensing of CiviCRM, |
24 | see the CiviCRM license FAQ at http://civicrm.org/licensing |
25 +--------------------------------------------------------------------+
31 * @copyright CiviCRM LLC (c) 2004-2014
32 * @copyright David Strauss <david@fourkitchens.com> (c) 2007
35 * (Note: This has been considerably rewritten; the interface is preserved
36 * for backward compatibility.)
38 * Transaction management in Civi is divided among three classes:
39 * - CRM_Core_Transaction: API. This binds to __construct() + __destruct()
40 * and notifies the transaction manager when it's OK to begin/end a transaction.
41 * - Civi\Core\Transaction\Manager: Tracks pending transaction-frames
42 * - Civi\Core\Transaction\Frame: A nestable transaction (e.g. based on BEGIN/COMMIT/ROLLBACK
43 * or SAVEPOINT/ROLLBACK TO SAVEPOINT).
48 * // Some business logic using the helper functions
49 * function my_business_logic() {
50 * CRM_Core_Transaction::create()->run(function($tx) {
52 * if ($error) throw new Exception();
56 * // Some business logic which returns an error-value
57 * // and explicitly manages the transaction.
58 * function my_business_logic() {
59 * $tx = new CRM_Core_Transaction();
67 * // Some business logic which uses exceptions
68 * // and explicitly manages the transaction.
69 * function my_business_logic() {
70 * $tx = new CRM_Core_Transaction();
73 * } catch (Exception $ex) {
74 * $tx->rollback()->commit();
81 * Note: As of 4.6, the transaction manager supports both reference-counting and nested
82 * transactions (SAVEPOINTs). In the past, it only supported reference-counting. The two cases
83 * may exhibit different systemic effects with respect to unhandled exceptions.
85 class CRM_Core_Transaction
{
88 * These constants represent phases at which callbacks can be invoked
90 CONST PHASE_PRE_COMMIT
= 1;
91 CONST PHASE_POST_COMMIT
= 2;
92 CONST PHASE_PRE_ROLLBACK
= 4;
93 CONST PHASE_POST_ROLLBACK
= 8;
96 * Whether commit() has been called on this instance
97 * of CRM_Core_Transaction
99 private $_pseudoCommitted = FALSE;
102 * Ensure that an SQL transaction is started
104 * This is a thin wrapper around __construct() which allows more fluent coding.
106 * @param bool $nest Determines what to do if there's currently an active transaction:
107 * - If true, then make a new nested transaction ("SAVEPOINT")
108 * - If false, then attach to the existing transaction
109 * @return \CRM_Core_Transaction
111 public static function create($nest = FALSE) {
112 return new self($nest);
116 * Ensure that an SQL transaction is started
118 * @param bool $nest Determines what to do if there's currently an active transaction:
119 * - If true, then make a new nested transaction ("SAVEPOINT")
120 * - If false, then attach to the existing transaction
122 function __construct($nest = FALSE) {
123 \Civi\Core\Transaction\Manager
::singleton()->inc($nest);
126 function __destruct() {
131 * Immediately commit or rollback
133 * (Note: Prior to 4.6, return void)
135 * @return \CRM_Core_Exception this
138 if (!$this->_pseudoCommitted
) {
139 $this->_pseudoCommitted
= TRUE;
140 \Civi\Core\Transaction\Manager
::singleton()->dec();
148 static public function rollbackIfFalse($flag) {
149 $frame = \Civi\Core\Transaction\Manager
::singleton()->getFrame();
150 if ($flag === FALSE && $frame !== NULL) {
151 $frame->setRollbackOnly();
156 * Mark the transaction for rollback.
158 * (Note: Prior to 4.6, return void)
159 * @return \CRM_Core_Exception this
161 public function rollback() {
162 $frame = \Civi\Core\Transaction\Manager
::singleton()->getFrame();
163 if ($frame !== NULL) {
164 $frame->setRollbackOnly();
170 * Execute a function ($callable) within the scope of a transaction. If
171 * $callable encounters an unhandled exception, then rollback the transaction.
173 * After calling run(), the CRM_Core_Transaction object is "used up"; do not
176 * @param mixed $callable Should exception one paramter (CRM_Core_Transaction $tx)
177 * @return \CRM_Core_Exception this
180 public function run($callable) {
183 } catch (Exception
$ex) {
184 $this->rollback()->commit();
192 * Force an immediate rollback, regardless of how many any
193 * CRM_Core_Transaction objects are waiting for
196 * Only rollback if the transaction API has been called.
198 * This is only appropriate when it is _certain_ that the
199 * callstack will not wind-down normally -- e.g. before
202 static public function forceRollbackIfEnabled() {
203 if (\Civi\Core\Transaction\Manager
::singleton()->getFrame() !== NULL) {
204 \Civi\Core\Transaction\Manager
::singleton()->forceRollback();
211 static public function willCommit() {
212 $frame = \Civi\Core\Transaction\Manager
::singleton()->getFrame();
213 return ($frame === NULL) ?
TRUE : !$frame->isRollbackOnly();
217 * Determine whether there is a pending transaction
219 static public function isActive() {
220 $frame = \Civi\Core\Transaction\Manager
::singleton()->getFrame();
221 return ($frame !== NULL);
225 * Add a transaction callback
227 * Note: It's conceivable to add callbacks to the main/overall transaction
228 * (aka $manager->getBaseFrame()) or to the innermost nested transaction
229 * (aka $manager->getFrame()). addCallback() has been used in the past to
230 * work-around deadlocks. This may or may not be necessary now -- but it
231 * seems more consistent (for b/c purposes) to attach callbacks to the
232 * main/overall transaction.
234 * Pre-condition: isActive()
236 * @param $phase A constant; one of: self::PHASE_{PRE,POST}_{COMMIT,ROLLBACK}
237 * @param $callback A PHP callback
238 * @param mixed $params Optional values to pass to callback.
239 * See php manual call_user_func_array for details.
241 static public function addCallback($phase, $callback, $params = null, $id = NULL) {
242 $frame = \Civi\Core\Transaction\Manager
::singleton()->getBaseFrame();
243 $frame->addCallback($phase, $callback, $params, $id);