CRM/Core/BAO/EntityTag.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.6                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2014                                |
   7  +--------------------------------------------------------------------+
   8  | This file is a part of CiviCRM.                                    |
   9  |                                                                    |
  10  | CiviCRM is free software; you can copy, modify, and distribute it  |
  11  | under the terms of the GNU Affero General Public License           |
  12  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  13  |                                                                    |
  14  | CiviCRM is distributed in the hope that it will be useful, but     |
  15  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  16  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  17  | See the GNU Affero General Public License for more details.        |
  18  |                                                                    |
  19  | You should have received a copy of the GNU Affero General Public   |
  20  | License and the CiviCRM Licensing Exception along                  |
  21  | with this program; if not, contact CiviCRM LLC                     |
  22  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  23  | GNU Affero General Public License or the licensing of CiviCRM,     |
  24  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  25  +--------------------------------------------------------------------+
  26  */
  27
  28 /**
  29  * This class contains functions for managing Tag(tag) for a contact
  30  *
  31  * @package CRM
  32  * @copyright CiviCRM LLC (c) 2004-2014
  33  * $Id$
  34  *
  35  */
  36 class CRM_Core_BAO_EntityTag extends CRM_Core_DAO_EntityTag {
  37
  38   /**
  39    *
  40    * Given a contact id, it returns an array of tag id's the
  41    * contact belongs to.
  42    *
  43    * @param int $entityID
  44    *   Id of the entity usually the contactID.
  45    * @param string $entityTable
  46    *   Name of the entity table usually 'civicrm_contact'.
  47    *
  48    * @return array
  49    *   reference $tag array of category id's the contact belongs to.
  50    *
  51    */
  52   public static function &getTag($entityID, $entityTable = 'civicrm_contact') {
  53     $tags = array();
  54
  55     $entityTag = new CRM_Core_BAO_EntityTag();
  56     $entityTag->entity_id = $entityID;
  57     $entityTag->entity_table = $entityTable;
  58     $entityTag->find();
  59
  60     while ($entityTag->fetch()) {
  61       $tags[$entityTag->tag_id] = $entityTag->tag_id;
  62     }
  63     return $tags;
  64   }
  65
  66   /**
  67    * Takes an associative array and creates a entityTag object
  68    *
  69    * the function extract all the params it needs to initialize the create a
  70    * group object. the params array could contain additional unused name/value
  71    * pairs
  72    *
  73    * @param array $params
  74    *   (reference ) an assoc array of name/value pairs.
  75    *
  76    * @return CRM_Core_BAO_EntityTag
  77    */
  78   public static function add(&$params) {
  79     $dataExists = self::dataExists($params);
  80     if (!$dataExists) {
  81       return NULL;
  82     }
  83
  84     $entityTag = new CRM_Core_BAO_EntityTag();
  85     $entityTag->copyValues($params);
  86
  87     // dont save the object if it already exists, CRM-1276
  88     if (!$entityTag->find(TRUE)) {
  89       $entityTag->save();
  90
  91       //invoke post hook on entityTag
  92       // we are using this format to keep things consistent between the single and bulk operations
  93       // so a bit different from other post hooks
  94       $object = array(0 => array(0 => $params['entity_id']), 1 => $params['entity_table']);
  95       CRM_Utils_Hook::post('create', 'EntityTag', $params['tag_id'], $object);
  96     }
  97     return $entityTag;
  98   }
  99
 100   /**
 101    * Check if there is data to create the object
 102    *
 103    * @param array $params
 104    *   An assoc array of name/value pairs.
 105    *
 106    * @return bool
 107    */
 108   public static function dataExists($params) {
 109     return !($params['tag_id'] == 0);
 110   }
 111
 112   /**
 113    * Delete the tag for a contact
 114    *
 115    * @param array $params
 116    *   (reference ) an assoc array of name/value pairs.
 117    */
 118   public static function del(&$params) {
 119     $entityTag = new CRM_Core_BAO_EntityTag();
 120     $entityTag->copyValues($params);
 121     $entityTag->delete();
 122
 123     //invoke post hook on entityTag
 124     $object = array(0 => array(0 => $params['entity_id']), 1 => $params['entity_table']);
 125     CRM_Utils_Hook::post('delete', 'EntityTag', $params['tag_id'], $object);
 126   }
 127
 128   /**
 129    * Given an array of entity ids and entity table, add all the entity to the tags
 130    *
 131    * @param array $entityIds
 132    *   (reference ) the array of entity ids to be added.
 133    * @param int $tagId
 134    *   The id of the tag.
 135    * @param string $entityTable
 136    *   Name of entity table default:civicrm_contact.
 137    *
 138    * @return array
 139    *   (total, added, notAdded) count of enities added to tag
 140    */
 141   public static function addEntitiesToTag(&$entityIds, $tagId, $entityTable = 'civicrm_contact') {
 142     $numEntitiesAdded = 0;
 143     $numEntitiesNotAdded = 0;
 144     $entityIdsAdded = array();
 145
 146     foreach ($entityIds as $entityId) {
 147       $tag = new CRM_Core_DAO_EntityTag();
 148
 149       $tag->entity_id = $entityId;
 150       $tag->tag_id = $tagId;
 151       $tag->entity_table = $entityTable;
 152       if (!$tag->find()) {
 153         $tag->save();
 154         $entityIdsAdded[] = $entityId;
 155         $numEntitiesAdded++;
 156       }
 157       else {
 158         $numEntitiesNotAdded++;
 159       }
 160     }
 161
 162     //invoke post hook on entityTag
 163     $object = array($entityIdsAdded, $entityTable);
 164     CRM_Utils_Hook::post('create', 'EntityTag', $tagId, $object);
 165
 166     // reset the group contact cache for all groups
 167     // if tags are being used in a smart group
 168     CRM_Contact_BAO_GroupContactCache::remove();
 169
 170     return array(count($entityIds), $numEntitiesAdded, $numEntitiesNotAdded);
 171   }
 172
 173   /**
 174    * Given an array of entity ids and entity table, remove entity(s) tags
 175    *
 176    * @param array $entityIds
 177    *   (reference ) the array of entity ids to be removed.
 178    * @param int $tagId
 179    *   The id of the tag.
 180    * @param string $entityTable
 181    *   Name of entity table default:civicrm_contact.
 182    *
 183    * @return array
 184    *   (total, removed, notRemoved) count of entities removed from tags
 185    */
 186   public static function removeEntitiesFromTag(&$entityIds, $tagId, $entityTable = 'civicrm_contact') {
 187     $numEntitiesRemoved = 0;
 188     $numEntitiesNotRemoved = 0;
 189     $entityIdsRemoved = array();
 190
 191     foreach ($entityIds as $entityId) {
 192       $tag = new CRM_Core_DAO_EntityTag();
 193
 194       $tag->entity_id = $entityId;
 195       $tag->tag_id = $tagId;
 196       $tag->entity_table = $entityTable;
 197       if ($tag->find()) {
 198         $tag->delete();
 199         $entityIdsRemoved[] = $entityId;
 200         $numEntitiesRemoved++;
 201       }
 202       else {
 203         $numEntitiesNotRemoved++;
 204       }
 205     }
 206
 207     //invoke post hook on entityTag
 208     $object = array($entityIdsRemoved, $entityTable);
 209     CRM_Utils_Hook::post('delete', 'EntityTag', $tagId, $object);
 210
 211     // reset the group contact cache for all groups
 212     // if tags are being used in a smart group
 213     CRM_Contact_BAO_GroupContactCache::remove();
 214
 215     return array(count($entityIds), $numEntitiesRemoved, $numEntitiesNotRemoved);
 216   }
 217
 218   /**
 219    * Takes an associative array and creates tag entity record for all tag entities
 220    *
 221    * @param array $params
 222    *   (reference) an assoc array of name/value pairs.
 223    * @param $entityTable
 224    * @param int $entityID
 225    *
 226    * @return void
 227    */
 228   public static function create(&$params, $entityTable, $entityID) {
 229     // get categories for the entity id
 230     $entityTag = CRM_Core_BAO_EntityTag::getTag($entityID, $entityTable);
 231
 232     // get the list of all the categories
 233     $allTag = CRM_Core_BAO_Tag::getTags($entityTable);
 234
 235     // this fix is done to prevent warning generated by array_key_exits incase of empty array is given as input
 236     if (!is_array($params)) {
 237       $params = array();
 238     }
 239
 240     // this fix is done to prevent warning generated by array_key_exits incase of empty array is given as input
 241     if (!is_array($entityTag)) {
 242       $entityTag = array();
 243     }
 244
 245     // check which values has to be inserted/deleted for contact
 246     foreach ($allTag as $key => $varValue) {
 247       $tagParams['entity_table'] = $entityTable;
 248       $tagParams['entity_id'] = $entityID;
 249       $tagParams['tag_id'] = $key;
 250
 251       if (array_key_exists($key, $params) && !array_key_exists($key, $entityTag)) {
 252         // insert a new record
 253         CRM_Core_BAO_EntityTag::add($tagParams);
 254       }
 255       elseif (!array_key_exists($key, $params) && array_key_exists($key, $entityTag)) {
 256         // delete a record for existing contact
 257         CRM_Core_BAO_EntityTag::del($tagParams);
 258       }
 259     }
 260   }
 261
 262   /**
 263    * This function returns all entities assigned to a specific tag
 264    *
 265    * @param object $tag
 266    *   An object of a tag.
 267    *
 268    * @return array
 269    *   array of entity ids
 270    */
 271   public function getEntitiesByTag($tag) {
 272     $entityIds = array();
 273     $entityTagDAO = new CRM_Core_DAO_EntityTag();
 274     $entityTagDAO->tag_id = $tag->id;
 275     $entityTagDAO->find();
 276     while ($entityTagDAO->fetch()) {
 277       $entityIds[] = $entityTagDAO->entity_id;
 278     }
 279     return $entityIds;
 280   }
 281
 282   /**
 283    * Get contact tags
 284    */
 285   public static function getContactTags($contactID, $count = FALSE) {
 286     $contactTags = array();
 287     if (!$count) {
 288       $select = "SELECT name ";
 289     }
 290     else {
 291       $select = "SELECT count(*) as cnt";
 292     }
 293
 294     $query = "{$select}
 295         FROM civicrm_tag ct
 296         INNER JOIN civicrm_entity_tag et ON ( ct.id = et.tag_id AND
 297             et.entity_id    = {$contactID} AND
 298             et.entity_table = 'civicrm_contact' AND
 299             ct.is_tagset = 0 )";
 300
 301     $dao = CRM_Core_DAO::executeQuery($query);
 302
 303     if ($count) {
 304       $dao->fetch();
 305       return $dao->cnt;
 306     }
 307
 308     while ($dao->fetch()) {
 309       $contactTags[] = $dao->name;
 310     }
 311
 312     return $contactTags;
 313   }
 314
 315   /**
 316    * Get child contact tags given parentId
 317    */
 318   public static function getChildEntityTags($parentId, $entityId, $entityTable = 'civicrm_contact') {
 319     $entityTags = array();
 320     $query = "SELECT ct.id as tag_id, name FROM civicrm_tag ct
 321                     INNER JOIN civicrm_entity_tag et ON ( et.entity_id = {$entityId} AND
 322                      et.entity_table = '{$entityTable}' AND  et.tag_id = ct.id)
 323                   WHERE ct.parent_id = {$parentId}";
 324
 325     $dao = CRM_Core_DAO::executeQuery($query);
 326
 327     while ($dao->fetch()) {
 328       $entityTags[$dao->tag_id] = array(
 329         'id' => $dao->tag_id,
 330         'name' => $dao->name,
 331       );
 332     }
 333
 334     return $entityTags;
 335   }
 336
 337   /**
 338    * Merge two tags: tag B into tag A.
 339    */
 340   public function mergeTags($tagAId, $tagBId) {
 341     $queryParams = array(
 342       1 => array($tagBId, 'Integer'),
 343       2 => array($tagAId, 'Integer'),
 344     );
 345
 346     // re-compute used_for field
 347     $query = "SELECT id, name, used_for FROM civicrm_tag WHERE id IN (%1, %2)";
 348     $dao = CRM_Core_DAO::executeQuery($query, $queryParams);
 349     $tags = array();
 350     while ($dao->fetch()) {
 351       $label = ($dao->id == $tagAId) ? 'tagA' : 'tagB';
 352       $tags[$label] = $dao->name;
 353       $tags["{$label}_used_for"] = $dao->used_for ? explode(",", $dao->used_for) : array();
 354     }
 355     $usedFor = array_merge($tags["tagA_used_for"], $tags["tagB_used_for"]);
 356     $usedFor = implode(',', array_unique($usedFor));
 357     $tags["tagB_used_for"] = explode(",", $usedFor);
 358
 359     // get all merge queries together
 360     $sqls = array(
 361       // 1. update entity tag entries
 362       "UPDATE IGNORE civicrm_entity_tag SET tag_id = %1 WHERE tag_id = %2",
 363       // 2. update used_for info for tag B
 364       "UPDATE civicrm_tag SET used_for = '{$usedFor}' WHERE id = %1",
 365       // 3. remove tag A, if tag A is getting merged into B
 366       "DELETE FROM civicrm_tag WHERE id = %2",
 367       // 4. remove duplicate entity tag records
 368       "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",
 369       // 5. remove orphaned entity_tags
 370       "DELETE FROM civicrm_entity_tag WHERE tag_id = %2",
 371     );
 372     $tables = array('civicrm_entity_tag', 'civicrm_tag');
 373
 374     // Allow hook_civicrm_merge() to add SQL statements for the merge operation AND / OR
 375     // perform any other actions like logging
 376     CRM_Utils_Hook::merge('sqls', $sqls, $tagAId, $tagBId, $tables);
 377
 378     // call the SQL queries in one transaction
 379     $transaction = new CRM_Core_Transaction();
 380     foreach ($sqls as $sql) {
 381       CRM_Core_DAO::executeQuery($sql, $queryParams, TRUE, NULL, TRUE);
 382     }
 383     $transaction->commit();
 384
 385     $tags['status'] = TRUE;
 386     return $tags;
 387   }
 388
 389   /**
 390    * Get options for a given field.
 391    *
 392    * @see CRM_Core_DAO::buildOptions
 393    * @see CRM_Core_DAO::buildOptionsContext
 394    *
 395    * @param string $fieldName
 396    * @param string $context
 397    *   As per CRM_Core_DAO::buildOptionsContext.
 398    * @param array $props
 399    *   whatever is known about this dao object.
 400    *
 401    * @return array|bool
 402    */
 403   public static function buildOptions($fieldName, $context = NULL, $props = array()) {
 404     $params = array();
 405
 406     $options = CRM_Core_PseudoConstant::get(__CLASS__, $fieldName, $params, $context);
 407
 408     // Output tag list as nested hierarchy
 409     // TODO: This will only work when api.entity is "entity_tag". What about others?
 410     if (($fieldName == 'tag' || $fieldName == 'tag_id') && ($context == 'search' || $context == 'create')) {
 411       $options = CRM_Core_BAO_Tag::getTags('civicrm_contact', CRM_Core_DAO::$_nullArray, CRM_Utils_Array::value('parent_id', $params), '- ');
 412     }
 413
 414     return $options;
 415   }
 416
 417 }