3 +--------------------------------------------------------------------+
4 | CiviCRM version 4.7 |
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2017 |
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-2017
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.
107 * Determines what to do if there's currently an active transaction:.
108 * - If true, then make a new nested transaction ("SAVEPOINT")
109 * - If false, then attach to the existing transaction
110 * @return \CRM_Core_Transaction
112 public static function create($nest = FALSE) {
113 return new self($nest);
117 * Ensure that an SQL transaction is started.
120 * Determines what to do if there's currently an active transaction:.
121 * - If true, then make a new nested transaction ("SAVEPOINT")
122 * - If false, then attach to the existing transaction
124 public function __construct($nest = FALSE) {
125 \Civi\Core\Transaction\Manager
::singleton()->inc($nest);
128 public function __destruct() {
133 * Immediately commit or rollback.
135 * (Note: Prior to 4.6, return void)
137 * @return \CRM_Core_Exception this
139 public function commit() {
140 if (!$this->_pseudoCommitted
) {
141 $this->_pseudoCommitted
= TRUE;
142 \Civi\Core\Transaction\Manager
::singleton()->dec();
150 static public function rollbackIfFalse($flag) {
151 $frame = \Civi\Core\Transaction\Manager
::singleton()->getFrame();
152 if ($flag === FALSE && $frame !== NULL) {
153 $frame->setRollbackOnly();
158 * Mark the transaction for rollback.
160 * (Note: Prior to 4.6, return void)
161 * @return \CRM_Core_Transaction
163 public function rollback() {
164 $frame = \Civi\Core\Transaction\Manager
::singleton()->getFrame();
165 if ($frame !== NULL) {
166 $frame->setRollbackOnly();
172 * Execute a function ($callable) within the scope of a transaction. If
173 * $callable encounters an unhandled exception, then rollback the transaction.
175 * After calling run(), the CRM_Core_Transaction object is "used up"; do not
178 * @param string $callable
179 * Should exception one parameter (CRM_Core_Transaction $tx).
180 * @return CRM_Core_Transaction
183 public function run($callable) {
187 catch (Exception
$ex) {
188 $this->rollback()->commit();
196 * Force an immediate rollback, regardless of how many any
197 * CRM_Core_Transaction objects are waiting for
200 * Only rollback if the transaction API has been called.
202 * This is only appropriate when it is _certain_ that the
203 * callstack will not wind-down normally -- e.g. before
206 static public function forceRollbackIfEnabled() {
207 if (\Civi\Core\Transaction\Manager
::singleton()->getFrame() !== NULL) {
208 \Civi\Core\Transaction\Manager
::singleton()->forceRollback();
215 static public function willCommit() {
216 $frame = \Civi\Core\Transaction\Manager
::singleton()->getFrame();
217 return ($frame === NULL) ?
TRUE : !$frame->isRollbackOnly();
221 * Determine whether there is a pending transaction.
223 static public function isActive() {
224 $frame = \Civi\Core\Transaction\Manager
::singleton()->getFrame();
225 return ($frame !== NULL);
229 * Add a transaction callback.
231 * Note: It's conceivable to add callbacks to the main/overall transaction
232 * (aka $manager->getBaseFrame()) or to the innermost nested transaction
233 * (aka $manager->getFrame()). addCallback() has been used in the past to
234 * work-around deadlocks. This may or may not be necessary now -- but it
235 * seems more consistent (for b/c purposes) to attach callbacks to the
236 * main/overall transaction.
238 * Pre-condition: isActive()
241 * A constant; one of: self::PHASE_{PRE,POST}_{COMMIT,ROLLBACK}.
242 * @param string $callback
244 * @param mixed $params
245 * Optional values to pass to callback.
246 * See php manual call_user_func_array for details.
249 static public function addCallback($phase, $callback, $params = NULL, $id = NULL) {
250 $frame = \Civi\Core\Transaction\Manager
::singleton()->getBaseFrame();
251 $frame->addCallback($phase, $callback, $params, $id);