Commit | Line | Data |
---|---|---|
6a488035 TO |
1 | <?php |
2 | /* | |
3 | +--------------------------------------------------------------------+ | |
06b69b18 | 4 | | CiviCRM version 4.5 | |
6a488035 | 5 | +--------------------------------------------------------------------+ |
06b69b18 | 6 | | Copyright CiviCRM LLC (c) 2004-2014 | |
6a488035 TO |
7 | +--------------------------------------------------------------------+ |
8 | | This file is a part of CiviCRM. | | |
9 | | | | |
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. | | |
13 | | | | |
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. | | |
18 | | | | |
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 | +--------------------------------------------------------------------+ | |
26 | */ | |
27 | ||
28 | /** | |
29 | * | |
30 | * @package CRM | |
06b69b18 | 31 | * @copyright CiviCRM LLC (c) 2004-2014 |
6a488035 TO |
32 | * @copyright David Strauss <david@fourkitchens.com> (c) 2007 |
33 | * $Id$ | |
34 | * | |
5bb8417a TO |
35 | * (Note: This has been considerably rewritten; the interface is preserved |
36 | * for backward compatibility.) | |
6a488035 | 37 | * |
5bb8417a TO |
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). | |
44 | * | |
45 | * Examples: | |
46 | * | |
47 | * @code | |
48 | * // Some business logic using the helper functions | |
49 | * function my_business_logic() { | |
50 | * CRM_Core_Transaction::create()->run(function($tx) { | |
51 | * ...do work... | |
52 | * if ($error) throw new Exception(); | |
53 | * }); | |
54 | * } | |
55 | * | |
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(); | |
60 | * ...do work... | |
61 | * if ($error) { | |
62 | * $tx->rollback(); | |
63 | * return error_value; | |
64 | * } | |
65 | * } | |
66 | * | |
67 | * // Some business logic which uses exceptions | |
68 | * // and explicitly manages the transaction. | |
69 | * function my_business_logic() { | |
70 | * $tx = new CRM_Core_Transaction(); | |
71 | * try { | |
72 | * ...do work... | |
73 | * } catch (Exception $ex) { | |
74 | * $tx->rollback()->commit(); | |
75 | * throw $ex; | |
76 | * } | |
77 | * } | |
78 | * | |
79 | * @endcode | |
80 | * | |
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. | |
6a488035 TO |
84 | */ |
85 | class CRM_Core_Transaction { | |
86 | ||
87 | /** | |
88 | * These constants represent phases at which callbacks can be invoked | |
89 | */ | |
90 | CONST PHASE_PRE_COMMIT = 1; | |
91 | CONST PHASE_POST_COMMIT = 2; | |
92 | CONST PHASE_PRE_ROLLBACK = 4; | |
93 | CONST PHASE_POST_ROLLBACK = 8; | |
94 | ||
95 | /** | |
5bb8417a TO |
96 | * Whether commit() has been called on this instance |
97 | * of CRM_Core_Transaction | |
6a488035 | 98 | */ |
5bb8417a | 99 | private $_pseudoCommitted = FALSE; |
6a488035 TO |
100 | |
101 | /** | |
5bb8417a | 102 | * Ensure that an SQL transaction is started |
6a488035 | 103 | * |
5bb8417a | 104 | * This is a thin wrapper around __construct() which allows more fluent coding. |
6a488035 | 105 | * |
5bb8417a TO |
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 | |
6a488035 | 110 | */ |
5bb8417a TO |
111 | public static function create($nest = FALSE) { |
112 | return new self($nest); | |
113 | } | |
a0ee3941 EM |
114 | |
115 | /** | |
5bb8417a | 116 | * Ensure that an SQL transaction is started |
a0ee3941 | 117 | * |
5bb8417a TO |
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 | |
a0ee3941 | 121 | */ |
5bb8417a TO |
122 | function __construct($nest = FALSE) { |
123 | \Civi\Core\Transaction\Manager::singleton()->inc($nest); | |
6a488035 TO |
124 | } |
125 | ||
126 | function __destruct() { | |
127 | $this->commit(); | |
128 | } | |
129 | ||
5bb8417a TO |
130 | /** |
131 | * Immediately commit or rollback | |
132 | * | |
133 | * (Note: Prior to 4.6, return void) | |
134 | * | |
135 | * @return \CRM_Core_Exception this | |
136 | */ | |
6a488035 | 137 | function commit() { |
5bb8417a | 138 | if (!$this->_pseudoCommitted) { |
6a488035 | 139 | $this->_pseudoCommitted = TRUE; |
5bb8417a | 140 | \Civi\Core\Transaction\Manager::singleton()->dec(); |
6a488035 | 141 | } |
5bb8417a | 142 | return $this; |
6a488035 TO |
143 | } |
144 | ||
a0ee3941 EM |
145 | /** |
146 | * @param $flag | |
147 | */ | |
6a488035 | 148 | static public function rollbackIfFalse($flag) { |
5bb8417a TO |
149 | $frame = \Civi\Core\Transaction\Manager::singleton()->getFrame(); |
150 | if ($flag === FALSE && $frame !== NULL) { | |
151 | $frame->setRollbackOnly(); | |
6a488035 TO |
152 | } |
153 | } | |
154 | ||
5bb8417a TO |
155 | /** |
156 | * Mark the transaction for rollback. | |
157 | * | |
158 | * (Note: Prior to 4.6, return void) | |
159 | * @return \CRM_Core_Exception this | |
160 | */ | |
6a488035 | 161 | public function rollback() { |
5bb8417a TO |
162 | $frame = \Civi\Core\Transaction\Manager::singleton()->getFrame(); |
163 | if ($frame !== NULL) { | |
164 | $frame->setRollbackOnly(); | |
165 | } | |
166 | return $this; | |
167 | } | |
168 | ||
169 | /** | |
170 | * Execute a function ($callable) within the scope of a transaction. If | |
171 | * $callable encounters an unhandled exception, then rollback the transaction. | |
172 | * | |
173 | * After calling run(), the CRM_Core_Transaction object is "used up"; do not | |
174 | * use it again. | |
175 | * | |
176 | * @param type $callable Should exception one paramter (CRM_Core_Transaction $tx) | |
177 | * @return \CRM_Core_Exception this | |
178 | * @throws Exception | |
179 | */ | |
180 | public function run($callable) { | |
181 | try { | |
182 | $callable($this); | |
183 | } catch (Exception $ex) { | |
184 | $this->rollback()->commit(); | |
185 | throw $ex; | |
186 | } | |
187 | $this->commit(); | |
188 | return $this; | |
6a488035 TO |
189 | } |
190 | ||
191 | /** | |
192 | * Force an immediate rollback, regardless of how many any | |
193 | * CRM_Core_Transaction objects are waiting for | |
194 | * pseudo-commits. | |
195 | * | |
196 | * Only rollback if the transaction API has been called. | |
197 | * | |
198 | * This is only appropriate when it is _certain_ that the | |
199 | * callstack will not wind-down normally -- e.g. before | |
200 | * a call to exit(). | |
201 | */ | |
202 | static public function forceRollbackIfEnabled() { | |
5bb8417a TO |
203 | if (\Civi\Core\Transaction\Manager::singleton()->getFrame() !== NULL) { |
204 | \Civi\Core\Transaction\Manager::singleton()->forceRollback(); | |
6a488035 TO |
205 | } |
206 | } | |
207 | ||
a0ee3941 EM |
208 | /** |
209 | * @return bool | |
210 | */ | |
6a488035 | 211 | static public function willCommit() { |
5bb8417a TO |
212 | $frame = \Civi\Core\Transaction\Manager::singleton()->getFrame(); |
213 | return ($frame === NULL) ? TRUE : !$frame->isRollbackOnly(); | |
6a488035 TO |
214 | } |
215 | ||
216 | /** | |
217 | * Determine whether there is a pending transaction | |
218 | */ | |
219 | static public function isActive() { | |
5bb8417a TO |
220 | $frame = \Civi\Core\Transaction\Manager::singleton()->getFrame(); |
221 | return ($frame !== NULL); | |
6a488035 TO |
222 | } |
223 | ||
224 | /** | |
225 | * Add a transaction callback | |
226 | * | |
5bb8417a TO |
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. | |
233 | * | |
6a488035 TO |
234 | * Pre-condition: isActive() |
235 | * | |
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. | |
240 | */ | |
f99a2e5d | 241 | static public function addCallback($phase, $callback, $params = null, $id = NULL) { |
5bb8417a TO |
242 | $frame = \Civi\Core\Transaction\Manager::singleton()->getBaseFrame(); |
243 | $frame->addCallback($phase, $callback, $params, $id); | |
6a488035 TO |
244 | } |
245 | } |