Civi/Test/Api3TestTrait.php

   1 <?php
   2
   3 namespace Civi\Test;
   4
   5 use Civi\API\Exception\NotImplementedException;
   6
   7 require_once 'api/v3/utils.php';
   8 /**
   9  * Class Api3TestTrait
  10  * @package Civi\Test
  11  *
  12  * This trait defines a number of helper functions for testing APIv3. Commonly
  13  * used helpers include `callAPISuccess()`, `callAPIFailure()`,
  14  * `assertAPISuccess()`, and `assertAPIFailure()`.
  15  *
  16  * This trait is intended for use with PHPUnit-based test cases.
  17  */
  18 trait Api3TestTrait {
  19
  20   /**
  21    * Get the api versions to test.
  22    *
  23    * @return array
  24    */
  25   public function versionThreeAndFour() {
  26     return [[3], [4]];
  27   }
  28
  29   /**
  30    * Api version - easier to override than just a define
  31    * @var int
  32    */
  33   protected $_apiversion = 3;
  34
  35   /**
  36    * Check that api returned 'is_error' => 1
  37    * else provide full message
  38    * @param array $result
  39    * @param $expected
  40    * @param array $valuesToExclude
  41    * @param string $prefix
  42    *   Extra test to add to message.
  43    */
  44   public function assertAPIArrayComparison($result, $expected, $valuesToExclude = [], $prefix = '') {
  45     $valuesToExclude = array_merge($valuesToExclude, ['debug', 'xdebug', 'sequential']);
  46     foreach ($valuesToExclude as $value) {
  47       if (isset($result[$value])) {
  48         unset($result[$value]);
  49       }
  50       if (isset($expected[$value])) {
  51         unset($expected[$value]);
  52       }
  53     }
  54     $this->assertEquals($result, $expected, "api result array comparison failed " . $prefix . print_r($result, TRUE) . ' was compared to ' . print_r($expected, TRUE));
  55   }
  56
  57   /**
  58    * Check that a deleted item has been deleted.
  59    *
  60    * @param $entity
  61    * @param $id
  62    */
  63   public function assertAPIDeleted($entity, $id) {
  64     $this->callAPISuccess($entity, 'getcount', ['id' => $id], 0);
  65   }
  66
  67   /**
  68    * Check that api returned 'is_error' => 1.
  69    *
  70    * @param array $apiResult
  71    *   Api result.
  72    * @param string $prefix
  73    *   Extra test to add to message.
  74    * @param null $expectedError
  75    */
  76   public function assertAPIFailure($apiResult, $prefix = '', $expectedError = NULL) {
  77     if (!empty($prefix)) {
  78       $prefix .= ': ';
  79     }
  80     if ($expectedError && !empty($apiResult['is_error'])) {
  81       $this->assertContains($expectedError, $apiResult['error_message'], 'api error message not as expected' . $prefix);
  82     }
  83     $this->assertEquals(1, $apiResult['is_error'], "api call should have failed but it succeeded " . $prefix . (print_r($apiResult, TRUE)));
  84     $this->assertNotEmpty($apiResult['error_message']);
  85   }
  86
  87   /**
  88    * Check that api returned 'is_error' => 0.
  89    *
  90    * @param array $apiResult
  91    *   Api result.
  92    * @param string $prefix
  93    *   Extra test to add to message.
  94    */
  95   public function assertAPISuccess($apiResult, $prefix = '') {
  96     if (!empty($prefix)) {
  97       $prefix .= ': ';
  98     }
  99     $errorMessage = empty($apiResult['error_message']) ? '' : " " . $apiResult['error_message'];
 100
 101     if (!empty($apiResult['debug_information'])) {
 102       $errorMessage .= "\n " . print_r($apiResult['debug_information'], TRUE);
 103     }
 104     if (!empty($apiResult['trace'])) {
 105       $errorMessage .= "\n" . print_r($apiResult['trace'], TRUE);
 106     }
 107     $this->assertEmpty($apiResult['is_error'] ?? NULL, $prefix . $errorMessage);
 108   }
 109
 110   /**
 111    * This function exists to wrap api functions.
 112    * so we can ensure they fail where expected & throw exceptions without litterering the test with checks
 113    * @param string $entity
 114    * @param string $action
 115    * @param array $params
 116    * @param string $expectedErrorMessage
 117    *   Error.
 118    * @param null $extraOutput
 119    * @return array|int
 120    */
 121   public function callAPIFailure($entity, $action, $params, $expectedErrorMessage = NULL, $extraOutput = NULL) {
 122     if (is_array($params)) {
 123       $params += [
 124         'version' => $this->_apiversion,
 125       ];
 126     }
 127     $result = $this->civicrm_api($entity, $action, $params);
 128     $this->assertAPIFailure($result, "We expected a failure for $entity $action but got a success", $expectedErrorMessage);
 129     return $result;
 130   }
 131
 132   /**
 133    * wrap api functions.
 134    * so we can ensure they succeed & throw exceptions without litterering the test with checks
 135    *
 136    * @param string $entity
 137    * @param string $action
 138    * @param array $params
 139    * @param mixed $checkAgainst
 140    *   Optional value to check result against, implemented for getvalue,.
 141    *   getcount, getsingle. Note that for getvalue the type is checked rather than the value
 142    *   for getsingle the array is compared against an array passed in - the id is not compared (for
 143    *   better or worse )
 144    *
 145    * @return array|int
 146    *
 147    * @throws \CRM_Core_Exception
 148    */
 149   public function callAPISuccess($entity, $action, $params = [], $checkAgainst = NULL) {
 150     $params = array_merge([
 151       'version' => $this->_apiversion,
 152       'debug' => 1,
 153     ],
 154       $params
 155     );
 156     switch (strtolower($action)) {
 157       case 'getvalue':
 158         return $this->callAPISuccessGetValue($entity, $params, $checkAgainst);
 159
 160       case 'getsingle':
 161         return $this->callAPISuccessGetSingle($entity, $params, $checkAgainst);
 162
 163       case 'getcount':
 164         return $this->callAPISuccessGetCount($entity, $params, $checkAgainst);
 165     }
 166     $result = $this->civicrm_api($entity, $action, $params);
 167     $this->assertAPISuccess($result, "Failure in api call for $entity $action");
 168     return $result;
 169   }
 170
 171   /**
 172    * This function exists to wrap api getValue function & check the result
 173    * so we can ensure they succeed & throw exceptions without litterering the test with checks
 174    * There is a type check in this
 175    *
 176    * @param string $entity
 177    * @param array $params
 178    * @param int $count
 179    *
 180    * @throws \CRM_Core_Exception
 181    *
 182    * @return array|int
 183    */
 184   public function callAPISuccessGetCount($entity, $params, $count = NULL) {
 185     $params += [
 186       'version' => $this->_apiversion,
 187       'debug' => 1,
 188     ];
 189     $result = $this->civicrm_api($entity, 'getcount', $params);
 190     if (!is_int($result) || !empty($result['is_error']) || isset($result['values'])) {
 191       throw new \CRM_Core_Exception('Invalid getcount result : ' . print_r($result, TRUE) . " type :" . gettype($result));
 192     }
 193     if (is_int($count)) {
 194       $this->assertEquals($count, $result, "incorrect count returned from $entity getcount");
 195     }
 196     return $result;
 197   }
 198
 199   /**
 200    * This function exists to wrap api getsingle function & check the result
 201    * so we can ensure they succeed & throw exceptions without litterering the test with checks
 202    *
 203    * @param string $entity
 204    * @param array $params
 205    * @param array $checkAgainst
 206    *   Array to compare result against.
 207    *   - boolean
 208    *   - integer
 209    *   - double
 210    *   - string
 211    *   - array
 212    *   - object
 213    *
 214    * @throws \CRM_Core_Exception
 215    *
 216    * @return array|int
 217    */
 218   public function callAPISuccessGetSingle($entity, $params, $checkAgainst = NULL) {
 219     $params += [
 220       'version' => $this->_apiversion,
 221     ];
 222     $result = $this->civicrm_api($entity, 'getsingle', $params);
 223     if (!is_array($result) || !empty($result['is_error']) || isset($result['values'])) {
 224       $unfilteredResult = $this->civicrm_api($entity, 'get', ['version' => $this->_apiversion]);
 225       throw new \CRM_Core_Exception(
 226         'Invalid getsingle result' . print_r($result, TRUE)
 227         . "\n entity: $entity . \n params \n " . print_r($params, TRUE)
 228         . "\n entities retrieved with blank params \n" . print_r($unfilteredResult, TRUE)
 229       );
 230     }
 231     if ($checkAgainst) {
 232       // @todo - have gone with the fn that unsets id? should we check id?
 233       $this->checkArrayEquals($result, $checkAgainst);
 234     }
 235     return $result;
 236   }
 237
 238   /**
 239    * This function exists to wrap api getValue function & check the result
 240    * so we can ensure they succeed & throw exceptions without litterering the test with checks
 241    * There is a type check in this
 242    *
 243    * @param string $entity
 244    * @param array $params
 245    * @param string $type
 246    *   Per http://php.net/manual/en/function.gettype.php possible types.
 247    *   - boolean
 248    *   - integer
 249    *   - double
 250    *   - string
 251    *   - array
 252    *   - object
 253    *
 254    * @return array|int
 255    * @throws \CRM_Core_Exception
 256    */
 257   public function callAPISuccessGetValue($entity, $params, $type = NULL) {
 258     $params += [
 259       'version' => $this->_apiversion,
 260       'debug' => 1,
 261     ];
 262     $result = $this->civicrm_api($entity, 'getvalue', $params);
 263     if (is_array($result) && (!empty($result['is_error']) || isset($result['values']))) {
 264       throw new \CRM_Core_Exception('Invalid getvalue result' . print_r($result, TRUE));
 265     }
 266     if ($type) {
 267       if ($type === 'integer') {
 268         // api seems to return integers as strings
 269         $this->assertTrue(is_numeric($result), "expected a numeric value but got " . print_r($result, 1));
 270       }
 271       else {
 272         $this->assertType($type, $result, "returned result should have been of type $type but was ");
 273       }
 274     }
 275     return $result;
 276   }
 277
 278   /**
 279    * A stub for the API interface. This can be overriden by subclasses to change how the API is called.
 280    *
 281    * @param $entity
 282    * @param $action
 283    * @param array $params
 284    * @return array|int
 285    */
 286   public function civicrm_api($entity, $action, $params = []) {
 287     if (($params['version'] ?? 0) == 4) {
 288       return $this->runApi4Legacy($entity, $action, $params);
 289     }
 290     return civicrm_api($entity, $action, $params);
 291   }
 292
 293   /**
 294    * Emulate v3 syntax so we can run api3 tests on v4
 295    *
 296    * @param $v3Entity
 297    * @param $v3Action
 298    * @param array $v3Params
 299    * @return array|int
 300    * @throws \API_Exception
 301    * @throws \CiviCRM_API3_Exception
 302    * @throws \Exception
 303    */
 304   public function runApi4Legacy($v3Entity, $v3Action, $v3Params = []) {
 305     $v4Entity = \CRM_Core_DAO_AllCoreTables::convertEntityNameToCamel($v3Entity);
 306     $v4Action = $v3Action = strtolower($v3Action);
 307     $v4Params = ['checkPermissions' => isset($v3Params['check_permissions']) ? (bool) $v3Params['check_permissions'] : FALSE];
 308     $sequential = !empty($v3Params['sequential']);
 309     $options = \_civicrm_api3_get_options_from_params($v3Params, in_array($v4Entity, ['Contact', 'Participant', 'Event', 'Group', 'Contribution', 'Membership']));
 310     $indexBy = in_array($v3Action, ['get', 'create', 'replace']) && !$sequential ? 'id' : NULL;
 311     $onlyId = !empty($v3Params['format.only_id']);
 312     $onlySuccess = !empty($v3Params['format.is_success']);
 313     if (!empty($v3Params['filters']['is_current']) || !empty($v3Params['isCurrent'])) {
 314       $v4Params['current'] = TRUE;
 315     }
 316     $language = $v3Params['options']['language'] ?? $v3Params['option.language'] ?? NULL;
 317     if ($language) {
 318       $v4Params['language'] = $language;
 319     }
 320     $toRemove = ['option.', 'return', 'api.', 'format.'];
 321     $chains = $joins = $custom = [];
 322     foreach ($v3Params as $key => $val) {
 323       foreach ($toRemove as $remove) {
 324         if (strpos($key, $remove) === 0) {
 325           if ($remove == 'api.') {
 326             $chains[$key] = $val;
 327           }
 328           unset($v3Params[$key]);
 329         }
 330       }
 331     }
 332
 333     $v3Fields = civicrm_api3($v3Entity, 'getfields', ['action' => $v3Action])['values'];
 334
 335     // Fix 'null'
 336     foreach ($v3Params as $key => $val) {
 337       if ($val === 'null') {
 338         $v3Params[$key] = NULL;
 339       }
 340     }
 341
 342     if ($v4Entity == 'Setting') {
 343       $indexBy = NULL;
 344       $v4Params['domainId'] = $v3Params['domain_id'] ?? NULL;
 345       if ($v3Action == 'getfields') {
 346         if (!empty($v3Params['name'])) {
 347           $v3Params['filters']['name'] = $v3Params['name'];
 348         }
 349         foreach ($v3Params['filters'] ?? [] as $filter => $val) {
 350           $v4Params['where'][] = [$filter, '=', $val];
 351         }
 352       }
 353       if ($v3Action == 'create') {
 354         $v4Action = 'set';
 355       }
 356       if ($v3Action == 'revert') {
 357         $v4Params['select'] = (array) $v3Params['name'];
 358       }
 359       if ($v3Action == 'getvalue') {
 360         $options['return'] = [$v3Params['name'] => 1];
 361         $v3Params = [];
 362       }
 363       \CRM_Utils_Array::remove($v3Params, 'domain_id', 'name');
 364     }
 365
 366     \CRM_Utils_Array::remove($v3Params, 'options', 'debug', 'version', 'sort', 'offset', 'rowCount', 'check_permissions', 'sequential', 'filters', 'isCurrent');
 367
 368     // Work around ugly hack in v3 Domain api
 369     if ($v4Entity == 'Domain') {
 370       $v3Fields['version'] = ['name' => 'version', 'api.aliases' => ['domain_version']];
 371       unset($v3Fields['domain_version']);
 372     }
 373
 374     foreach ($v3Fields as $name => $field) {
 375       // Resolve v3 aliases
 376       foreach ($field['api.aliases'] ?? [] as $alias) {
 377         if (isset($v3Params[$alias])) {
 378           $v3Params[$field['name']] = $v3Params[$alias];
 379           unset($v3Params[$alias]);
 380         }
 381       }
 382       // Convert custom field names
 383       if (strpos($name, 'custom_') === 0 && is_numeric($name[7])) {
 384         // Strictly speaking, using titles instead of names is incorrect, but it works for
 385         // unit tests where names and titles are identical and saves an extra db lookup.
 386         $custom[$field['groupTitle']][$field['title']] = $name;
 387         $v4FieldName = $field['groupTitle'] . '.' . $field['title'];
 388         if (isset($v3Params[$name])) {
 389           $v3Params[$v4FieldName] = $v3Params[$name];
 390           unset($v3Params[$name]);
 391         }
 392         if (isset($options['return'][$name])) {
 393           $options['return'][$v4FieldName] = 1;
 394           unset($options['return'][$name]);
 395         }
 396       }
 397
 398       if ($name === 'option_group_id' && isset($v3Params[$name]) && !is_numeric($v3Params[$name])) {
 399         // This is a per field hack (bad) but we can't solve everything at once
 400         // & a cleverer way turned out to be too much for this round.
 401         // Being in the test class it's tested....
 402         $v3Params['option_group.name'] = $v3Params['option_group_id'];
 403         unset($v3Params['option_group_id']);
 404       }
 405     }
 406
 407     switch ($v3Action) {
 408       case 'getcount':
 409         $v4Params['select'] = ['row_count'];
 410         // No break - keep processing as get
 411       case 'getsingle':
 412       case 'getvalue':
 413         $v4Action = 'get';
 414         // No break - keep processing as get
 415       case 'get':
 416         if ($options['return'] && $v3Action !== 'getcount') {
 417           $v4Params['select'] = array_keys($options['return']);
 418           // Ensure id field is returned as v3 always expects it
 419           if ($v4Entity != 'Setting' && !in_array('id', $v4Params['select'])) {
 420             $v4Params['select'][] = 'id';
 421           }
 422           // Convert join syntax
 423           foreach ($v4Params['select'] as &$select) {
 424             if (strstr($select, '_id.')) {
 425               $joins[$select] = explode('.', str_replace('_id.', '.', $select));
 426               $select = str_replace('_id.', '.', $select);
 427             }
 428           }
 429         }
 430         if ($options['limit'] && $v4Entity != 'Setting') {
 431           $v4Params['limit'] = $options['limit'];
 432         }
 433         if ($options['offset']) {
 434           $v4Params['offset'] = $options['offset'];
 435         }
 436         if ($options['sort']) {
 437           foreach (explode(',', $options['sort']) as $sort) {
 438             list($sortField, $sortDir) = array_pad(explode(' ', trim($sort)), 2, 'ASC');
 439             $v4Params['orderBy'][$sortField] = $sortDir;
 440           }
 441         }
 442         break;
 443
 444       case 'replace':
 445         if (empty($v3Params['values'])) {
 446           $v4Action = 'delete';
 447         }
 448         else {
 449           $v4Params['records'] = $v3Params['values'];
 450         }
 451         unset($v3Params['values']);
 452         break;
 453
 454       case 'create':
 455       case 'update':
 456         if (!empty($v3Params['id'])) {
 457           $v4Action = 'update';
 458           $v4Params['where'][] = ['id', '=', $v3Params['id']];
 459         }
 460
 461         $v4Params['values'] = $v3Params;
 462         unset($v4Params['values']['id']);
 463         break;
 464
 465       case 'delete':
 466         if (isset($v3Params['id'])) {
 467           $v4Params['where'][] = ['id', '=', $v3Params['id']];
 468         }
 469         break;
 470
 471       case 'getoptions':
 472         $indexBy = 0;
 473         $v4Action = 'getFields';
 474         $v4Params += [
 475           'where' => [['name', '=', $v3Params['field']]],
 476           'loadOptions' => TRUE,
 477         ];
 478         break;
 479
 480       case 'getfields':
 481         $v4Action = 'getFields';
 482         if (!empty($v3Params['action']) || !empty($v3Params['api_action'])) {
 483           $v4Params['action'] = !empty($v3Params['action']) ? $v3Params['action'] : $v3Params['api_action'];
 484         }
 485         $indexBy = !$sequential ? 'name' : NULL;
 486         break;
 487     }
 488
 489     // Ensure this api4 entity/action exists
 490     try {
 491       $actionInfo = \civicrm_api4($v4Entity, 'getActions', ['checkPermissions' => FALSE, 'where' => [['name', '=', $v4Action]]]);
 492     }
 493     catch (NotImplementedException $e) {
 494       // For now we'll mark the test incomplete if a v4 entity doesn't exit yet
 495       $this->markTestIncomplete($e->getMessage());
 496     }
 497     if (!isset($actionInfo[0])) {
 498       throw new \Exception("Api4 $v4Entity $v4Action does not exist.");
 499     }
 500
 501     // Migrate special params like fix_address
 502     foreach ($actionInfo[0]['params'] as $v4ParamName => $paramInfo) {
 503       // camelCase in api4, lower_case in api3
 504       $v3ParamName = strtolower(preg_replace('/(?=[A-Z])/', '_$0', $v4ParamName));
 505       if (isset($v3Params[$v3ParamName])) {
 506         $v4Params[$v4ParamName] = $v3Params[$v3ParamName];
 507         unset($v3Params[$v3ParamName]);
 508         if ($paramInfo['type'][0] == 'bool') {
 509           $v4Params[$v4ParamName] = (bool) $v4Params[$v4ParamName];
 510         }
 511       }
 512     }
 513
 514     // Build where clause for 'getcount', 'getsingle', 'getvalue', 'get' & 'replace'
 515     if ($v4Action == 'get' || $v3Action == 'replace') {
 516       foreach ($v3Params as $key => $val) {
 517         $op = '=';
 518         if (is_array($val) && count($val) == 1 && array_intersect_key($val, array_flip(\CRM_Core_DAO::acceptedSQLOperators()))) {
 519           foreach ($val as $op => $newVal) {
 520             $val = $newVal;
 521           }
 522         }
 523         $v4Params['where'][] = [$key, $op, $val];
 524       }
 525     }
 526
 527     try {
 528       $result = \civicrm_api4($v4Entity, $v4Action, $v4Params, $indexBy);
 529     }
 530     catch (\Exception $e) {
 531       return $onlySuccess ? 0 : [
 532         'is_error' => 1,
 533         'error_message' => $e->getMessage(),
 534         'version' => 4,
 535       ];
 536     }
 537
 538     if (($v3Action == 'getsingle' || $v3Action == 'getvalue' || $v3Action == 'delete') && count($result) != 1) {
 539       return $onlySuccess ? 0 : [
 540         'is_error' => 1,
 541         'error_message' => "Expected one $v4Entity but found " . count($result),
 542         'count' => count($result),
 543       ];
 544     }
 545
 546     if ($onlySuccess) {
 547       return 1;
 548     }
 549
 550     if ($v3Action == 'getcount') {
 551       return $result->count();
 552     }
 553
 554     if ($onlyId) {
 555       return $result->first()['id'];
 556     }
 557
 558     if ($v3Action == 'getvalue' && $v4Entity == 'Setting') {
 559       return $result->first()['value'] ?? NULL;
 560     }
 561
 562     if ($v3Action == 'getvalue') {
 563       $returnKey = array_keys($options['return'])[0];
 564       return $result->first()[$returnKey] ?? NULL;
 565     }
 566
 567     // Mimic api3 behavior when using 'replace' action to delete all
 568     if ($v3Action == 'replace' && $v4Action == 'delete') {
 569       $result->exchangeArray([]);
 570     }
 571
 572     if ($v3Action == 'getoptions') {
 573       return [
 574         'is_error' => 0,
 575         'count' => $result['options'] ? count($result['options']) : 0,
 576         'values' => $result['options'] ?: [],
 577         'version' => 4,
 578       ];
 579     }
 580
 581     // Emulate the weird return format of api3 settings
 582     if (($v3Action == 'get' || $v3Action == 'create') && $v4Entity == 'Setting') {
 583       $settings = [];
 584       foreach ($result as $item) {
 585         $settings[$item['domain_id']][$item['name']] = $item['value'];
 586       }
 587       $result->exchangeArray($sequential ? array_values($settings) : $settings);
 588     }
 589
 590     foreach ($result as $index => $row) {
 591       // Run chains
 592       foreach ($chains as $key => $params) {
 593         $result[$index][$key] = $this->runApi4LegacyChain($key, $params, $v4Entity, $row, $sequential);
 594       }
 595       // Convert join format
 596       foreach ($joins as $api3Key => $api4Path) {
 597         $result[$index][$api3Key] = \CRM_Utils_Array::pathGet($result[$index], $api4Path);
 598       }
 599       // Resolve custom field names
 600       foreach ($custom as $group => $fields) {
 601         foreach ($fields as $field => $v3FieldName) {
 602           if (isset($row["$group.$field"])) {
 603             $result[$index][$v3FieldName] = $row["$group.$field"];
 604             unset($result[$index]["$group.$field"]);
 605           }
 606         }
 607       }
 608     }
 609
 610     if ($v3Action == 'getsingle') {
 611       return $result->first();
 612     }
 613
 614     return [
 615       'is_error' => 0,
 616       'version' => 4,
 617       'count' => count($result),
 618       'values' => (array) $result,
 619       'id' => is_object($result) && count($result) == 1 ? ($result->first()['id'] ?? NULL) : NULL,
 620     ];
 621   }
 622
 623   /**
 624    * @param string $key
 625    * @param mixed $params
 626    * @param string $mainEntity
 627    * @param array $result
 628    * @param bool $sequential
 629    * @return array
 630    * @throws \API_Exception
 631    */
 632   protected function runApi4LegacyChain($key, $params, $mainEntity, $result, $sequential) {
 633     // Handle an array of multiple calls using recursion
 634     if (is_array($params) && isset($params[0]) && is_array($params[0])) {
 635       $results = [];
 636       foreach ($params as $chain) {
 637         $results[] = $this->runApi4LegacyChain($key, $chain, $mainEntity, $result, $sequential);
 638       }
 639       return $results;
 640     }
 641
 642     // Handle single api call
 643     list(, $chainEntity, $chainAction) = explode('.', $key);
 644     $lcChainEntity = \CRM_Core_DAO_AllCoreTables::convertEntityNameToLower($chainEntity);
 645     $chainEntity = \CRM_Core_DAO_AllCoreTables::convertEntityNameToCamel($chainEntity);
 646     $lcMainEntity = \CRM_Core_DAO_AllCoreTables::convertEntityNameToLower($mainEntity);
 647     $params = is_array($params) ? $params : [];
 648
 649     // Api3 expects this to be inherited
 650     $params += ['sequential' => $sequential];
 651
 652     // Replace $value.field_name
 653     foreach ($params as $name => $param) {
 654       if (is_string($param) && strpos($param, '$value.') === 0) {
 655         $param = substr($param, 7);
 656         $params[$name] = $result[$param] ?? NULL;
 657       }
 658     }
 659
 660     try {
 661       $getFields = civicrm_api4($chainEntity, 'getFields', ['select' => ['name']], 'name');
 662     }
 663     catch (NotImplementedException $e) {
 664       $this->markTestIncomplete($e->getMessage());
 665     }
 666
 667     // Emulate the string-fu guesswork that api3 does
 668     if ($chainEntity == $mainEntity && empty($params['id']) &&  !empty($result['id'])) {
 669       $params['id'] = $result['id'];
 670     }
 671     elseif (empty($params['id']) && !empty($result[$lcChainEntity . '_id'])) {
 672       $params['id'] = $result[$lcChainEntity . '_id'];
 673     }
 674     elseif (!empty($result['id']) && isset($getFields[$lcMainEntity . '_id']) && empty($params[$lcMainEntity . '_id'])) {
 675       $params[$lcMainEntity . '_id'] = $result['id'];
 676     }
 677     return $this->runApi4Legacy($chainEntity, $chainAction, $params);
 678   }
 679
 680 }