Merge pull request #27275 from colemanw/isDefined

EntityLookupTrait - Add isDefined and getDefinition methods
civicrm · Sep 4, 2023 · 63449bc · 63449bc
2 parents 3678a37 + 1e7d04f
commit 63449bc
Show file tree

Hide file tree

Showing 2 changed files with 34 additions and 7 deletions.
diff --git a/Civi/API/EntityLookupTrait.php b/Civi/API/EntityLookupTrait.php
@@ -44,6 +44,26 @@ protected function define(string $apiEntityName, string $nickname, array $identi
     $this->entityLookupValues[$nickname] = [];
   }
 
+  /**
+   * Check if an entity can be looked up
+   *
+   * @param string $nickname
+   * @return bool
+   */
+  public function isDefined(string $nickname): bool {
+    return !is_null($this->getDefinition($nickname));
+  }
+
+  /**
+   * Retrieve entity definition (entityName string, identifier [keys/values])
+   *
+   * @param string $nickname
+   * @return array{entityName: string, identifier: array}|null
+   */
+  protected function getDefinition(string $nickname): ?array {
+    return $this->entityLookupDefinitions[$nickname] ?? NULL;
+  }
+
   /**
    * Retrieve a field value for a defined entity
    *
@@ -54,31 +74,31 @@ protected function define(string $apiEntityName, string $nickname, array $identi
    * @throws \CRM_Core_Exception
    */
   public function lookup(string $nickname, string $fieldName) {
-    if (!isset($this->entityLookupValues[$nickname])) {
+    $definition = $this->getDefinition($nickname);
+    if (!$definition) {
       throw new \CRM_Core_Exception(sprintf('Cannot lookup entity "%s" before it has been defined.', $nickname));
     }
     // Simply return an id - no need for any queries
-    if (isset($this->entityLookupDefinitions[$nickname]['identifier'][$fieldName])) {
-      return $this->entityLookupDefinitions[$nickname]['identifier'][$fieldName];
+    if (isset($definition['identifier'][$fieldName])) {
+      return $definition['identifier'][$fieldName];
     }
     // Return stored value from previous lookup
     if (array_key_exists($fieldName, $this->entityLookupValues[$nickname])) {
       return $this->entityLookupValues[$nickname][$fieldName];
     }
-    $entityName = $this->entityLookupDefinitions[$nickname]['entityName'];
     $params = [
       'select' => [$fieldName],
       'where' => [],
       'checkPermissions' => FALSE,
     ];
-    foreach ($this->entityLookupDefinitions[$nickname]['identifier'] as $key => $val) {
+    foreach ($definition['identifier'] as $key => $val) {
       $params['where'][] = [$key, '=', $val];
     }
     // Initial load - prefetch all core fields to reduce # of subsequent queries
     if (!$this->entityLookupValues[$nickname]) {
       $params['select'][] = '*';
       // Contact email is commonly needed by forms so prefetch it as well
-      if ($entityName === 'Contact') {
+      if ($definition['entityName'] === 'Contact') {
         $params['select'][] = 'email_primary.*';
       }
     }
@@ -88,7 +108,7 @@ public function lookup(string $nickname, string $fieldName) {
       $parts[count($parts) - 1] = '*';
       $params['select'][] = implode('.', $parts);
     }
-    $retrieved = civicrm_api4($entityName, 'get', $params)->single();
+    $retrieved = civicrm_api4($definition['entityName'], 'get', $params)->single();
     $this->entityLookupValues[$nickname] += $retrieved;
     return $this->entityLookupValues[$nickname][$fieldName] ?? NULL;
   }

diff --git a/tests/phpunit/Civi/API/EntityLookupTest.php b/tests/phpunit/Civi/API/EntityLookupTest.php
@@ -9,10 +9,17 @@ public function testLookupContacts() {
     $bob = $this->createTestEntity('Contact', ['first_name' => 'Bob', 'last_name' => 'One', 'gender_id:name' => 'Male', 'email_primary.email' => 'bob@one.test']);
     $jan = $this->createTestEntity('Contact', ['first_name' => 'Jan', 'last_name' => 'Two', 'gender_id:name' => 'Female', 'external_identifier' => uniqid()]);
     $this->define('Contact', 'Bob', ['id' => $bob['id']]);
+    $this->assertFalse($this->isDefined('Jan'));
     $this->define('Contact', 'Jan', ['external_identifier' => $jan['external_identifier']]);
+    $this->assertTrue($this->isDefined('Jan'));
+    $this->assertEquals($bob['id'], $this->getDefinition('Bob')['identifier']['id']);
+    $this->assertEquals('Contact', $this->getDefinition('Jan')['entityName']);
+    $this->assertNull($this->getDefinition('Jim'));
+    $this->assertFalse($this->isDefined('Jim'));
     $this->assertEquals('One', $this->lookup('Bob', 'last_name'));
     $this->assertEquals('bob@one.test', $this->lookup('Bob', 'email_primary.email'));
     $this->assertEquals('Male', $this->lookup('Bob', 'gender_id:name'));
+    $this->assertEquals($jan['id'], $this->lookup('Jan', 'id'));
     $this->assertEquals('Two', $this->lookup('Jan', 'last_name'));
     $this->assertEquals('Female', $this->lookup('Jan', 'gender_id:name'));
   }