Civi/API/Subscriber/TransactionSubscriber.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 5                                                  |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2019                                |
   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 ($this->isForceRollback($apiProvider, $apiRequest)) {
  83       return TRUE;
  84     }
  85     if (isset($apiRequest['params']['is_transactional'])) {
  86       return \CRM_Utils_String::strtobool($apiRequest['params']['is_transactional']) || $apiRequest['params']['is_transactional'] == 'nest';
  87     }
  88     return strtolower($apiRequest['action']) == 'create' || strtolower($apiRequest['action']) == 'delete' || strtolower($apiRequest['action']) == 'submit';
  89   }
  90
  91   /**
  92    * Determine if caller wants us to *always* rollback.
  93    *
  94    * @param \Civi\API\Provider\ProviderInterface $apiProvider
  95    *   The API provider responsible for this request.
  96    * @param array $apiRequest
  97    *   The full API request.
  98    * @return bool
  99    */
 100   public function isForceRollback($apiProvider, $apiRequest) {
 101     // FIXME: When APIv3 uses better parsing, only one check will be needed.
 102     if (isset($apiRequest['params']['options']['force_rollback'])) {
 103       return \CRM_Utils_String::strtobool($apiRequest['params']['options']['force_rollback']);
 104     }
 105     if (isset($apiRequest['options']['force_rollback'])) {
 106       return \CRM_Utils_String::strtobool($apiRequest['options']['force_rollback']);
 107     }
 108     return FALSE;
 109   }
 110
 111   /**
 112    * Determine if caller wants a nested transaction or a re-used transaction.
 113    *
 114    * @param \Civi\API\Provider\ProviderInterface $apiProvider
 115    *   The API provider responsible for this request.
 116    * @param array $apiRequest
 117    *   The full API request.
 118    * @return bool
 119    *   True if a new nested transaction is required; false if active tx may be used
 120    */
 121   public function isNested($apiProvider, $apiRequest) {
 122     if ($this->isForceRollback($apiProvider, $apiRequest)) {
 123       return TRUE;
 124     }
 125     if (isset($apiRequest['params']['is_transactional']) && $apiRequest['params']['is_transactional'] === 'nest') {
 126       return TRUE;
 127     }
 128     return FALSE;
 129   }
 130
 131   /**
 132    * Open a new transaction instance (if appropriate in the current policy)
 133    *
 134    * @param \Civi\API\Event\PrepareEvent $event
 135    *   API preparation event.
 136    */
 137   public function onApiPrepare(\Civi\API\Event\PrepareEvent $event) {
 138     $apiRequest = $event->getApiRequest();
 139     if ($this->isTransactional($event->getApiProvider(), $apiRequest)) {
 140       $this->transactions[$apiRequest['id']] = new \CRM_Core_Transaction($this->isNested($event->getApiProvider(), $apiRequest));
 141     }
 142     if ($this->isForceRollback($event->getApiProvider(), $apiRequest)) {
 143       $this->transactions[$apiRequest['id']]->rollback();
 144     }
 145   }
 146
 147   /**
 148    * Close any pending transactions.
 149    *
 150    * @param \Civi\API\Event\RespondEvent $event
 151    *   API response event.
 152    */
 153   public function onApiRespond(\Civi\API\Event\RespondEvent $event) {
 154     $apiRequest = $event->getApiRequest();
 155     if (isset($this->transactions[$apiRequest['id']])) {
 156       if (civicrm_error($event->getResponse())) {
 157         $this->transactions[$apiRequest['id']]->rollback();
 158       }
 159       unset($this->transactions[$apiRequest['id']]);
 160     }
 161   }
 162
 163   /**
 164    * Rollback the pending transaction.
 165    *
 166    * @param \Civi\API\Event\ExceptionEvent $event
 167    *   API exception event.
 168    */
 169   public function onApiException(\Civi\API\Event\ExceptionEvent $event) {
 170     $apiRequest = $event->getApiRequest();
 171     if (isset($this->transactions[$apiRequest['id']])) {
 172       $this->transactions[$apiRequest['id']]->rollback();
 173       unset($this->transactions[$apiRequest['id']]);
 174     }
 175   }
 176
 177 }