CRM/Core/BAO/Tag.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.4                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2013                                |
   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  *
  30  * @package CRM
  31  * @copyright CiviCRM LLC (c) 2004-2013
  32  * $Id$
  33  *
  34  */
  35 class CRM_Core_BAO_Tag extends CRM_Core_DAO_Tag {
  36
  37   /**
  38    * class constructor
  39    */
  40   function __construct() {
  41     parent::__construct();
  42   }
  43
  44   /**
  45    * Takes a bunch of params that are needed to match certain criteria and
  46    * retrieves the relevant objects. Typically the valid params are only
  47    * contact_id. We'll tweak this function to be more full featured over a period
  48    * of time. This is the inverse function of create. It also stores all the retrieved
  49    * values in the default array
  50    *
  51    * @param array $params      (reference ) an assoc array of name/value pairs
  52    * @param array $defaults    (reference ) an assoc array to hold the flattened values
  53    *
  54    * @return object     CRM_Core_DAO_Tag object on success, otherwise null
  55    * @access public
  56    * @static
  57    */
  58   static function retrieve(&$params, &$defaults) {
  59     $tag = new CRM_Core_DAO_Tag();
  60     $tag->copyValues($params);
  61     if ($tag->find(TRUE)) {
  62       CRM_Core_DAO::storeValues($tag, $defaults);
  63       return $tag;
  64     }
  65     return NULL;
  66   }
  67
  68   function getTree($usedFor = NULL, $excludeHidden = FALSE) {
  69     if (!isset($this->tree)) {
  70       $this->buildTree($usedFor, $excludeHidden);
  71     }
  72     return $this->tree;
  73   }
  74
  75   function buildTree($usedFor = NULL, $excludeHidden = FALSE) {
  76     $sql = "SELECT civicrm_tag.id, civicrm_tag.parent_id,civicrm_tag.name FROM civicrm_tag ";
  77
  78     $whereClause = array();
  79     if ($usedFor) {
  80       $whereClause[] = "used_for like '%{$usedFor}%'";
  81     }
  82     if ($excludeHidden) {
  83       $whereClause[] = "is_tagset = 0";
  84     }
  85
  86     if (!empty($whereClause)) {
  87       $sql .= " WHERE " . implode(' AND ', $whereClause);
  88     }
  89
  90     $sql .= " ORDER BY parent_id,name";
  91
  92     $dao = CRM_Core_DAO::executeQuery($sql, CRM_Core_DAO::$_nullArray, TRUE, NULL, FALSE, FALSE);
  93
  94     $orphan = array();
  95     while ($dao->fetch()) {
  96       if (!$dao->parent_id) {
  97         $this->tree[$dao->id]['name'] = $dao->name;
  98       }
  99       else {
 100         if (array_key_exists($dao->parent_id, $this->tree)) {
 101           $parent = &$this->tree[$dao->parent_id];
 102           if (!isset($this->tree[$dao->parent_id]['children'])) {
 103             $this->tree[$dao->parent_id]['children'] = array();
 104           }
 105         }
 106         else {
 107           //3rd level tag
 108           if (!array_key_exists($dao->parent_id, $orphan)) {
 109             $orphan[$dao->parent_id] = array('children' => array());
 110           }
 111           $parent = &$orphan[$dao->parent_id];
 112         }
 113         $parent['children'][$dao->id] = array('name' => $dao->name);
 114       }
 115     }
 116     if (sizeof($orphan)) {
 117       //hang the 3rd level lists at the right place
 118       foreach ($this->tree as & $level1) {
 119         if (!isset($level1['children'])) {
 120           continue;
 121         }
 122
 123         foreach ($level1['children'] as $key => & $level2) {
 124           if (array_key_exists($key, $orphan)) {
 125             $level2['children'] = $orphan[$key]['children'];
 126           }
 127         }
 128       }
 129     }
 130   }
 131
 132   static function getTagsUsedFor($usedFor = array('civicrm_contact'),
 133     $buildSelect = TRUE,
 134     $all         = FALSE,
 135     $parentId    = NULL
 136   ) {
 137     $tags = array();
 138
 139     if (empty($usedFor)) {
 140       return $tags;
 141     }
 142     if (!is_array($usedFor)) {
 143       $usedFor = array($usedFor);
 144     }
 145
 146     if ($parentId === NULL) {
 147       $parentClause = " parent_id IS NULL AND ";
 148     }
 149     else {
 150       $parentClause = " parent_id = {$parentId} AND ";
 151     }
 152
 153     foreach ($usedFor as $entityTable) {
 154       $tag = new CRM_Core_DAO_Tag();
 155       $tag->fields();
 156       $tag->orderBy('parent_id');
 157       if ($buildSelect) {
 158         $tag->whereAdd("is_tagset = 0 AND {$parentClause} used_for LIKE '%{$entityTable}%'");
 159       }
 160       else {
 161         $tag->whereAdd("used_for LIKE '%{$entityTable}%'");
 162       }
 163       if (!$all) {
 164         $tag->is_tagset = 0;
 165       }
 166       $tag->find();
 167
 168       while ($tag->fetch()) {
 169         if ($buildSelect) {
 170           $tags[$tag->id] = $tag->name;
 171         }
 172         else {
 173           $tags[$tag->id]['name'] = $tag->name;
 174           $tags[$tag->id]['parent_id'] = $tag->parent_id;
 175           $tags[$tag->id]['is_tagset'] = $tag->is_tagset;
 176           $tags[$tag->id]['used_for'] = $tag->used_for;
 177         }
 178       }
 179       $tag->free();
 180     }
 181
 182     return $tags;
 183   }
 184
 185   static function getTags($usedFor = 'civicrm_contact',
 186     &$tags = array(),
 187     $parentId  = NULL,
 188     $separator = '&nbsp;&nbsp;'
 189   ) {
 190     // We need to build a list of tags ordered by hierarchy and sorted by
 191     // name. The heirarchy will be communicated by an accumulation of
 192     // separators in front of the name to give it a visual offset.
 193     // Instead of recursively making mysql queries, we'll make one big
 194     // query and build the heirarchy with the algorithm below.
 195     $args = array(1 => array('%' . $usedFor . '%', 'String'));
 196     $query = "SELECT id, name, parent_id, is_tagset
 197                   FROM civicrm_tag
 198               WHERE used_for LIKE %1";
 199     if ($parentId) {
 200       $query .= " AND parent_id = %2";
 201       $args[2] = array($parentId, 'Integer');
 202     }
 203     $query .= " ORDER BY name";
 204     $dao = CRM_Core_DAO::executeQuery($query, $args, TRUE, NULL, FALSE, FALSE);
 205
 206     // Sort the tags into the correct storage by the parent_id/is_tagset
 207     // filter the filter was in place previously, we're just reusing it.
 208     // $roots represents the current leaf nodes that need to be checked for
 209     // children. $rows represents the unplaced nodes, not all of much
 210     // are necessarily placed.
 211     $roots = $rows = array();
 212     while ($dao->fetch()) {
 213       if ($dao->parent_id == $parentId && $dao->is_tagset == 0) {
 214         $roots[] = array('id' => $dao->id, 'prefix' => '', 'name' => $dao->name);
 215       }
 216       else {
 217         $rows[] = array('id' => $dao->id, 'prefix' => '', 'name' => $dao->name, 'parent_id' => $dao->parent_id);
 218       }
 219     }
 220     $dao->free();
 221     // While we have nodes left to build, shift the first (alphabetically)
 222     // node of the list, place it in our tags list and loop through the
 223     // list of unplaced nodes to find its children. We make a copy to
 224     // iterate through because we must modify the unplaced nodes list
 225     // during the loop.
 226     while (count($roots)) {
 227       $new_roots         = array();
 228       $current_rows      = $rows;
 229       $root              = array_shift($roots);
 230       $tags[$root['id']] = array($root['prefix'], $root['name']);
 231
 232       // As you find the children, append them to the end of the new set
 233       // of roots (maintain alphabetical ordering). Also remove the node
 234       // from the set of unplaced nodes.
 235       if (is_array($current_rows)) {
 236         foreach ($current_rows as $key => $row) {
 237           if ($row['parent_id'] == $root['id']) {
 238             $new_roots[] = array('id' => $row['id'], 'prefix' => $tags[$root['id']][0] . $separator, 'name' => $row['name']);
 239             unset($rows[$key]);
 240           }
 241         }
 242       }
 243
 244       //As a group, insert the new roots into the beginning of the roots
 245       //list. This maintains the hierarchical ordering of the tags.
 246       $roots = array_merge($new_roots, $roots);
 247     }
 248
 249     // Prefix each name with the calcuated spacing to give the visual
 250     // appearance of ordering when transformed into HTML in the form layer.
 251     foreach ($tags as & $tag) {
 252       $tag = $tag[0] . $tag[1];
 253     }
 254
 255     return $tags;
 256   }
 257
 258   /**
 259    * Function to delete the tag
 260    *
 261    * @param int $id   tag id
 262    *
 263    * @return boolean
 264    * @access public
 265    * @static
 266    *
 267    */
 268   static function del($id) {
 269     // since this is a destructive operation, lets make sure
 270     // id is a postive number
 271     CRM_Utils_Type::validate($id, 'Positive');
 272
 273     // delete all crm_entity_tag records with the selected tag id
 274     $entityTag = new CRM_Core_DAO_EntityTag();
 275     $entityTag->tag_id = $id;
 276     $entityTag->delete();
 277
 278     // delete from tag table
 279     $tag = new CRM_Core_DAO_Tag();
 280     $tag->id = $id;
 281
 282     CRM_Utils_Hook::pre('delete', 'Tag', $id, $tag);
 283
 284     if ($tag->delete()) {
 285       CRM_Utils_Hook::post('delete', 'Tag', $id, $tag);
 286       CRM_Core_Session::setStatus(ts('Selected tag has been deleted successfuly.'), ts('Tag Deleted'), 'success');
 287       return TRUE;
 288     }
 289     return FALSE;
 290   }
 291
 292   /**
 293    * takes an associative array and creates a contact object
 294    *
 295    * The function extract all the params it needs to initialize the create a
 296    * contact object. the params array could contain additional unused name/value
 297    * pairs
 298    *
 299    * @param array  $params         (reference) an assoc array of name/value pairs
 300    * @param array  $ids  (optional)  the array that holds all the db ids - we are moving away from this in bao
 301    * signatures
 302    *
 303    * @return object    CRM_Core_DAO_Tag object on success, otherwise null
 304    * @access public
 305    * @static
 306    */
 307   static function add(&$params, $ids = array()) {
 308     if (!self::dataExists($params)) {
 309       return NULL;
 310     }
 311
 312     $tag = new CRM_Core_DAO_Tag();
 313
 314     // if parent id is set then inherit used for and is hidden properties
 315     if (CRM_Utils_Array::value('parent_id', $params)) {
 316       // get parent details
 317       $params['used_for'] = CRM_Core_DAO::getFieldValue('CRM_Core_DAO_Tag', $params['parent_id'], 'used_for');
 318     }
 319
 320     $tag->copyValues($params);
 321     $tag->id = CRM_Utils_Array::value('id', $params, CRM_Utils_Array::value('tag', $ids));
 322     $hook = empty($params['id']) ? 'create' : 'edit';
 323     CRM_Utils_Hook::pre($hook, 'Tag', $tag->id, $params);
 324
 325     // save creator id and time
 326     if (!$tag->id) {
 327       $session           = CRM_Core_Session::singleton();
 328       $tag->created_id   = $session->get('userID');
 329       $tag->created_date = date('YmdHis');
 330     }
 331
 332     $tag->save();
 333     CRM_Utils_Hook::post($hook, 'Tag', $tag->id, $tag);
 334
 335     // if we modify parent tag, then we need to update all children
 336     if ($tag->parent_id === 'null') {
 337       CRM_Core_DAO::executeQuery("UPDATE civicrm_tag SET used_for=%1 WHERE parent_id = %2",
 338         array(1 => array($params['used_for'], 'String'),
 339           2 => array($tag->id, 'Integer'),
 340         )
 341       );
 342     }
 343
 344     return $tag;
 345   }
 346
 347   /**
 348    * Check if there is data to create the object
 349    *
 350    * @param array  $params         (reference ) an assoc array of name/value pairs
 351    *
 352    * @return boolean
 353    * @access public
 354    * @static
 355    */
 356   static function dataExists(&$params) {
 357     if (!empty($params['name'])) {
 358       return TRUE;
 359     }
 360
 361     return FALSE;
 362   }
 363
 364   /**
 365    * Function to get the tag sets for a entity object
 366    *
 367    * @param string $entityTable entity_table
 368    *
 369    * @return array $tagSets array of tag sets
 370    * @access public
 371    * @static
 372    */
 373   static function getTagSet($entityTable) {
 374     $tagSets = array();
 375     $query = "SELECT name, id FROM civicrm_tag
 376               WHERE is_tagset=1 AND parent_id IS NULL and used_for LIKE %1";
 377     $dao = CRM_Core_DAO::executeQuery($query, array(1 => array('%' . $entityTable . '%', 'String')), TRUE, NULL, FALSE, FALSE);
 378     while ($dao->fetch()) {
 379       $tagSets[$dao->id] = $dao->name;
 380     }
 381     $dao->free();
 382     return $tagSets;
 383   }
 384
 385   /**
 386    * Function to get the tags that are not children of a tagset.
 387    *
 388    * @return $tags associated array of tag name and id
 389    * @access public
 390    * @static
 391    */
 392   static function getTagsNotInTagset() {
 393     $tags = $tagSets = array();
 394     // first get all the tag sets
 395     $query = "SELECT id FROM civicrm_tag WHERE is_tagset=1 AND parent_id IS NULL";
 396     $dao = CRM_Core_DAO::executeQuery($query, CRM_Core_DAO::$_nullArray);
 397     while ($dao->fetch()) {
 398       $tagSets[] = $dao->id;
 399     }
 400
 401     $parentClause = '';
 402     if (!empty($tagSets)) {
 403       $parentClause = ' WHERE ( parent_id IS NULL ) OR ( parent_id NOT IN ( ' . implode(',', $tagSets) . ' ) )';
 404     }
 405
 406     // get that tags that don't have tagset as parent
 407     $query = "SELECT id, name FROM civicrm_tag {$parentClause}";
 408     $dao = CRM_Core_DAO::executeQuery($query);
 409     while ($dao->fetch()) {
 410       $tags[$dao->id] = $dao->name;
 411     }
 412
 413     return $tags;
 414   }
 415 }
 416