Civi/API/Subscriber/TransactionSubscriber.php

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