Merge pull request #6539 from joannechester/CRM-16185-rename-date-filters

[civicrm-core.git] / Civi / API / Subscriber / TransactionSubscriber.php

diff --git a/Civi/API/Subscriber/TransactionSubscriber.php b/Civi/API/Subscriber/TransactionSubscriber.php
index 0a2939c062bfc765c5823ae255e7bf8e4109319a..ee10ea164780b30becc204bbeec6a9d574bd5d4b 100644 (file)
--- a/Civi/API/Subscriber/TransactionSubscriber.php
+++ b/Civi/API/Subscriber/TransactionSubscriber.php
@@ -1,9 +1,9 @@
 <?php
 /*
  +--------------------------------------------------------------------+
- | CiviCRM version 4.6                                                |
+ | CiviCRM version 4.7                                                |
  +--------------------------------------------------------------------+
- | Copyright CiviCRM LLC (c) 2004-2014                                |
+ | Copyright CiviCRM LLC (c) 2004-2015                                |
  +--------------------------------------------------------------------+
  | This file is a part of CiviCRM.                                    |
  |                                                                    |
@@ -23,9 +23,10 @@
  | GNU Affero General Public License or the licensing of CiviCRM,     |
  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  +--------------------------------------------------------------------+
-*/
+ */
 
 namespace Civi\API\Subscriber;
+
 use Civi\API\Events;
 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
@@ -33,9 +34,12 @@ use Symfony\Component\EventDispatcher\EventSubscriberInterface;
  * Class TransactionSubscriber
  *
  * Implement transaction management for API calls. Two API options are accepted:
- *  - is_transactional: bool|'nest' - if true, then all work is done inside a transaction. by default, true for mutator actions (C-UD)
- *      'nest' will force creation of a nested transaction; otherwise, the default is to re-use any existing transactions
- *  - options.force_rollback: bool - if true, all work is done in a nested transaction which will be rolled back
+ *  - is_transactional: bool|'nest' - if true, then all work is done inside a
+ *    transaction. By default, true for mutator actions (C-UD). 'nest' will
+ *    force creation of a nested transaction; otherwise, the default is to
+ *    re-use any existing transactions.
+ *  - options.force_rollback: bool - if true, all work is done in a nested
+ *    transaction which will be rolled back.
  *
  * @package Civi\API\Subscriber
  */
@@ -65,15 +69,17 @@ class TransactionSubscriber implements EventSubscriberInterface {
   private $forceRollback = array();
 
   /**
-   * Determine if an API request should be treated as transactional
+   * Determine if an API request should be treated as transactional.
    *
    * @param \Civi\API\Provider\ProviderInterface $apiProvider
+   *   The API provider responsible for this request.
    * @param array $apiRequest
+   *   The full API request.
    * @return bool
    */
   public function isTransactional($apiProvider, $apiRequest) {
     if ($this->isForceRollback($apiProvider, $apiRequest)) {
-      return true;
+      return TRUE;
     }
     if (isset($apiRequest['params']['is_transactional'])) {
       return \CRM_Utils_String::strtobool($apiRequest['params']['is_transactional']) || $apiRequest['params']['is_transactional'] == 'nest';
@@ -85,11 +91,13 @@ class TransactionSubscriber implements EventSubscriberInterface {
    * Determine if caller wants us to *always* rollback.
    *
    * @param \Civi\API\Provider\ProviderInterface $apiProvider
+   *   The API provider responsible for this request.
    * @param array $apiRequest
+   *   The full API request.
    * @return bool
    */
   public function isForceRollback($apiProvider, $apiRequest) {
-    // FIXME: When APIv3 uses better parsing, the [params][options][force_rollback] check will be redundant
+    // FIXME: When APIv3 uses better parsing, only one check will be needed.
     if (isset($apiRequest['params']['options']['force_rollback'])) {
       return \CRM_Utils_String::strtobool($apiRequest['params']['options']['force_rollback']);
     }
@@ -103,14 +111,17 @@ class TransactionSubscriber implements EventSubscriberInterface {
    * Determine if caller wants a nested transaction or a re-used transaction.
    *
    * @param \Civi\API\Provider\ProviderInterface $apiProvider
+   *   The API provider responsible for this request.
    * @param array $apiRequest
-   * @return bool True if a new nested transaction is required; false if active tx may be used
+   *   The full API request.
+   * @return bool
+   *   True if a new nested transaction is required; false if active tx may be used
    */
   public function isNested($apiProvider, $apiRequest) {
     if ($this->isForceRollback($apiProvider, $apiRequest)) {
       return TRUE;
     }
-    if (isset($apiRequest['params']['is_transactional']) && $apiRequest['params']['is_transactional'] === 'nest')  {
+    if (isset($apiRequest['params']['is_transactional']) && $apiRequest['params']['is_transactional'] === 'nest') {
       return TRUE;
     }
     return FALSE;
@@ -120,8 +131,9 @@ class TransactionSubscriber implements EventSubscriberInterface {
    * Open a new transaction instance (if appropriate in the current policy)
    *
    * @param \Civi\API\Event\PrepareEvent $event
+   *   API preparation event.
    */
-  function onApiPrepare(\Civi\API\Event\PrepareEvent $event) {
+  public function onApiPrepare(\Civi\API\Event\PrepareEvent $event) {
     $apiRequest = $event->getApiRequest();
     if ($this->isTransactional($event->getApiProvider(), $apiRequest)) {
       $this->transactions[$apiRequest['id']] = new \CRM_Core_Transaction($this->isNested($event->getApiProvider(), $apiRequest));
@@ -132,9 +144,12 @@ class TransactionSubscriber implements EventSubscriberInterface {
   }
 
   /**
-   * Close any pending transactions
+   * Close any pending transactions.
+   *
+   * @param \Civi\API\Event\RespondEvent $event
+   *   API response event.
    */
-  function onApiRespond(\Civi\API\Event\RespondEvent $event) {
+  public function onApiRespond(\Civi\API\Event\RespondEvent $event) {
     $apiRequest = $event->getApiRequest();
     if (isset($this->transactions[$apiRequest['id']])) {
       if (civicrm_error($event->getResponse())) {
@@ -145,15 +160,17 @@ class TransactionSubscriber implements EventSubscriberInterface {
   }
 
   /**
-   * Rollback the pending transaction
+   * Rollback the pending transaction.
    *
    * @param \Civi\API\Event\ExceptionEvent $event
+   *   API exception event.
    */
-  function onApiException(\Civi\API\Event\ExceptionEvent $event) {
+  public function onApiException(\Civi\API\Event\ExceptionEvent $event) {
     $apiRequest = $event->getApiRequest();
     if (isset($this->transactions[$apiRequest['id']])) {
       $this->transactions[$apiRequest['id']]->rollback();
       unset($this->transactions[$apiRequest['id']]);
     }
   }
+
 }