crm.fsf.org/20131203/files/sites/all/modules-new/civicrm/Civi/API/Subscriber/TransactionSubscriber.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.6                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2015                                |
   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 namespace Civi\API\Subscriber;
  29
  30 use Civi\API\Events;
  31 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
  32
  33 /**
  34  * Class TransactionSubscriber
  35  *
  36  * Implement transaction management for API calls. Two API options are accepted:
  37  *  - is_transactional: bool|'nest' - if true, then all work is done inside a
  38  *    transaction. By default, true for mutator actions (C-UD). 'nest' will
  39  *    force creation of a nested transaction; otherwise, the default is to
  40  *    re-use any existing transactions.
  41  *  - options.force_rollback: bool - if true, all work is done in a nested
  42  *    transaction which will be rolled back.
  43  *
  44  * @package Civi\API\Subscriber
  45  */
  46 class TransactionSubscriber implements EventSubscriberInterface {
  47   /**
  48    * @return array
  49    */
  50   public static function getSubscribedEvents() {
  51     return array(
  52       Events::PREPARE => array('onApiPrepare', Events::W_EARLY),
  53       Events::RESPOND => array('onApiRespond', Events::W_MIDDLE),
  54       Events::EXCEPTION => array('onApiException', Events::W_EARLY),
  55     );
  56   }
  57
  58   /**
  59    * @var array (scalar $apiRequestId => CRM_Core_Transaction $tx)
  60    */
  61   private $transactions = array();
  62
  63   /**
  64    * @var array (scalar $apiRequestId => bool)
  65    *
  66    * A list of requests which should be forcibly rolled back to
  67    * their save points.
  68    */
  69   private $forceRollback = array();
  70
  71   /**
  72    * Determine if an API request should be treated as transactional.
  73    *
  74    * @param \Civi\API\Provider\ProviderInterface $apiProvider
  75    *   The API provider responsible for this request.
  76    * @param array $apiRequest
  77    *   The full API request.
  78    * @return bool
  79    */
  80   public function isTransactional($apiProvider, $apiRequest) {
  81     if ($this->isForceRollback($apiProvider, $apiRequest)) {
  82       return TRUE;
  83     }
  84     if (isset($apiRequest['params']['is_transactional'])) {
  85       return \CRM_Utils_String::strtobool($apiRequest['params']['is_transactional']) || $apiRequest['params']['is_transactional'] == 'nest';
  86     }
  87     return strtolower($apiRequest['action']) == 'create' || strtolower($apiRequest['action']) == 'delete' || strtolower($apiRequest['action']) == 'submit';
  88   }
  89
  90   /**
  91    * Determine if caller wants us to *always* rollback.
  92    *
  93    * @param \Civi\API\Provider\ProviderInterface $apiProvider
  94    *   The API provider responsible for this request.
  95    * @param array $apiRequest
  96    *   The full API request.
  97    * @return bool
  98    */
  99   public function isForceRollback($apiProvider, $apiRequest) {
 100     // FIXME: When APIv3 uses better parsing, only one check will be needed.
 101     if (isset($apiRequest['params']['options']['force_rollback'])) {
 102       return \CRM_Utils_String::strtobool($apiRequest['params']['options']['force_rollback']);
 103     }
 104     if (isset($apiRequest['options']['force_rollback'])) {
 105       return \CRM_Utils_String::strtobool($apiRequest['options']['force_rollback']);
 106     }
 107     return FALSE;
 108   }
 109
 110   /**
 111    * Determine if caller wants a nested transaction or a re-used transaction.
 112    *
 113    * @param \Civi\API\Provider\ProviderInterface $apiProvider
 114    *   The API provider responsible for this request.
 115    * @param array $apiRequest
 116    *   The full API request.
 117    * @return bool
 118    *   True if a new nested transaction is required; false if active tx may be used
 119    */
 120   public function isNested($apiProvider, $apiRequest) {
 121     if ($this->isForceRollback($apiProvider, $apiRequest)) {
 122       return TRUE;
 123     }
 124     if (isset($apiRequest['params']['is_transactional']) && $apiRequest['params']['is_transactional'] === 'nest') {
 125       return TRUE;
 126     }
 127     return FALSE;
 128   }
 129
 130   /**
 131    * Open a new transaction instance (if appropriate in the current policy)
 132    *
 133    * @param \Civi\API\Event\PrepareEvent $event
 134    *   API preparation event.
 135    */
 136   public function onApiPrepare(\Civi\API\Event\PrepareEvent $event) {
 137     $apiRequest = $event->getApiRequest();
 138     if ($this->isTransactional($event->getApiProvider(), $apiRequest)) {
 139       $this->transactions[$apiRequest['id']] = new \CRM_Core_Transaction($this->isNested($event->getApiProvider(), $apiRequest));
 140     }
 141     if ($this->isForceRollback($event->getApiProvider(), $apiRequest)) {
 142       $this->transactions[$apiRequest['id']]->rollback();
 143     }
 144   }
 145
 146   /**
 147    * Close any pending transactions.
 148    *
 149    * @param \Civi\API\Event\RespondEvent $event
 150    *   API response event.
 151    */
 152   public function onApiRespond(\Civi\API\Event\RespondEvent $event) {
 153     $apiRequest = $event->getApiRequest();
 154     if (isset($this->transactions[$apiRequest['id']])) {
 155       if (civicrm_error($event->getResponse())) {
 156         $this->transactions[$apiRequest['id']]->rollback();
 157       }
 158       unset($this->transactions[$apiRequest['id']]);
 159     }
 160   }
 161
 162   /**
 163    * Rollback the pending transaction.
 164    *
 165    * @param \Civi\API\Event\ExceptionEvent $event
 166    *   API exception event.
 167    */
 168   public function onApiException(\Civi\API\Event\ExceptionEvent $event) {
 169     $apiRequest = $event->getApiRequest();
 170     if (isset($this->transactions[$apiRequest['id']])) {
 171       $this->transactions[$apiRequest['id']]->rollback();
 172       unset($this->transactions[$apiRequest['id']]);
 173     }
 174   }
 175
 176 }