Civi/API/Subscriber/TransactionSubscriber.php

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