Civi/API/Subscriber/TransactionSubscriber.php

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