CRM/Core/BAO/Tag.php

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