CRM/Core/BAO/EntityTag.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 /**
  13  * This class contains functions for managing Tag(tag) for a contact
  14  *
  15  * @package CRM
  16  * @copyright CiviCRM LLC https://civicrm.org/licensing
  17  */
  18 class CRM_Core_BAO_EntityTag extends CRM_Core_DAO_EntityTag {
  19
  20   /**
  21    * Given a contact id, it returns an array of tag id's the contact belongs to.
  22    *
  23    * @param int $entityID
  24    *   Id of the entity usually the contactID.
  25    * @param string $entityTable
  26    *   Name of the entity table usually 'civicrm_contact'.
  27    *
  28    * @return array
  29    *   reference $tag array of category id's the contact belongs to.
  30    */
  31   public static function getTag($entityID, $entityTable = 'civicrm_contact') {
  32     $tags = [];
  33
  34     $entityTag = new CRM_Core_BAO_EntityTag();
  35     $entityTag->entity_id = $entityID;
  36     $entityTag->entity_table = $entityTable;
  37     $entityTag->find();
  38
  39     while ($entityTag->fetch()) {
  40       $tags[$entityTag->tag_id] = $entityTag->tag_id;
  41     }
  42     return $tags;
  43   }
  44
  45   /**
  46    * Takes an associative array and creates a entityTag object.
  47    *
  48    * the function extract all the params it needs to initialize the create a
  49    * group object. the params array could contain additional unused name/value
  50    * pairs
  51    *
  52    * @param array $params
  53    *   (reference ) an assoc array of name/value pairs.
  54    *
  55    * @return CRM_Core_BAO_EntityTag
  56    */
  57   public static function add(&$params) {
  58     $dataExists = self::dataExists($params);
  59     if (!$dataExists) {
  60       return NULL;
  61     }
  62
  63     $entityTag = new CRM_Core_BAO_EntityTag();
  64     $entityTag->copyValues($params);
  65
  66     // dont save the object if it already exists, CRM-1276
  67     if (!$entityTag->find(TRUE)) {
  68       //invoke pre hook
  69       CRM_Utils_Hook::pre('create', 'EntityTag', $params['tag_id'], $params);
  70
  71       $entityTag->save();
  72
  73       //invoke post hook on entityTag
  74       // we are using this format to keep things consistent between the single and bulk operations
  75       // so a bit different from other post hooks
  76       $object = [0 => [0 => $params['entity_id']], 1 => $params['entity_table']];
  77       CRM_Utils_Hook::post('create', 'EntityTag', $params['tag_id'], $object);
  78     }
  79     return $entityTag;
  80   }
  81
  82   /**
  83    * Check if there is data to create the object.
  84    *
  85    * @param array $params
  86    *   An assoc array of name/value pairs.
  87    *
  88    * @return bool
  89    */
  90   public static function dataExists($params) {
  91     return !($params['tag_id'] == 0);
  92   }
  93
  94   /**
  95    * Delete the tag for a contact.
  96    *
  97    * @param array $params
  98    *   (reference ) an assoc array of name/value pairs.
  99    */
 100   public static function del(&$params) {
 101     //invoke pre hook
 102     if (!empty($params['tag_id'])) {
 103       CRM_Utils_Hook::pre('delete', 'EntityTag', $params['tag_id'], $params);
 104     }
 105
 106     $entityTag = new CRM_Core_BAO_EntityTag();
 107     $entityTag->copyValues($params);
 108     $entityTag->delete();
 109
 110     //invoke post hook on entityTag
 111     if (!empty($params['tag_id'])) {
 112       $object = [0 => [0 => $params['entity_id']], 1 => $params['entity_table']];
 113       CRM_Utils_Hook::post('delete', 'EntityTag', $params['tag_id'], $object);
 114     }
 115   }
 116
 117   /**
 118    * Given an array of entity ids and entity table, add all the entity to the tags.
 119    *
 120    * @param array $entityIds
 121    *   (reference ) the array of entity ids to be added.
 122    * @param int $tagId
 123    *   The id of the tag.
 124    * @param string $entityTable
 125    *   Name of entity table default:civicrm_contact.
 126    * @param bool $applyPermissions
 127    *   Should permissions be applied in this function.
 128    *
 129    * @return array
 130    *   (total, added, notAdded) count of entities added to tag
 131    */
 132   public static function addEntitiesToTag(&$entityIds, $tagId, $entityTable, $applyPermissions) {
 133     $numEntitiesAdded = 0;
 134     $numEntitiesNotAdded = 0;
 135     $entityIdsAdded = [];
 136
 137     //invoke pre hook for entityTag
 138     $preObject = [$entityIds, $entityTable];
 139     CRM_Utils_Hook::pre('create', 'EntityTag', $tagId, $preObject);
 140
 141     foreach ($entityIds as $entityId) {
 142       // CRM-17350 - check if we have permission to edit the contact
 143       // that this tag belongs to.
 144       if ($applyPermissions && !self::checkPermissionOnEntityTag($entityId, $entityTable)) {
 145         $numEntitiesNotAdded++;
 146         continue;
 147       }
 148       $tag = new CRM_Core_DAO_EntityTag();
 149
 150       $tag->entity_id = $entityId;
 151       $tag->tag_id = $tagId;
 152       $tag->entity_table = $entityTable;
 153       if (!$tag->find()) {
 154         $tag->save();
 155         $entityIdsAdded[] = $entityId;
 156         $numEntitiesAdded++;
 157       }
 158       else {
 159         $numEntitiesNotAdded++;
 160       }
 161     }
 162
 163     //invoke post hook on entityTag
 164     $object = [$entityIdsAdded, $entityTable];
 165     CRM_Utils_Hook::post('create', 'EntityTag', $tagId, $object);
 166
 167     CRM_Contact_BAO_GroupContactCache::opportunisticCacheFlush();
 168
 169     return [count($entityIds), $numEntitiesAdded, $numEntitiesNotAdded];
 170   }
 171
 172   /**
 173    * Basic check for ACL permission on editing/creating/removing a tag.
 174    *
 175    * In the absence of something better contacts get a proper check and other entities
 176    * default to 'edit all contacts'. This is currently only accessed from the api which previously
 177    * applied edit all contacts to all - so while still too restrictive it represents a loosening.
 178    *
 179    * Current possible entities are attachments, activities, cases & contacts.
 180    *
 181    * @param int $entityID
 182    * @param string $entityTable
 183    *
 184    * @return bool
 185    */
 186   public static function checkPermissionOnEntityTag($entityID, $entityTable) {
 187     if ($entityTable == 'civicrm_contact') {
 188       return CRM_Contact_BAO_Contact_Permission::allow($entityID, CRM_Core_Permission::EDIT);
 189     }
 190     else {
 191       return CRM_Core_Permission::check('edit all contacts');
 192     }
 193   }
 194
 195   /**
 196    * Given an array of entity ids and entity table, remove entity(s)tags.
 197    *
 198    * @param array $entityIds
 199    *   (reference ) the array of entity ids to be removed.
 200    * @param int $tagId
 201    *   The id of the tag.
 202    * @param string $entityTable
 203    *   Name of entity table default:civicrm_contact.
 204    * @param bool $applyPermissions
 205    *   Should permissions be applied in this function.
 206    *
 207    * @return array
 208    *   (total, removed, notRemoved) count of entities removed from tags
 209    */
 210   public static function removeEntitiesFromTag(&$entityIds, $tagId, $entityTable, $applyPermissions) {
 211     $numEntitiesRemoved = 0;
 212     $numEntitiesNotRemoved = 0;
 213     $entityIdsRemoved = [];
 214
 215     //invoke pre hook for entityTag
 216     $preObject = [$entityIds, $entityTable];
 217     CRM_Utils_Hook::pre('delete', 'EntityTag', $tagId, $preObject);
 218
 219     foreach ($entityIds as $entityId) {
 220       // CRM-17350 - check if we have permission to edit the contact
 221       // that this tag belongs to.
 222       if ($applyPermissions && !self::checkPermissionOnEntityTag($entityId, $entityTable)) {
 223         $numEntitiesNotRemoved++;
 224         continue;
 225       }
 226       $tag = new CRM_Core_DAO_EntityTag();
 227
 228       $tag->entity_id = $entityId;
 229       $tag->tag_id = $tagId;
 230       $tag->entity_table = $entityTable;
 231       if ($tag->find()) {
 232         $tag->delete();
 233         $entityIdsRemoved[] = $entityId;
 234         $numEntitiesRemoved++;
 235       }
 236       else {
 237         $numEntitiesNotRemoved++;
 238       }
 239     }
 240
 241     //invoke post hook on entityTag
 242     $object = [$entityIdsRemoved, $entityTable];
 243     CRM_Utils_Hook::post('delete', 'EntityTag', $tagId, $object);
 244
 245     CRM_Contact_BAO_GroupContactCache::opportunisticCacheFlush();
 246
 247     return [count($entityIds), $numEntitiesRemoved, $numEntitiesNotRemoved];
 248   }
 249
 250   /**
 251    * Takes an associative array and creates tag entity record for all tag entities.
 252    *
 253    * @param array $params
 254    *   (reference) an assoc array of name/value pairs.
 255    * @param string $entityTable
 256    * @param int $entityID
 257    */
 258   public static function create(&$params, $entityTable, $entityID) {
 259     // get categories for the entity id
 260     $entityTag = CRM_Core_BAO_EntityTag::getTag($entityID, $entityTable);
 261
 262     // get the list of all the categories
 263     $allTag = CRM_Core_BAO_Tag::getTags($entityTable);
 264
 265     // this fix is done to prevent warning generated by array_key_exits incase of empty array is given as input
 266     if (!is_array($params)) {
 267       $params = [];
 268     }
 269
 270     // this fix is done to prevent warning generated by array_key_exits incase of empty array is given as input
 271     if (!is_array($entityTag)) {
 272       $entityTag = [];
 273     }
 274
 275     // check which values has to be inserted/deleted for contact
 276     foreach ($allTag as $key => $varValue) {
 277       $tagParams['entity_table'] = $entityTable;
 278       $tagParams['entity_id'] = $entityID;
 279       $tagParams['tag_id'] = $key;
 280
 281       if (array_key_exists($key, $params) && !array_key_exists($key, $entityTag)) {
 282         // insert a new record
 283         CRM_Core_BAO_EntityTag::add($tagParams);
 284       }
 285       elseif (!array_key_exists($key, $params) && array_key_exists($key, $entityTag)) {
 286         // delete a record for existing contact
 287         CRM_Core_BAO_EntityTag::del($tagParams);
 288       }
 289     }
 290   }
 291
 292   /**
 293    * This function returns all entities assigned to a specific tag.
 294    *
 295    * @param object $tag
 296    *   An object of a tag.
 297    *
 298    * @return array
 299    *   array of entity ids
 300    */
 301   public function getEntitiesByTag($tag) {
 302     $entityIds = [];
 303     $entityTagDAO = new CRM_Core_DAO_EntityTag();
 304     $entityTagDAO->tag_id = $tag->id;
 305     $entityTagDAO->find();
 306     while ($entityTagDAO->fetch()) {
 307       $entityIds[] = $entityTagDAO->entity_id;
 308     }
 309     return $entityIds;
 310   }
 311
 312   /**
 313    * Get contact tags.
 314    *
 315    * @param int $contactID
 316    * @param bool $count
 317    *
 318    * @return array
 319    */
 320   public static function getContactTags($contactID, $count = FALSE) {
 321     $contactTags = [];
 322     if (!$count) {
 323       $select = "SELECT ct.id, ct.name ";
 324     }
 325     else {
 326       $select = "SELECT count(*) as cnt";
 327     }
 328
 329     $query = "{$select}
 330         FROM civicrm_tag ct
 331         INNER JOIN civicrm_entity_tag et ON ( ct.id = et.tag_id AND
 332             et.entity_id    = {$contactID} AND
 333             et.entity_table = 'civicrm_contact' AND
 334             ct.is_tagset = 0 )";
 335
 336     $dao = CRM_Core_DAO::executeQuery($query);
 337
 338     if ($count) {
 339       $dao->fetch();
 340       return $dao->cnt;
 341     }
 342
 343     while ($dao->fetch()) {
 344       $contactTags[$dao->id] = $dao->name;
 345     }
 346
 347     return $contactTags;
 348   }
 349
 350   /**
 351    * Get child contact tags given parentId.
 352    *
 353    * @param int $parentId
 354    * @param int $entityId
 355    * @param string $entityTable
 356    *
 357    * @return array
 358    */
 359   public static function getChildEntityTags($parentId, $entityId, $entityTable = 'civicrm_contact') {
 360     $entityTags = [];
 361     $query = "SELECT ct.id as tag_id, name FROM civicrm_tag ct
 362                     INNER JOIN civicrm_entity_tag et ON ( et.entity_id = {$entityId} AND
 363                      et.entity_table = '{$entityTable}' AND  et.tag_id = ct.id)
 364                   WHERE ct.parent_id = {$parentId}";
 365
 366     $dao = CRM_Core_DAO::executeQuery($query);
 367
 368     while ($dao->fetch()) {
 369       $entityTags[$dao->tag_id] = [
 370         'id' => $dao->tag_id,
 371         'name' => $dao->name,
 372       ];
 373     }
 374
 375     return $entityTags;
 376   }
 377
 378   /**
 379    * Merge two tags
 380    *
 381    * Tag A will inherit all of tag B's properties.
 382    * Tag B will be deleted.
 383    *
 384    * @param int $tagAId
 385    * @param int $tagBId
 386    *
 387    * @return array
 388    */
 389   public function mergeTags($tagAId, $tagBId) {
 390     $queryParams = [
 391       1 => [$tagAId, 'Integer'],
 392       2 => [$tagBId, 'Integer'],
 393     ];
 394
 395     // re-compute used_for field
 396     $query = "SELECT id, name, used_for FROM civicrm_tag WHERE id IN (%1, %2)";
 397     $dao = CRM_Core_DAO::executeQuery($query, $queryParams);
 398     $tags = [];
 399     while ($dao->fetch()) {
 400       $label = ($dao->id == $tagAId) ? 'tagA' : 'tagB';
 401       $tags[$label] = $dao->name;
 402       $tags["{$label}_used_for"] = $dao->used_for ? explode(",", $dao->used_for) : [];
 403     }
 404     $usedFor = array_merge($tags["tagA_used_for"], $tags["tagB_used_for"]);
 405     $usedFor = implode(',', array_unique($usedFor));
 406     $tags["used_for"] = explode(",", $usedFor);
 407
 408     // get all merge queries together
 409     $sqls = [
 410       // 1. update entity tag entries
 411       "UPDATE IGNORE civicrm_entity_tag SET tag_id = %1 WHERE tag_id = %2",
 412       // 2. move children
 413       "UPDATE civicrm_tag SET parent_id = %1 WHERE parent_id = %2",
 414       // 3. update used_for info for tag A & children
 415       "UPDATE civicrm_tag SET used_for = '{$usedFor}' WHERE id = %1 OR parent_id = %1",
 416       // 4. delete tag B
 417       "DELETE FROM civicrm_tag WHERE id = %2",
 418       // 5. remove duplicate entity tag records
 419       "DELETE et2.* from civicrm_entity_tag et1 INNER JOIN civicrm_entity_tag et2 ON et1.entity_table = et2.entity_table AND et1.entity_id = et2.entity_id AND et1.tag_id = et2.tag_id WHERE et1.id < et2.id",
 420       // 6. remove orphaned entity_tags
 421       "DELETE FROM civicrm_entity_tag WHERE tag_id = %2",
 422     ];
 423     $tables = ['civicrm_entity_tag', 'civicrm_tag'];
 424
 425     // Allow hook_civicrm_merge() to add SQL statements for the merge operation AND / OR
 426     // perform any other actions like logging
 427     CRM_Utils_Hook::merge('sqls', $sqls, $tagAId, $tagBId, $tables);
 428
 429     // call the SQL queries in one transaction
 430     $transaction = new CRM_Core_Transaction();
 431     foreach ($sqls as $sql) {
 432       CRM_Core_DAO::executeQuery($sql, $queryParams, TRUE, NULL, TRUE);
 433     }
 434     $transaction->commit();
 435
 436     $tags['status'] = TRUE;
 437     return $tags;
 438   }
 439
 440   /**
 441    * Get options for a given field.
 442    *
 443    * @see CRM_Core_DAO::buildOptions
 444    * @see CRM_Core_DAO::buildOptionsContext
 445    *
 446    * @param string $fieldName
 447    * @param string $context
 448    *   As per CRM_Core_DAO::buildOptionsContext.
 449    * @param array $props
 450    *   whatever is known about this dao object.
 451    *
 452    * @return array|bool
 453    */
 454   public static function buildOptions($fieldName, $context = NULL, $props = []) {
 455     $params = [];
 456
 457     if ($fieldName == 'tag' || $fieldName == 'tag_id') {
 458       if (!empty($props['entity_table'])) {
 459         $entity = CRM_Utils_Type::escape($props['entity_table'], 'String');
 460         $params[] = "used_for LIKE '%$entity%'";
 461       }
 462
 463       // Output tag list as nested hierarchy
 464       // TODO: This will only work when api.entity is "entity_tag". What about others?
 465       if ($context == 'search' || $context == 'create') {
 466         $dummyArray = [];
 467         return CRM_Core_BAO_Tag::getTags(CRM_Utils_Array::value('entity_table', $props, 'civicrm_contact'), $dummyArray, CRM_Utils_Array::value('parent_id', $params), '- ');
 468       }
 469     }
 470
 471     $options = CRM_Core_PseudoConstant::get(__CLASS__, $fieldName, $params, $context);
 472
 473     // Special formatting for validate/match context
 474     if ($fieldName == 'entity_table' && in_array($context, ['validate', 'match'])) {
 475       $options = [];
 476       foreach (self::buildOptions($fieldName) as $tableName => $label) {
 477         $bao = CRM_Core_DAO_AllCoreTables::getClassForTable($tableName);
 478         $apiName = CRM_Core_DAO_AllCoreTables::getBriefName($bao);
 479         $options[$tableName] = $apiName;
 480       }
 481     }
 482
 483     return $options;
 484   }
 485
 486   /**
 487    * This function deletes entity tags when a related entity is called.
 488    *
 489    * It is registered as a listener in \Civi\Core\Container::createEventDispatcher
 490    *
 491    * @param \Civi\Core\DAO\Event\PreDelete $event
 492    */
 493   public static function preDeleteOtherEntity($event) {
 494     if (
 495       $event->object instanceof CRM_Core_DAO_EntityTag
 496       // Activity can call the pre hook for delete with no ID - this seems to be isolated to activity....
 497       // @todo - what is the correct way to standardise activity delete?
 498       || ($event->object instanceof CRM_Activity_DAO_Activity && !$event->object->id)
 499
 500     ) {
 501       return;
 502     }
 503     // This is probably fairly mild in terms of helping performance - a case could be made to check if tags
 504     // exist before deleting (further down) as delete is a locking action.
 505     $entity = CRM_Core_DAO_AllCoreTables::getBriefName(get_class($event->object));
 506     if (!isset(Civi::$statics[__CLASS__]['tagged_entities'][$entity])) {
 507       $tableName = CRM_Core_DAO_AllCoreTables::getTableForEntityName($entity);
 508       $used_for = CRM_Core_OptionGroup::values('tag_used_for');
 509       Civi::$statics[__CLASS__]['tagged_entities'][$entity] = !empty($used_for[$tableName]) ? $tableName : FALSE;
 510     }
 511
 512     if (Civi::$statics[__CLASS__]['tagged_entities'][$entity]) {
 513       CRM_Core_DAO::executeQuery('DELETE FROM civicrm_entity_tag WHERE entity_table = %1 AND entity_id = %2',
 514         [1 => [Civi::$statics[__CLASS__]['tagged_entities'][$entity], 'String'], 2 => [$event->object->id, 'Integer']]
 515       );
 516     }
 517
 518   }
 519
 520 }