Civi/API/Subscriber/ChainSubscriber.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  * The ChainSubscriber looks for API parameters which specify a nested or
  19  * chained API call. For example:
  20  *
  21  * @code
  22  * $result = civicrm_api('Contact', 'create', array(
  23  *   'version' => 3,
  24  *   'first_name' => 'Amy',
  25  *   'api.Email.create' => array(
  26  *     'email' => 'amy@example.com',
  27  *     'location_type_id' => 123,
  28  *   ),
  29  * ));
  30  * @endcode
  31  *
  32  * The ChainSubscriber looks for any parameters of the form "api.Email.create";
  33  * if found, it issues the nested API call (and passes some extra context --
  34  * eg Amy's contact_id).
  35  */
  36 class ChainSubscriber implements EventSubscriberInterface {
  37
  38   /**
  39    * @return array
  40    */
  41   public static function getSubscribedEvents() {
  42     return [
  43       Events::RESPOND => ['onApiRespond', Events::W_EARLY],
  44     ];
  45   }
  46
  47   /**
  48    * @param \Civi\API\Event\RespondEvent $event
  49    *   API response event.
  50    *
  51    * @throws \Exception
  52    */
  53   public function onApiRespond(\Civi\API\Event\RespondEvent $event) {
  54     $apiRequest = $event->getApiRequest();
  55     if ($apiRequest['version'] < 4) {
  56       $result = $event->getResponse();
  57       if (is_array($result) && empty($result['is_error'])) {
  58         $this->callNestedApi($event->getApiKernel(), $apiRequest['params'], $result, $apiRequest['action'], $apiRequest['entity'], $apiRequest['version']);
  59         $event->setResponse($result);
  60       }
  61     }
  62   }
  63
  64   /**
  65    * Call any nested api calls.
  66    *
  67    * TODO: We don't really need this to be a separate function.
  68    * @param \Civi\API\Kernel $apiKernel
  69    * @param $params
  70    * @param $result
  71    * @param $action
  72    * @param $entity
  73    * @param $version
  74    * @throws \Exception
  75    */
  76   protected function callNestedApi($apiKernel, &$params, &$result, $action, $entity, $version) {
  77     $lowercase_entity = _civicrm_api_get_entity_name_from_camel($entity);
  78
  79     // We don't need to worry about nested api in the getfields/getoptions
  80     // actions, so just return immediately.
  81     if (in_array($action, ['getfields', 'getfield', 'getoptions'])) {
  82       return;
  83     }
  84
  85     if ($action == 'getsingle') {
  86       // I don't understand the protocol here, but we don't want
  87       // $result to be a recursive array
  88       // $result['values'][0] = $result;
  89       $oldResult = $result;
  90       $result = ['values' => [0 => $oldResult]];
  91     }
  92     foreach ($params as $field => $newparams) {
  93       if ((is_array($newparams) || $newparams === 1) && $field <> 'api.has_parent' && substr($field, 0, 3) == 'api') {
  94
  95         // 'api.participant.delete' => 1 is a valid options - handle 1
  96         // instead of an array
  97         if ($newparams === 1) {
  98           $newparams = ['version' => $version];
  99         }
 100         // can be api_ or api.
 101         $separator = $field[3];
 102         if (!($separator == '.' || $separator == '_')) {
 103           continue;
 104         }
 105         $subAPI = explode($separator, $field);
 106
 107         $subaction = empty($subAPI[2]) ? $action : $subAPI[2];
 108         $subParams = [
 109           'debug' => $params['debug'] ?? NULL,
 110         ];
 111         $subEntity = _civicrm_api_get_entity_name_from_camel($subAPI[1]);
 112
 113         // Hard coded list of entitys that have fields starting api_ and shouldn't be automatically
 114         // deemed to be chained API calls
 115         $skipList = [
 116           'SmsProvider' => ['type', 'url', 'params'],
 117           'Job' => ['prefix', 'entity', 'action'],
 118           'Contact' => ['key'],
 119         ];
 120         if (isset($skipList[$entity]) && in_array($subEntity, $skipList[$entity])) {
 121           continue;
 122         }
 123
 124         foreach ($result['values'] as $idIndex => $parentAPIValues) {
 125
 126           if ($subEntity != 'contact') {
 127             //contact spits the dummy at activity_id so what else won't it like?
 128             //set entity_id & entity table based on the parent's id & entity.
 129             //e.g for something like note if the parent call is contact
 130             //'entity_table' will be set to 'contact' & 'id' to the contact id
 131             //from the parent call. in this case 'contact_id' will also be
 132             //set to the parent's id
 133             if (!($subEntity == 'line_item' && $lowercase_entity == 'contribution' && $action != 'create')) {
 134               $subParams["entity_id"] = $parentAPIValues['id'];
 135               $subParams['entity_table'] = 'civicrm_' . $lowercase_entity;
 136             }
 137
 138             $addEntityId = TRUE;
 139             if ($subEntity == 'relationship' && $lowercase_entity == 'contact') {
 140               // if a relationship call is chained to a contact call, we need
 141               // to check whether contact_id_a or contact_id_b for the
 142               // relationship is given. If so, don't add an extra subParam
 143               // "contact_id" => parent_id.
 144               // See CRM-16084.
 145               foreach (array_keys($newparams) as $key) {
 146                 if (substr($key, 0, 11) == 'contact_id_') {
 147                   $addEntityId = FALSE;
 148                   break;
 149                 }
 150               }
 151             }
 152             if ($addEntityId) {
 153               $subParams[$lowercase_entity . "_id"] = $parentAPIValues['id'];
 154             }
 155           }
 156           if ($entity != 'Contact' && \CRM_Utils_Array::value(strtolower($subEntity . "_id"), $parentAPIValues)) {
 157             //e.g. if event_id is in the values returned & subentity is event
 158             //then pass in event_id as 'id' don't do this for contact as it
 159             //does some weird things like returning primary email &
 160             //thus limiting the ability to chain email
 161             //TODO - this might need the camel treatment
 162             $subParams['id'] = $parentAPIValues[$subEntity . "_id"];
 163           }
 164
 165           if (\CRM_Utils_Array::value('entity_table', $result['values'][$idIndex]) == $subEntity) {
 166             $subParams['id'] = $result['values'][$idIndex]['entity_id'];
 167           }
 168           // if we are dealing with the same entity pass 'id' through
 169           // (useful for get + delete for example)
 170           if ($lowercase_entity == $subEntity) {
 171             $subParams['id'] = $result['values'][$idIndex]['id'];
 172           }
 173
 174           $subParams['version'] = $version;
 175           if (!empty($params['check_permissions'])) {
 176             $subParams['check_permissions'] = $params['check_permissions'];
 177           }
 178           $subParams['sequential'] = 1;
 179           $subParams['api.has_parent'] = 1;
 180           if (array_key_exists(0, $newparams)) {
 181             $genericParams = $subParams;
 182             // it is a numerically indexed array - ie. multiple creates
 183             foreach ($newparams as $entityparams) {
 184               $subParams = array_merge($genericParams, $entityparams);
 185               _civicrm_api_replace_variables($subParams, $result['values'][$idIndex], $separator);
 186               $result['values'][$idIndex][$field][] = $apiKernel->runSafe($subEntity, $subaction, $subParams);
 187               if ($result['is_error'] === 1) {
 188                 throw new \Exception($subEntity . ' ' . $subaction . 'call failed with' . $result['error_message']);
 189               }
 190             }
 191           }
 192           else {
 193
 194             $subParams = array_merge($subParams, $newparams);
 195             _civicrm_api_replace_variables($subParams, $result['values'][$idIndex], $separator);
 196             $result['values'][$idIndex][$field] = $apiKernel->runSafe($subEntity, $subaction, $subParams);
 197             if (!empty($result['is_error'])) {
 198               throw new \Exception($subEntity . ' ' . $subaction . 'call failed with' . $result['error_message']);
 199             }
 200           }
 201         }
 202       }
 203     }
 204     if ($action == 'getsingle') {
 205       $result = $result['values'][0];
 206     }
 207   }
 208
 209 }