tag/lib.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17
  18 /**
  19  * Moodle tag library
  20  *
  21  * Tag strings : you can use any character in tags, except the comma (which is the separator) and
  22  * the '\' (backslash).  Note that many spaces (or other blank characters) will get "compressed"
  23  * into one. A tag string is always a rawurlencode'd string. This is the same behavior as
  24  * http://del.icio.us.
  25  *
  26  * A "record" is a php array (note that an object will work too) that contains the following
  27  * variables :
  28  *  - type: The database table containing the record that we are tagging (eg: for a blog, this is
  29  *          the table named 'post', and for a user it is the table name 'user')
  30  *  - id:   The id of the record
  31  *
  32  * BASIC INSTRUCTIONS :
  33  *  - to "tag a blog post" (for example):
  34  *        tag_set('post', $blog_post->id, $array_of_tags, 'core', $thecontext);
  35  *
  36  *  - to "remove all the tags on a blog post":
  37  *        tag_set('post', $blog_post->id, array(), 'core', $thecontext);
  38  *
  39  * Tag set will create tags that need to be created.
  40  *
  41  * @package    core_tag
  42  * @category   tag
  43  * @todo       MDL-31090 turn this into a full-fledged categorization system. This could start by
  44  *             modifying (removing, probably) the 'tag type' to use another table describing the
  45  *             relationship between tags (parents, sibling, etc.), which could then be merged with
  46  *             the 'course categorization' system.
  47  * @see        http://www.php.net/manual/en/function.urlencode.php
  48  * @copyright  2007 Luiz Cruz <luiz.laydner@gmail.com>
  49  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  50  */
  51
  52 /**
  53  * Used to require that the return value from a function is an array.
  54  * @see tag_set()
  55  */
  56 define('TAG_RETURN_ARRAY', 0);
  57 /**
  58  * Used to require that the return value from a function is an object.
  59  * @see tag_set()
  60  */
  61 define('TAG_RETURN_OBJECT', 1);
  62 /**
  63  * Use to specify that HTML free text is expected to be returned from a function.
  64  * @see tag_display_name()
  65  */
  66 define('TAG_RETURN_TEXT', 2);
  67 /**
  68  * Use to specify that encoded HTML is expected to be returned from a function.
  69  * @see tag_display_name()
  70  */
  71 define('TAG_RETURN_HTML', 3);
  72
  73 /**
  74  * Used to specify that we wish a lowercased string to be returned
  75  * @see tag_normal()
  76  */
  77 define('TAG_CASE_LOWER', 0);
  78 /**
  79  * Used to specify that we do not wish the case of the returned string to change
  80  * @see tag_normal()
  81  */
  82 define('TAG_CASE_ORIGINAL', 1);
  83
  84 /**
  85  * Used to specify that we want all related tags returned, no matter how they are related.
  86  * @see tag_get_related_tags()
  87  */
  88 define('TAG_RELATED_ALL', 0);
  89 /**
  90  * Used to specify that we only want back tags that were manually related.
  91  * @see tag_get_related_tags()
  92  */
  93 define('TAG_RELATED_MANUAL', 1);
  94 /**
  95  * Used to specify that we only want back tags where the relationship was automatically correlated.
  96  * @see tag_get_related_tags()
  97  */
  98 define('TAG_RELATED_CORRELATED', 2);
  99
 100 ///////////////////////////////////////////////////////
 101 /////////////////// PUBLIC TAG API ////////////////////
 102
 103 /// Functions for settings tags  //////////////////////
 104
 105 /**
 106  * Set the tags assigned to a record.  This overwrites the current tags.
 107  *
 108  * This function is meant to be fed the string coming up from the user interface, which contains all tags assigned to a record.
 109  *
 110  * @package core_tag
 111  * @category tag
 112  * @access public
 113  * @param string $record_type the type of record to tag ('post' for blogs, 'user' for users, 'tag' for tags, etc.)
 114  * @param int $record_id the id of the record to tag
 115  * @param array $tags the array of tags to set on the record. If given an empty array, all tags will be removed.
 116  * @param string|null $component the component that was tagged
 117  * @param int|null $contextid the context id of where this tag was assigned
 118  * @return bool|null
 119  */
 120 function tag_set($record_type, $record_id, $tags, $component = null, $contextid = null) {
 121
 122     static $in_recursion_semaphore = false; // this is to prevent loops when tagging a tag
 123
 124     if ( $record_type == 'tag' && !$in_recursion_semaphore) {
 125         $current_tagged_tag_name = tag_get_name($record_id);
 126     }
 127
 128     $tags_ids = tag_get_id($tags, TAG_RETURN_ARRAY); // force an array, even if we only have one tag.
 129     $cleaned_tags = tag_normalize($tags);
 130     //echo 'tags-in-tag_set'; var_dump($tags); var_dump($tags_ids); var_dump($cleaned_tags);
 131
 132     $current_ids = tag_get_tags_ids($record_type, $record_id);
 133     //var_dump($current_ids);
 134
 135     // for data coherence reasons, it's better to remove deleted tags
 136     // before adding new data: ordering could be duplicated.
 137     foreach($current_ids as $current_id) {
 138         if (!in_array($current_id, $tags_ids)) {
 139             tag_delete_instance($record_type, $record_id, $current_id);
 140             if ( $record_type == 'tag' && !$in_recursion_semaphore) {
 141                 // if we are removing a tag-on-a-tag (manually related tag),
 142                 // we need to remove the opposite relationship as well.
 143                 tag_delete_instance('tag', $current_id, $record_id);
 144             }
 145         }
 146     }
 147
 148     if (empty($tags)) {
 149         return true;
 150     }
 151
 152     foreach($tags as $ordering => $tag) {
 153         $tag = trim($tag);
 154         if (!$tag) {
 155             continue;
 156         }
 157
 158         $clean_tag = $cleaned_tags[$tag];
 159         $tag_current_id = $tags_ids[$clean_tag];
 160
 161         if ( is_null($tag_current_id) ) {
 162             // create new tags
 163             //echo "call to add tag $tag\n";
 164             $new_tag = tag_add($tag);
 165             $tag_current_id = $new_tag[$clean_tag];
 166         }
 167
 168         tag_assign($record_type, $record_id, $tag_current_id, $ordering, 0, $component, $contextid);
 169
 170         // if we are tagging a tag (adding a manually-assigned related tag), we
 171         // need to create the opposite relationship as well.
 172         if ( $record_type == 'tag' && !$in_recursion_semaphore) {
 173             $in_recursion_semaphore = true;
 174             tag_set_add('tag', $tag_current_id, $current_tagged_tag_name, $component, $contextid);
 175             $in_recursion_semaphore = false;
 176         }
 177     }
 178 }
 179
 180 /**
 181  * Adds a tag to a record, without overwriting the current tags.
 182  *
 183  * @package core_tag
 184  * @category tag
 185  * @access public
 186  * @param string $record_type the type of record to tag ('post' for blogs, 'user' for users, etc.)
 187  * @param int $record_id the id of the record to tag
 188  * @param string $tag the tag to add
 189  * @param string|null $component the component that was tagged
 190  * @param int|null $contextid the context id of where this tag was assigned
 191  * @return bool|null
 192  */
 193 function tag_set_add($record_type, $record_id, $tag, $component = null, $contextid = null) {
 194
 195     $new_tags = array();
 196     foreach( tag_get_tags($record_type, $record_id) as $current_tag ) {
 197         $new_tags[] = $current_tag->rawname;
 198     }
 199     $new_tags[] = $tag;
 200
 201     return tag_set($record_type, $record_id, $new_tags, $component, $contextid);
 202 }
 203
 204 /**
 205  * Removes a tag from a record, without overwriting other current tags.
 206  *
 207  * @package core_tag
 208  * @category tag
 209  * @access public
 210  * @param string $record_type the type of record to tag ('post' for blogs, 'user' for users, etc.)
 211  * @param int $record_id the id of the record to tag
 212  * @param string $tag the tag to delete
 213  * @param string|null $component the component that was tagged
 214  * @param int|null $contextid the context id of where this tag was assigned
 215  * @return bool|null
 216  */
 217 function tag_set_delete($record_type, $record_id, $tag, $component = null, $contextid = null) {
 218
 219     $new_tags = array();
 220     foreach( tag_get_tags($record_type, $record_id) as $current_tag ) {
 221         if ($current_tag->name != $tag) {  // Keep all tags but the one specified
 222             $new_tags[] = $current_tag->name;
 223         }
 224     }
 225
 226     return tag_set($record_type, $record_id, $new_tags, $component, $contextid);
 227 }
 228
 229 /**
 230  * Set the type of a tag.  At this time (version 2.2) the possible values are 'default' or 'official'.  Official tags will be
 231  * displayed separately "at tagging time" (while selecting the tags to apply to a record).
 232  *
 233  * @package  core_tag
 234  * @category tag
 235  * @access   public
 236  * @param    string   $tagid tagid to modify
 237  * @param    string   $type either 'default' or 'official'
 238  * @return   bool     true on success, false otherwise
 239  */
 240 function tag_type_set($tagid, $type) {
 241     global $DB;
 242
 243     if ($tag = $DB->get_record('tag', array('id' => $tagid), 'id, userid, name, rawname')) {
 244         $tag->tagtype = $type;
 245         $tag->timemodified = time();
 246         $DB->update_record('tag', $tag);
 247
 248         $event = \core\event\tag_updated::create(array(
 249             'objectid' => $tag->id,
 250             'relateduserid' => $tag->userid,
 251             'context' => context_system::instance(),
 252             'other' => array(
 253                 'name' => $tag->name,
 254                 'rawname' => $tag->rawname
 255             )
 256         ));
 257         $event->trigger();
 258
 259         return true;
 260     }
 261     return false;
 262 }
 263
 264 /**
 265  * Set the description of a tag
 266  *
 267  * @package  core_tag
 268  * @category tag
 269  * @access   public
 270  * @param    int      $tagid the id of the tag
 271  * @param    string   $description the tag's description string to be set
 272  * @param    int      $descriptionformat the moodle text format of the description
 273  *                    {@link http://docs.moodle.org/dev/Text_formats_2.0#Database_structure}
 274  * @return   bool     true on success, false otherwise
 275  */
 276 function tag_description_set($tagid, $description, $descriptionformat) {
 277     global $DB;
 278
 279     if ($tag = $DB->get_record('tag', array('id' => $tagid), 'id, userid, name, rawname')) {
 280         $tag->description = $description;
 281         $tag->descriptionformat = $descriptionformat;
 282         $tag->timemodified = time();
 283         $DB->update_record('tag', $tag);
 284
 285         $event = \core\event\tag_updated::create(array(
 286             'objectid' => $tag->id,
 287             'relateduserid' => $tag->userid,
 288             'context' => context_system::instance(),
 289             'other' => array(
 290                 'name' => $tag->name,
 291                 'rawname' => $tag->rawname
 292             )
 293         ));
 294         $event->trigger();
 295
 296         return true;
 297     }
 298
 299     return false;
 300 }
 301
 302
 303
 304
 305
 306
 307 /// Functions for getting information about tags //////
 308
 309 /**
 310  * Simple function to just return a single tag object when you know the name or something
 311  *
 312  * @package  core_tag
 313  * @category tag
 314  * @access   public
 315  * @param    string $field        which field do we use to identify the tag: id, name or rawname
 316  * @param    string $value        the required value of the aforementioned field
 317  * @param    string $returnfields which fields do we want returned. This is a comma seperated string containing any combination of
 318  *                                'id', 'name', 'rawname' or '*' to include all fields.
 319  * @return   mixed  tag object
 320  */
 321 function tag_get($field, $value, $returnfields='id, name, rawname') {
 322     global $DB;
 323
 324     if ($field == 'name') {
 325         $value = core_text::strtolower($value);   // To cope with input that might just be wrong case
 326     }
 327     return $DB->get_record('tag', array($field=>$value), $returnfields);
 328 }
 329
 330
 331 /**
 332  * Get the array of db record of tags associated to a record (instances).  Use {@see tag_get_tags_csv()} if you wish to get the same
 333  * data in a comma-separated string, for instances such as needing to simply display a list of tags to the end user. This should
 334  * really be called tag_get_tag_instances().
 335  *
 336  * @package core_tag
 337  * @category tag
 338  * @access public
 339  * @param string $record_type the record type for which we want to get the tags
 340  * @param int $record_id the record id for which we want to get the tags
 341  * @param string $type the tag type (either 'default' or 'official'). By default, all tags are returned.
 342  * @param int $userid (optional) only required for course tagging
 343  * @return array the array of tags
 344  */
 345 function tag_get_tags($record_type, $record_id, $type=null, $userid=0) {
 346     global $CFG, $DB;
 347
 348     $params = array();
 349
 350     if ($type) {
 351         $sql_type = "AND tg.tagtype = :type";
 352         $params['type'] = $type;
 353     } else {
 354         $sql_type = '';
 355     }
 356
 357    $u = null;
 358     if ($userid) {
 359         $u =  "AND ti.tiuserid = :userid ";
 360         $params['userid'] = $userid;
 361     }
 362
 363     $sql = "SELECT ti.id AS taginstanceid, tg.id, tg.tagtype, tg.name, tg.rawname, tg.flag, ti.ordering
 364               FROM {tag_instance} ti
 365               JOIN {tag} tg ON tg.id = ti.tagid
 366               WHERE ti.itemtype = :recordtype AND ti.itemid = :recordid $u $sql_type
 367            ORDER BY ti.ordering ASC";
 368     $params['recordtype'] = $record_type;
 369     $params['recordid']   = $record_id;
 370
 371     // if the fields in this query are changed, you need to do the same changes in tag_get_correlated_tags
 372     return $DB->get_records_sql($sql, $params);
 373     // This version of the query, reversing the ON clause, "correctly" returns
 374     // a row with NULL values for instances that are still in the DB even though
 375     // the tag has been deleted.  This shouldn't happen, but if it did, using
 376     // this query could help "clean it up".  This causes bugs at this time.
 377     //$tags = $DB->get_records_sql("SELECT ti.tagid, tg.tagtype, tg.name, tg.rawname, tg.flag, ti.ordering ".
 378     //    "FROM {tag_instance} ti LEFT JOIN {tag} tg ON ti.tagid = tg.id ".
 379     //    "WHERE ti.itemtype = '{$record_type}' AND ti.itemid = '{$record_id}' {$type} ".
 380     //    "ORDER BY ti.ordering ASC");
 381 }
 382
 383 /**
 384  * Get the array of tags display names, indexed by id.
 385  *
 386  * @package  core_tag
 387  * @category tag
 388  * @access   public
 389  * @param    string $record_type the record type for which we want to get the tags
 390  * @param    int    $record_id   the record id for which we want to get the tags
 391  * @param    string $type        the tag type (either 'default' or 'official'). By default, all tags are returned.
 392  * @return   array  the array of tags (with the value returned by tag_display_name), indexed by id
 393  */
 394 function tag_get_tags_array($record_type, $record_id, $type=null) {
 395     $tags = array();
 396     foreach(tag_get_tags($record_type, $record_id, $type) as $tag) {
 397         $tags[$tag->id] = tag_display_name($tag);
 398     }
 399     return $tags;
 400 }
 401
 402 /**
 403  * Get a comma-separated string of tags associated to a record.  Use {@see tag_get_tags()} to get the same information in an array.
 404  *
 405  * @package  core_tag
 406  * @category tag
 407  * @access   public
 408  * @param    string   $record_type the record type for which we want to get the tags
 409  * @param    int      $record_id   the record id for which we want to get the tags
 410  * @param    int      $html        either TAG_RETURN_HTML or TAG_RETURN_TEXT, depending on the type of output desired
 411  * @param    string   $type        either 'official' or 'default', if null, all tags are returned
 412  * @return   string   the comma-separated list of tags.
 413  */
 414 function tag_get_tags_csv($record_type, $record_id, $html=TAG_RETURN_HTML, $type=null) {
 415     global $CFG;
 416
 417     $tags_names = array();
 418     foreach(tag_get_tags($record_type, $record_id, $type) as $tag) {
 419         if ($html == TAG_RETURN_TEXT) {
 420             $tags_names[] = tag_display_name($tag, TAG_RETURN_TEXT);
 421         } else { // TAG_RETURN_HTML
 422             $tags_names[] = '<a href="'. $CFG->wwwroot .'/tag/index.php?tag='. rawurlencode($tag->name) .'">'. tag_display_name($tag) .'</a>';
 423         }
 424     }
 425     return implode(', ', $tags_names);
 426 }
 427
 428 /**
 429  * Get an array of tag ids associated to a record.
 430  *
 431  * @package  core_tag
 432  * @category tag
 433  * @access   public
 434  * @todo     MDL-31150 Update ordering property
 435  * @param    string    $record_type the record type for which we want to get the tags
 436  * @param    int       $record_id the record id for which we want to get the tags
 437  * @return   array     tag ids, indexed and sorted by 'ordering'
 438  */
 439 function tag_get_tags_ids($record_type, $record_id) {
 440     $tag_ids = array();
 441     foreach (tag_get_tags($record_type, $record_id) as $tag) {
 442         if ( array_key_exists($tag->ordering, $tag_ids) ) {
 443             // until we can add a unique constraint, in table tag_instance,
 444             // on (itemtype, itemid, ordering), this is needed to prevent a bug
 445             // TODO MDL-31150 modify database in 2.0
 446             $tag->ordering++;
 447         }
 448         $tag_ids[$tag->ordering] = $tag->id;
 449     }
 450     ksort($tag_ids);
 451     return $tag_ids;
 452 }
 453
 454 /**
 455  * Returns the database ID of a set of tags.
 456  *
 457  * @package  core_tag
 458  * @category tag
 459  * @access   public
 460  * @todo     MDL-31152 Test the commented MDL-31152 todo in this function to see if it helps performance
 461  *                     without breaking anything.
 462  * @param    mixed $tags one tag, or array of tags, to look for.
 463  * @param    bool  $return_value specify the type of the returned value. Either TAG_RETURN_OBJECT, or TAG_RETURN_ARRAY (default).
 464  *                               If TAG_RETURN_ARRAY is specified, an array will be returned even if only one tag was passed in $tags.
 465  * @return   mixed tag-indexed array of ids (or objects, if second parameter is TAG_RETURN_OBJECT), or only an int, if only one tag
 466  *                 is given *and* the second parameter is null. No value for a key means the tag wasn't found.
 467  */
 468 function tag_get_id($tags, $return_value=null) {
 469     global $CFG, $DB;
 470
 471     static $tag_id_cache = array();
 472
 473     $return_an_int = false;
 474     if (!is_array($tags)) {
 475         if(is_null($return_value) || $return_value == TAG_RETURN_OBJECT) {
 476             $return_an_int = true;
 477         }
 478         $tags = array($tags);
 479     }
 480
 481     $result = array();
 482
 483     //TODO MDL-31152 test this and see if it helps performance without breaking anything
 484     //foreach($tags as $key => $tag) {
 485     //    $clean_tag = core_text::strtolower($tag);
 486     //    if ( array_key_exists($clean_tag), $tag_id_cache) ) {
 487     //        $result[$clean_tag] = $tag_id_cache[$clean_tag];
 488     //        $tags[$key] = ''; // prevent further processing for this one.
 489     //    }
 490     //}
 491
 492     $tags = array_values(tag_normalize($tags));
 493     foreach($tags as $key => $tag) {
 494         $tags[$key] = core_text::strtolower($tag);
 495         $result[core_text::strtolower($tag)] = null; // key must exists : no value for a key means the tag wasn't found.
 496     }
 497
 498     if (empty($tags)) {
 499         return array();
 500     }
 501
 502     list($tag_string, $params) = $DB->get_in_or_equal($tags);
 503
 504     $rs = $DB->get_recordset_sql("SELECT * FROM {tag} WHERE name $tag_string ORDER BY name", $params);
 505     foreach ($rs as $record) {
 506         if ($return_value == TAG_RETURN_OBJECT) {
 507             $result[$record->name] = $record;
 508         } else { // TAG_RETURN_ARRAY
 509             $result[$record->name] = $record->id;
 510         }
 511     }
 512     $rs->close();
 513
 514     if ($return_an_int) {
 515         return array_pop($result);
 516     }
 517
 518     return $result;
 519 }
 520
 521
 522 /**
 523  * Returns tags related to a tag
 524  *
 525  * Related tags of a tag come from two sources:
 526  *   - manually added related tags, which are tag_instance entries for that tag
 527  *   - correlated tags, which are calculated
 528  *
 529  * @package  core_tag
 530  * @category tag
 531  * @access   public
 532  * @param    string   $tagid          is a single **normalized** tag name or the id of a tag
 533  * @param    int      $type           the function will return either manually (TAG_RELATED_MANUAL) related tags or correlated
 534  *                                    (TAG_RELATED_CORRELATED) tags. Default is TAG_RELATED_ALL, which returns everything.
 535  * @param    int      $limitnum       (optional) return a subset comprising this many records, the default is 10
 536  * @return   array    an array of tag objects
 537  */
 538 function tag_get_related_tags($tagid, $type=TAG_RELATED_ALL, $limitnum=10) {
 539
 540     $related_tags = array();
 541
 542     if ( $type == TAG_RELATED_ALL || $type == TAG_RELATED_MANUAL) {
 543         //gets the manually added related tags
 544         $related_tags = tag_get_tags('tag', $tagid);
 545     }
 546
 547     if ( $type == TAG_RELATED_ALL || $type == TAG_RELATED_CORRELATED ) {
 548         //gets the correlated tags
 549         $automatic_related_tags = tag_get_correlated($tagid);
 550         $related_tags = array_merge($related_tags, $automatic_related_tags);
 551     }
 552
 553     // Remove duplicated tags (multiple instances of the same tag).
 554     $seen = array();
 555     foreach ($related_tags as $instance => $tag) {
 556         if (isset($seen[$tag->id])) {
 557             unset($related_tags[$instance]);
 558         } else {
 559             $seen[$tag->id] = 1;
 560         }
 561     }
 562
 563     return array_slice($related_tags, 0 , $limitnum);
 564 }
 565
 566 /**
 567  * Get a comma-separated list of tags related to another tag.
 568  *
 569  * @package  core_tag
 570  * @category tag
 571  * @access   public
 572  * @param    array    $related_tags the array returned by tag_get_related_tags
 573  * @param    int      $html    either TAG_RETURN_HTML (default) or TAG_RETURN_TEXT : return html links, or just text.
 574  * @return   string   comma-separated list
 575  */
 576 function tag_get_related_tags_csv($related_tags, $html=TAG_RETURN_HTML) {
 577     global $CFG;
 578
 579     $tags_names = array();
 580     foreach($related_tags as $tag) {
 581         if ( $html == TAG_RETURN_TEXT) {
 582             $tags_names[] = tag_display_name($tag, TAG_RETURN_TEXT);
 583         } else {
 584             // TAG_RETURN_HTML
 585             $tags_names[] = '<a href="'. $CFG->wwwroot .'/tag/index.php?tag='. rawurlencode($tag->name) .'">'. tag_display_name($tag) .'</a>';
 586         }
 587     }
 588
 589     return implode(', ', $tags_names);
 590 }
 591
 592 /**
 593  * Change the "value" of a tag, and update the associated 'name'.
 594  *
 595  * @package  core_tag
 596  * @category tag
 597  * @access   public
 598  * @param    int      $tagid  the id of the tag to modify
 599  * @param    string   $newrawname the new rawname
 600  * @return   bool     true on success, false otherwise
 601  */
 602 function tag_rename($tagid, $newrawname) {
 603     global $COURSE, $DB;
 604
 605     $norm = tag_normalize($newrawname, TAG_CASE_ORIGINAL);
 606     if (! $newrawname_clean = array_shift($norm) ) {
 607         return false;
 608     }
 609
 610     if (! $newname_clean = core_text::strtolower($newrawname_clean)) {
 611         return false;
 612     }
 613
 614     // Prevent the rename if a tag with that name already exists
 615     if ($existing = tag_get('name', $newname_clean, 'id, name, rawname')) {
 616         if ($existing->id != $tagid) {  // Another tag already exists with this name
 617             return false;
 618         }
 619     }
 620
 621     if ($tag = tag_get('id', $tagid, 'id, userid, name, rawname')) {
 622         // Store the name before we change it.
 623         $oldname = $tag->name;
 624
 625         $tag->rawname = $newrawname_clean;
 626         $tag->name = $newname_clean;
 627         $tag->timemodified = time();
 628         $DB->update_record('tag', $tag);
 629
 630         $event = \core\event\tag_updated::create(array(
 631             'objectid' => $tag->id,
 632             'relateduserid' => $tag->userid,
 633             'context' => context_system::instance(),
 634             'other' => array(
 635                 'name' => $newname_clean,
 636                 'rawname' => $newrawname_clean
 637             )
 638         ));
 639         $event->set_legacy_logdata(array($COURSE->id, 'tag', 'update', 'index.php?id='. $tag->id, $oldname . '->'. $tag->name));
 640         $event->trigger();
 641
 642         return true;
 643     }
 644     return false;
 645 }
 646
 647
 648 /**
 649  * Delete one or more tag, and all their instances if there are any left.
 650  *
 651  * @package  core_tag
 652  * @category tag
 653  * @access   public
 654  * @param    mixed    $tagids one tagid (int), or one array of tagids to delete
 655  * @return   bool     true on success, false otherwise
 656  */
 657 function tag_delete($tagids) {
 658     global $DB;
 659
 660     if (!is_array($tagids)) {
 661         $tagids = array($tagids);
 662     }
 663
 664     // Use the tagids to create a select statement to be used later.
 665     list($tagsql, $tagparams) = $DB->get_in_or_equal($tagids);
 666
 667     // Store the tags and tag instances we are going to delete.
 668     $tags = $DB->get_records_select('tag', 'id ' . $tagsql, $tagparams);
 669     $taginstances = $DB->get_records_select('tag_instance', 'tagid ' . $tagsql, $tagparams);
 670
 671     // Delete all the tag instances.
 672     $select = 'WHERE tagid ' . $tagsql;
 673     $sql = "DELETE FROM {tag_instance} $select";
 674     $DB->execute($sql, $tagparams);
 675
 676     // Delete all the tag correlations.
 677     $sql = "DELETE FROM {tag_correlation} $select";
 678     $DB->execute($sql, $tagparams);
 679
 680     // Delete all the tags.
 681     $select = 'WHERE id ' . $tagsql;
 682     $sql = "DELETE FROM {tag} $select";
 683     $DB->execute($sql, $tagparams);
 684
 685     // Fire an event that these items were untagged.
 686     if ($taginstances) {
 687         // Save the system context in case the 'contextid' column in the 'tag_instance' table is null.
 688         $syscontextid = context_system::instance()->id;
 689         // Loop through the tag instances and fire a 'tag_removed'' event.
 690         foreach ($taginstances as $taginstance) {
 691             // We can not fire an event with 'null' as the contextid.
 692             if (is_null($taginstance->contextid)) {
 693                 $taginstance->contextid = $syscontextid;
 694             }
 695
 696             // Trigger tag removed event.
 697             $event = \core\event\tag_removed::create(array(
 698                 'objectid' => $taginstance->id,
 699                 'contextid' => $taginstance->contextid,
 700                 'other' => array(
 701                     'tagid' => $taginstance->tagid,
 702                     'tagname' => $tags[$taginstance->tagid]->name,
 703                     'tagrawname' => $tags[$taginstance->tagid]->rawname,
 704                     'itemid' => $taginstance->itemid,
 705                     'itemtype' => $taginstance->itemtype
 706                 )
 707             ));
 708             $event->add_record_snapshot('tag_instance', $taginstance);
 709             $event->trigger();
 710         }
 711     }
 712
 713     // Fire an event that these tags were deleted.
 714     if ($tags) {
 715         $context = context_system::instance();
 716         foreach ($tags as $tag) {
 717             // Delete all files associated with this tag
 718             $fs = get_file_storage();
 719             $files = $fs->get_area_files($context->id, 'tag', 'description', $tag->id);
 720             foreach ($files as $file) {
 721                 $file->delete();
 722             }
 723
 724             // Trigger an event for deleting this tag.
 725             $event = \core\event\tag_deleted::create(array(
 726                 'objectid' => $tag->id,
 727                 'relateduserid' => $tag->userid,
 728                 'context' => $context,
 729                 'other' => array(
 730                     'name' => $tag->name,
 731                     'rawname' => $tag->rawname
 732                 )
 733             ));
 734             $event->add_record_snapshot('tag', $tag);
 735             $event->trigger();
 736         }
 737     }
 738
 739     return true;
 740 }
 741
 742 /**
 743  * Deletes all the tag instances given a component and an optional contextid.
 744  *
 745  * @param string $component
 746  * @param int $contextid if null, then we delete all tag instances for the $component
 747  */
 748 function tag_delete_instances($component, $contextid = null) {
 749     global $DB;
 750
 751     $sql = "SELECT ti.*, t.name, t.rawname
 752               FROM {tag_instance} ti
 753               JOIN {tag} t
 754                 ON ti.tagid = t.id ";
 755     if (is_null($contextid)) {
 756         $params = array('component' => $component);
 757         $sql .= "WHERE ti.component = :component";
 758     } else {
 759         $params = array('component' => $component, 'contextid' => $contextid);
 760         $sql .= "WHERE ti.component = :component
 761                    AND ti.contextid = :contextid";
 762     }
 763     if ($taginstances = $DB->get_records_sql($sql, $params)) {
 764         // Now remove all the tag instances.
 765         $DB->delete_records('tag_instance',$params);
 766         // Save the system context in case the 'contextid' column in the 'tag_instance' table is null.
 767         $syscontextid = context_system::instance()->id;
 768         // Loop through the tag instances and fire an 'tag_removed' event.
 769         foreach ($taginstances as $taginstance) {
 770             // We can not fire an event with 'null' as the contextid.
 771             if (is_null($taginstance->contextid)) {
 772                 $taginstance->contextid = $syscontextid;
 773             }
 774
 775             // Trigger tag removed event.
 776             $event = \core\event\tag_removed::create(array(
 777                 'objectid' => $taginstance->id,
 778                 'contextid' => $taginstance->contextid,
 779                 'other' => array(
 780                     'tagid' => $taginstance->tagid,
 781                     'tagname' => $taginstance->name,
 782                     'tagrawname' => $taginstance->rawname,
 783                     'itemid' => $taginstance->itemid,
 784                     'itemtype' => $taginstance->itemtype
 785                 )
 786             ));
 787             $event->add_record_snapshot('tag_instance', $taginstance);
 788             $event->trigger();
 789         }
 790     }
 791 }
 792
 793 /**
 794  * Delete one instance of a tag.  If the last instance was deleted, it will also delete the tag, unless its type is 'official'.
 795  *
 796  * @package  core_tag
 797  * @category tag
 798  * @access   public
 799  * @param    string $record_type the type of the record for which to remove the instance
 800  * @param    int    $record_id   the id of the record for which to remove the instance
 801  * @param    int    $tagid       the tagid that needs to be removed
 802  * @param    int    $userid      (optional) the userid
 803  * @return   bool   true on success, false otherwise
 804  */
 805 function tag_delete_instance($record_type, $record_id, $tagid, $userid = null) {
 806     global $DB;
 807
 808     if (is_null($userid)) {
 809         $taginstance = $DB->get_record('tag_instance', array('tagid' => $tagid, 'itemtype' => $record_type, 'itemid' => $record_id));
 810     } else {
 811         $taginstance = $DB->get_record('tag_instance', array('tagid' => $tagid, 'itemtype' => $record_type, 'itemid' => $record_id,
 812             'tiuserid' => $userid));
 813     }
 814     if ($taginstance) {
 815         // Get the tag.
 816         $tag = $DB->get_record('tag', array('id' => $tagid));
 817
 818         $DB->delete_records('tag_instance', array('id' => $taginstance->id));
 819
 820         // We can not fire an event with 'null' as the contextid.
 821         if (is_null($taginstance->contextid)) {
 822             $taginstance->contextid = context_system::instance()->id;
 823         }
 824
 825         // Trigger tag removed event.
 826         $event = \core\event\tag_removed::create(array(
 827             'objectid' => $taginstance->id,
 828             'contextid' => $taginstance->contextid,
 829             'other' => array(
 830                 'tagid' => $tag->id,
 831                 'tagname' => $tag->name,
 832                 'tagrawname' => $tag->rawname,
 833                 'itemid' => $taginstance->itemid,
 834                 'itemtype' => $taginstance->itemtype
 835             )
 836         ));
 837         $event->add_record_snapshot('tag_instance', $taginstance);
 838         $event->trigger();
 839
 840         // If there are no other instances of the tag then consider deleting the tag as well.
 841         if (!$DB->record_exists('tag_instance', array('tagid' => $tagid))) {
 842             // If the tag is a personal tag then delete it - don't delete official tags.
 843             if ($tag->tagtype == 'default') {
 844                 tag_delete($tagid);
 845             }
 846         }
 847     } else {
 848         return false;
 849     }
 850
 851     return true;
 852 }
 853
 854
 855 /**
 856  * Function that returns the name that should be displayed for a specific tag
 857  *
 858  * @package  core_tag
 859  * @category tag
 860  * @access   public
 861  * @param    object   $tagobject a line out of tag table, as returned by the adobd functions
 862  * @param    int      $html TAG_RETURN_HTML (default) will return htmlspecialchars encoded string, TAG_RETURN_TEXT will not encode.
 863  * @return   string
 864  */
 865 function tag_display_name($tagobject, $html=TAG_RETURN_HTML) {
 866     global $CFG;
 867
 868     if (!isset($tagobject->name)) {
 869         return '';
 870     }
 871
 872     if (empty($CFG->keeptagnamecase)) {
 873         //this is the normalized tag name
 874         $tagname = core_text::strtotitle($tagobject->name);
 875     } else {
 876         //original casing of the tag name
 877         $tagname = $tagobject->rawname;
 878     }
 879
 880     // clean up a bit just in case the rules change again
 881     $tagname = clean_param($tagname, PARAM_TAG);
 882
 883     if ($html == TAG_RETURN_TEXT) {
 884         return $tagname;
 885     } else { // TAG_RETURN_HTML
 886         return htmlspecialchars($tagname);
 887     }
 888 }
 889
 890 /**
 891  * Find all records tagged with a tag of a given type ('post', 'user', etc.)
 892  *
 893  * @package  core_tag
 894  * @category tag
 895  * @access   public
 896  * @param    string   $tag       tag to look for
 897  * @param    string   $type      type to restrict search to.  If null, every matching record will be returned
 898  * @param    int      $limitfrom (optional, required if $limitnum is set) return a subset of records, starting at this point.
 899  * @param    int      $limitnum  (optional, required if $limitfrom is set) return a subset comprising this many records.
 900  * @return   array of matching objects, indexed by record id, from the table containing the type requested
 901  */
 902 function tag_find_records($tag, $type, $limitfrom='', $limitnum='') {
 903     global $CFG, $DB;
 904
 905     if (!$tag || !$type) {
 906         return array();
 907     }
 908
 909     $tagid = tag_get_id($tag);
 910
 911     $query = "SELECT it.*
 912                 FROM {".$type."} it INNER JOIN {tag_instance} tt ON it.id = tt.itemid
 913                WHERE tt.itemtype = ? AND tt.tagid = ?";
 914     $params = array($type, $tagid);
 915
 916     return $DB->get_records_sql($query, $params, $limitfrom, $limitnum);
 917 }
 918
 919
 920
 921
 922 ///////////////////////////////////////////////////////
 923 /////////////////// PRIVATE TAG API ///////////////////
 924
 925 /**
 926  * Adds one or more tag in the database.  This function should not be called directly : you should
 927  * use tag_set.
 928  *
 929  * @package core_tag
 930  * @access  private
 931  * @param   mixed    $tags     one tag, or an array of tags, to be created
 932  * @param   string   $type     type of tag to be created ("default" is the default value and "official" is the only other supported
 933  *                             value at this time). An official tag is kept even if there are no records tagged with it.
 934  * @return array     $tags ids indexed by their lowercase normalized names. Any boolean false in the array indicates an error while
 935  *                             adding the tag.
 936  */
 937 function tag_add($tags, $type="default") {
 938     global $USER, $DB;
 939
 940     if (!is_array($tags)) {
 941         $tags = array($tags);
 942     }
 943
 944     $tag_object = new StdClass;
 945     $tag_object->tagtype      = $type;
 946     $tag_object->userid       = $USER->id;
 947     $tag_object->timemodified = time();
 948
 949     $clean_tags = tag_normalize($tags, TAG_CASE_ORIGINAL);
 950
 951     $tags_ids = array();
 952     foreach($clean_tags as $tag) {
 953         $tag = trim($tag);
 954         if (!$tag) {
 955             $tags_ids[$tag] = false;
 956         } else {
 957             // note that the difference between rawname and name is only
 958             // capitalization : the rawname is NOT the same at the rawtag.
 959             $tag_object->rawname = $tag;
 960             $tag_name_lc         = core_text::strtolower($tag);
 961             $tag_object->name    = $tag_name_lc;
 962             //var_dump($tag_object);
 963             $tags_ids[$tag_name_lc] = $DB->insert_record('tag', $tag_object);
 964
 965             $event = \core\event\tag_created::create(array(
 966                 'objectid' => $tags_ids[$tag_name_lc],
 967                 'relateduserid' => $tag_object->userid,
 968                 'context' => context_system::instance(),
 969                 'other' => array(
 970                     'name' => $tag_object->name,
 971                     'rawname' => $tag_object->rawname
 972                 )
 973             ));
 974             $event->trigger();
 975         }
 976     }
 977
 978     return $tags_ids;
 979 }
 980
 981 /**
 982  * Assigns a tag to a record; if the record already exists, the time and ordering will be updated.
 983  *
 984  * @package core_tag
 985  * @access private
 986  * @param string $record_type the type of the record that will be tagged
 987  * @param int $record_id the id of the record that will be tagged
 988  * @param string $tagid the tag id to set on the record.
 989  * @param int $ordering the order of the instance for this record
 990  * @param int $userid (optional) only required for course tagging
 991  * @param string|null $component the component that was tagged
 992  * @param int|null $contextid the context id of where this tag was assigned
 993  * @return bool true on success, false otherwise
 994  */
 995 function tag_assign($record_type, $record_id, $tagid, $ordering, $userid = 0, $component = null, $contextid = null) {
 996     global $DB;
 997
 998     if ($component === null || $contextid === null) {
 999         debugging('You should specify the component and contextid of the item being tagged in your call to tag_assign.',
1000             DEBUG_DEVELOPER);
1001     }
1002
1003     // Get the tag.
1004     $tag = $DB->get_record('tag', array('id' => $tagid), 'name, rawname', MUST_EXIST);
1005
1006     if ( $tag_instance_object = $DB->get_record('tag_instance', array('tagid'=>$tagid, 'itemtype'=>$record_type, 'itemid'=>$record_id, 'tiuserid'=>$userid), 'id')) {
1007         $tag_instance_object->ordering     = $ordering;
1008         $tag_instance_object->timemodified = time();
1009
1010         $DB->update_record('tag_instance', $tag_instance_object);
1011     } else {
1012         $tag_instance_object = new StdClass;
1013         $tag_instance_object->tagid        = $tagid;
1014         $tag_instance_object->component    = $component;
1015         $tag_instance_object->itemid       = $record_id;
1016         $tag_instance_object->itemtype     = $record_type;
1017         $tag_instance_object->contextid    = $contextid;
1018         $tag_instance_object->ordering     = $ordering;
1019         $tag_instance_object->timecreated  = time();
1020         $tag_instance_object->timemodified = $tag_instance_object->timecreated;
1021         $tag_instance_object->tiuserid     = $userid;
1022
1023         $tag_instance_object->id = $DB->insert_record('tag_instance', $tag_instance_object);
1024     }
1025
1026     // We can not fire an event with 'null' as the contextid.
1027     if (is_null($contextid)) {
1028         $contextid = context_system::instance()->id;
1029     }
1030
1031     // Trigger tag added event.
1032     $event = \core\event\tag_added::create(array(
1033         'objectid' => $tag_instance_object->id,
1034         'contextid' => $contextid,
1035         'other' => array(
1036             'tagid' => $tagid,
1037             'tagname' => $tag->name,
1038             'tagrawname' => $tag->rawname,
1039             'itemid' => $record_id,
1040             'itemtype' => $record_type
1041         )
1042     ));
1043     $event->trigger();
1044
1045     return true;
1046 }
1047
1048 /**
1049  * Clean up the tag tables, making sure all tagged object still exists.
1050  *
1051  * This should normally not be necessary, but in case related tags are not deleted when the tagged record is removed, this should be
1052  * done once in a while, perhaps on an occasional cron run.  On a site with lots of tags, this could become an expensive function to
1053  * call: don't run at peak time.
1054  *
1055  * @package core_tag
1056  * @access  private
1057  * @todo    MDL-31212 Update tag cleanup sql so that it supports multiple types of tags
1058  */
1059 function tag_cleanup() {
1060     global $DB;
1061
1062     // Get ids to delete from instances where the tag has been deleted. This should never happen apparently.
1063     $sql = "SELECT ti.id
1064               FROM {tag_instance} ti
1065          LEFT JOIN {tag} t ON t.id = ti.tagid
1066              WHERE t.id IS null";
1067     $tagids = $DB->get_records_sql($sql);
1068     $tagarray = array();
1069     foreach ($tagids as $tagid) {
1070         $tagarray[] = $tagid->id;
1071     }
1072
1073     // Next get ids from instances that have an owner that has been deleted.
1074     $sql = "SELECT ti.id
1075               FROM {tag_instance} ti, {user} u
1076              WHERE ti.itemid = u.id
1077                AND ti.itemtype = 'user'
1078                AND u.deleted = 1";
1079     $tagids = $DB->get_records_sql($sql);
1080     foreach ($tagids as $tagid) {
1081         $tagarray[] = $tagid->id;
1082     }
1083
1084     // Get the other itemtypes.
1085     $sql = "SELECT itemtype
1086               FROM {tag_instance}
1087              WHERE itemtype <> 'user'
1088           GROUP BY itemtype";
1089     $tagitemtypes = $DB->get_records_sql($sql);
1090     foreach ($tagitemtypes as $key => $notused) {
1091         $sql = 'SELECT ti.id
1092                   FROM {tag_instance} ti
1093              LEFT JOIN {' . $key . '} it ON it.id = ti.itemid
1094                  WHERE it.id IS null
1095                  AND ti.itemtype = \'' . $key . '\'';
1096         $tagids = $DB->get_records_sql($sql);
1097         foreach ($tagids as $tagid) {
1098             $tagarray[] = $tagid->id;
1099         }
1100     }
1101
1102     // Get instances for each of the ids to be deleted.
1103     if (count($tagarray) > 0) {
1104         list($sqlin, $params) = $DB->get_in_or_equal($tagarray);
1105         $sql = "SELECT ti.*, COALESCE(t.name, 'deleted') AS name, COALESCE(t.rawname, 'deleted') AS rawname
1106                   FROM {tag_instance} ti
1107              LEFT JOIN {tag} t ON t.id = ti.tagid
1108                  WHERE ti.id $sqlin";
1109         $instances = $DB->get_records_sql($sql, $params);
1110         tag_bulk_delete_instances($instances);
1111     }
1112
1113     // TODO MDL-31212 this will only clean tags of type 'default'.  This is good as
1114     // it won't delete 'official' tags, but the day we get more than two
1115     // types, we need to fix this.
1116     $unused_tags = $DB->get_recordset_sql("SELECT tg.id
1117                                              FROM {tag} tg
1118                                             WHERE tg.tagtype = 'default'
1119                                                   AND NOT EXISTS (
1120                                                       SELECT 'x'
1121                                                         FROM {tag_instance} ti
1122                                                        WHERE ti.tagid = tg.id
1123                                                   )");
1124
1125     // cleanup tags
1126     foreach ($unused_tags as $unused_tag) {
1127         tag_delete($unused_tag->id);
1128         //debugging('deleting unused tag #'. $unused_tag->id,  DEBUG_DEVELOPER);
1129     }
1130     $unused_tags->close();
1131 }
1132
1133 /**
1134  * This function will delete numerous tag instances efficiently.
1135  * This removes tag instances only. It doesn't check to see if it is the last use of a tag.
1136  *
1137  * @param array $instances An array of tag instance objects with the addition of the tagname and tagrawname
1138  *        (used for recording a delete event).
1139  */
1140 function tag_bulk_delete_instances($instances) {
1141     global $DB;
1142
1143     $instanceids = array();
1144     foreach ($instances as $instance) {
1145         $instanceids[] = $instance->id;
1146     }
1147
1148     // This is a multi db compatible method of creating the correct sql when using the 'IN' value.
1149     // $insql is the sql statement, $params are the id numbers.
1150     list($insql, $params) = $DB->get_in_or_equal($instanceids);
1151     $sql = 'id ' . $insql;
1152     $DB->delete_records_select('tag_instance', $sql, $params);
1153
1154     // Now go through and record each tag individually with the event system.
1155     foreach ($instances as $instance) {
1156         // Trigger tag removed event (i.e. The tag instance has been removed).
1157         $event = \core\event\tag_removed::create(array(
1158             'objectid' => $instance->id,
1159             'contextid' => $instance->contextid,
1160             'other' => array(
1161                 'tagid' => $instance->tagid,
1162                 'tagname' => $instance->name,
1163                 'tagrawname' => $instance->rawname,
1164                 'itemid' => $instance->itemid,
1165                 'itemtype' => $instance->itemtype
1166             )
1167         ));
1168         unset($instance->name);
1169         unset($instance->rawname);
1170         $event->add_record_snapshot('tag_instance', $instance);
1171         $event->trigger();
1172     }
1173 }
1174
1175 /**
1176  * Calculates and stores the correlated tags of all tags. The correlations are stored in the 'tag_correlation' table.
1177  *
1178  * Two tags are correlated if they appear together a lot. Ex.: Users tagged with "computers" will probably also be tagged with "algorithms".
1179  *
1180  * The rationale for the 'tag_correlation' table is performance. It works as a cache for a potentially heavy load query done at the
1181  * 'tag_instance' table. So, the 'tag_correlation' table stores redundant information derived from the 'tag_instance' table.
1182  *
1183  * @package core_tag
1184  * @access  private
1185  * @param   int      $mincorrelation Only tags with more than $mincorrelation correlations will be identified.
1186  */
1187 function tag_compute_correlations($mincorrelation = 2) {
1188     global $DB;
1189
1190     // This mighty one line query fetches a row from the database for every
1191     // individual tag correlation. We then need to process the rows collecting
1192     // the correlations for each tag id.
1193     // The fields used by this query are as follows:
1194     //   tagid         : This is the tag id, there should be at least $mincorrelation
1195     //                   rows for each tag id.
1196     //   correlation   : This is the tag id that correlates to the above tagid field.
1197     //   correlationid : This is the id of the row in the tag_correlation table that
1198     //                   relates to the tagid field and will be NULL if there are no
1199     //                   existing correlations
1200     $sql = 'SELECT pairs.tagid, pairs.correlation, pairs.ocurrences, co.id AS correlationid
1201               FROM (
1202                        SELECT ta.tagid, tb.tagid AS correlation, COUNT(*) AS ocurrences
1203                          FROM {tag_instance} ta
1204                          JOIN {tag_instance} tb ON (ta.itemtype = tb.itemtype AND ta.itemid = tb.itemid AND ta.tagid <> tb.tagid)
1205                      GROUP BY ta.tagid, tb.tagid
1206                        HAVING COUNT(*) > :mincorrelation
1207                    ) pairs
1208          LEFT JOIN {tag_correlation} co ON co.tagid = pairs.tagid
1209           ORDER BY pairs.tagid ASC, pairs.ocurrences DESC, pairs.correlation ASC';
1210     $rs = $DB->get_recordset_sql($sql, array('mincorrelation' => $mincorrelation));
1211
1212     // Set up an empty tag correlation object
1213     $tagcorrelation = new stdClass;
1214     $tagcorrelation->id = null;
1215     $tagcorrelation->tagid = null;
1216     $tagcorrelation->correlatedtags = array();
1217
1218     // We store each correlation id in this array so we can remove any correlations
1219     // that no longer exist.
1220     $correlations = array();
1221
1222     // Iterate each row of the result set and build them into tag correlations.
1223     // We add all of a tag's correlations to $tagcorrelation->correlatedtags[]
1224     // then save the $tagcorrelation object
1225     foreach ($rs as $row) {
1226         if ($row->tagid != $tagcorrelation->tagid) {
1227             // The tag id has changed so we have all of the correlations for this tag
1228             $tagcorrelationid = tag_process_computed_correlation($tagcorrelation);
1229             if ($tagcorrelationid) {
1230                 $correlations[] = $tagcorrelationid;
1231             }
1232             // Now we reset the tag correlation object so we can reuse it and set it
1233             // up for the current record.
1234             $tagcorrelation = new stdClass;
1235             $tagcorrelation->id = $row->correlationid;
1236             $tagcorrelation->tagid = $row->tagid;
1237             $tagcorrelation->correlatedtags = array();
1238         }
1239         //Save the correlation on the tag correlation object
1240         $tagcorrelation->correlatedtags[] = $row->correlation;
1241     }
1242     // Update the current correlation after the last record.
1243     $tagcorrelationid = tag_process_computed_correlation($tagcorrelation);
1244     if ($tagcorrelationid) {
1245         $correlations[] = $tagcorrelationid;
1246     }
1247
1248
1249     // Close the recordset
1250     $rs->close();
1251
1252     // Remove any correlations that weren't just identified
1253     if (empty($correlations)) {
1254         //there are no tag correlations
1255         $DB->delete_records('tag_correlation');
1256     } else {
1257         list($sql, $params) = $DB->get_in_or_equal($correlations, SQL_PARAMS_NAMED, 'param0000', false);
1258         $DB->delete_records_select('tag_correlation', 'id '.$sql, $params);
1259     }
1260 }
1261
1262 /**
1263  * This function processes a tag correlation and makes changes in the database as required.
1264  *
1265  * The tag correlation object needs have both a tagid property and a correlatedtags property that is an array.
1266  *
1267  * @package core_tag
1268  * @access  private
1269  * @param   stdClass $tagcorrelation
1270  * @return  int/bool The id of the tag correlation that was just processed or false.
1271  */
1272 function tag_process_computed_correlation(stdClass $tagcorrelation) {
1273     global $DB;
1274
1275     // You must provide a tagid and correlatedtags must be set and be an array
1276     if (empty($tagcorrelation->tagid) || !isset($tagcorrelation->correlatedtags) || !is_array($tagcorrelation->correlatedtags)) {
1277         return false;
1278     }
1279
1280     $tagcorrelation->correlatedtags = join(',', $tagcorrelation->correlatedtags);
1281     if (!empty($tagcorrelation->id)) {
1282         // The tag correlation already exists so update it
1283         $DB->update_record('tag_correlation', $tagcorrelation);
1284     } else {
1285         // This is a new correlation to insert
1286         $tagcorrelation->id = $DB->insert_record('tag_correlation', $tagcorrelation);
1287     }
1288     return $tagcorrelation->id;
1289 }
1290
1291 /**
1292  * Tasks that should be performed at cron time
1293  *
1294  * @package core_tag
1295  * @access private
1296  */
1297 function tag_cron() {
1298     tag_compute_correlations();
1299     tag_cleanup();
1300 }
1301
1302 /**
1303  * Search for tags with names that match some text
1304  *
1305  * @package core_tag
1306  * @access  private
1307  * @param   string        $text      escaped string that the tag names will be matched against
1308  * @param   bool          $ordered   If true, tags are ordered by their popularity. If false, no ordering.
1309  * @param   int/string    $limitfrom (optional, required if $limitnum is set) return a subset of records, starting at this point.
1310  * @param   int/string    $limitnum  (optional, required if $limitfrom is set) return a subset comprising this many records.
1311  * @return  array/boolean an array of objects, or false if no records were found or an error occured.
1312  */
1313 function tag_find_tags($text, $ordered=true, $limitfrom='', $limitnum='') {
1314     global $DB;
1315
1316     $norm = tag_normalize($text, TAG_CASE_LOWER);
1317     $text = array_shift($norm);
1318
1319     if ($ordered) {
1320         $query = "SELECT tg.id, tg.name, tg.rawname, COUNT(ti.id) AS count
1321                     FROM {tag} tg LEFT JOIN {tag_instance} ti ON tg.id = ti.tagid
1322                    WHERE tg.name LIKE ?
1323                 GROUP BY tg.id, tg.name, tg.rawname
1324                 ORDER BY count DESC";
1325     } else {
1326         $query = "SELECT tg.id, tg.name, tg.rawname
1327                     FROM {tag} tg
1328                    WHERE tg.name LIKE ?";
1329     }
1330     $params = array("%{$text}%");
1331     return $DB->get_records_sql($query, $params, $limitfrom , $limitnum);
1332 }
1333
1334 /**
1335  * Get the name of a tag
1336  *
1337  * @package core_tag
1338  * @access  private
1339  * @param   mixed    $tagids the id of the tag, or an array of ids
1340  * @return  mixed    string name of one tag, or id-indexed array of strings
1341  */
1342 function tag_get_name($tagids) {
1343     global $DB;
1344
1345     if (!is_array($tagids)) {
1346         if ($tag = $DB->get_record('tag', array('id'=>$tagids))) {
1347             return $tag->name;
1348         }
1349         return false;
1350     }
1351
1352     $tag_names = array();
1353     foreach($DB->get_records_list('tag', 'id', $tagids) as $tag) {
1354         $tag_names[$tag->id] = $tag->name;
1355     }
1356
1357     return $tag_names;
1358 }
1359
1360 /**
1361  * Returns the correlated tags of a tag, retrieved from the tag_correlation table. Make sure cron runs, otherwise the table will be
1362  * empty and this function won't return anything.
1363  *
1364  * Correlated tags are calculated in cron based on existing tag instances.
1365  *
1366  * This function will return as many entries as there are existing tag instances,
1367  * which means that there will be duplicates for each tag.
1368  *
1369  * If you need only one record for each correlated tag please call:
1370  *      tag_get_related_tags($tag_id, TAG_RELATED_CORRELATED);
1371  *
1372  * @package core_tag
1373  * @access  private
1374  * @param   int      $tag_id   is a single tag id
1375  * @param   int      $notused  this argument is no longer used
1376  * @return  array    an array of tag objects or an empty if no correlated tags are found
1377  */
1378 function tag_get_correlated($tag_id, $notused = null) {
1379     global $DB;
1380
1381     $tag_correlation = $DB->get_record('tag_correlation', array('tagid'=>$tag_id));
1382
1383     if (!$tag_correlation || empty($tag_correlation->correlatedtags)) {
1384         return array();
1385     }
1386
1387     // this is (and has to) return the same fields as the query in tag_get_tags
1388     $sql = "SELECT ti.id AS taginstanceid, tg.id, tg.tagtype, tg.name, tg.rawname, tg.flag, ti.ordering
1389               FROM {tag} tg
1390         INNER JOIN {tag_instance} ti ON tg.id = ti.tagid
1391              WHERE tg.id IN ({$tag_correlation->correlatedtags})
1392           ORDER BY ti.ordering ASC";
1393     return $DB->get_records_sql($sql);
1394 }
1395
1396 /**
1397  * Function that normalizes a list of tag names.
1398  *
1399  * @package core_tag
1400  * @access  private
1401  * @param   array/string $rawtags array of tags, or a single tag.
1402  * @param   int          $case    case to use for returned value (default: lower case). Either TAG_CASE_LOWER (default) or TAG_CASE_ORIGINAL
1403  * @return  array        lowercased normalized tags, indexed by the normalized tag, in the same order as the original array.
1404  *                       (Eg: 'Banana' => 'banana').
1405  */
1406 function tag_normalize($rawtags, $case = TAG_CASE_LOWER) {
1407
1408     // cache normalized tags, to prevent costly repeated calls to clean_param
1409     static $cleaned_tags_lc = array(); // lower case - use for comparison
1410     static $cleaned_tags_mc = array(); // mixed case - use for saving to database
1411
1412     if ( !is_array($rawtags) ) {
1413         $rawtags = array($rawtags);
1414     }
1415
1416     $result = array();
1417     foreach($rawtags as $rawtag) {
1418         $rawtag = trim($rawtag);
1419         if (!$rawtag) {
1420             continue;
1421         }
1422         if ( !array_key_exists($rawtag, $cleaned_tags_lc) ) {
1423             $cleaned_tags_lc[$rawtag] = core_text::strtolower( clean_param($rawtag, PARAM_TAG) );
1424             $cleaned_tags_mc[$rawtag] = clean_param($rawtag, PARAM_TAG);
1425         }
1426         if ( $case == TAG_CASE_LOWER ) {
1427             $result[$rawtag] = $cleaned_tags_lc[$rawtag];
1428         } else { // TAG_CASE_ORIGINAL
1429             $result[$rawtag] = $cleaned_tags_mc[$rawtag];
1430         }
1431     }
1432
1433     return $result;
1434 }
1435
1436 /**
1437  * Count how many records are tagged with a specific tag.
1438  *
1439  * @package core_tag
1440  * @access  private
1441  * @param   string   $record_type record to look for ('post', 'user', etc.)
1442  * @param   int      $tagid       is a single tag id
1443  * @return  int      number of mathing tags.
1444  */
1445 function tag_record_count($record_type, $tagid) {
1446     global $DB;
1447     return $DB->count_records('tag_instance', array('itemtype'=>$record_type, 'tagid'=>$tagid));
1448 }
1449
1450 /**
1451  * Determine if a record is tagged with a specific tag
1452  *
1453  * @package core_tag
1454  * @access  private
1455  * @param   string   $record_type the record type to look for
1456  * @param   int      $record_id   the record id to look for
1457  * @param   string   $tag         a tag name
1458  * @return  bool/int true if it is tagged, 0 (false) otherwise
1459  */
1460 function tag_record_tagged_with($record_type, $record_id, $tag) {
1461     global $DB;
1462     if ($tagid = tag_get_id($tag)) {
1463         return $DB->count_records('tag_instance', array('itemtype'=>$record_type, 'itemid'=>$record_id, 'tagid'=>$tagid));
1464     } else {
1465         return 0; // tag doesn't exist
1466     }
1467 }
1468
1469 /**
1470  * Flag a tag as inappropriate.
1471  *
1472  * @param int|array $tagids a single tagid, or an array of tagids
1473  */
1474 function tag_set_flag($tagids) {
1475     global $DB;
1476
1477     $tagids = (array) $tagids;
1478
1479     // Use the tagids to create a select statement to be used later.
1480     list($tagsql, $tagparams) = $DB->get_in_or_equal($tagids, SQL_PARAMS_NAMED);
1481
1482     // Update all the tags to flagged.
1483     $sql = "UPDATE {tag}
1484                SET flag = flag + 1, timemodified = :time
1485              WHERE id $tagsql";
1486
1487     // Update all the tags.
1488     $DB->execute($sql, array_merge(array('time' => time()), $tagparams));
1489
1490     // Get all the tags.
1491     if ($tags = $DB->get_records_select('tag', 'id '. $tagsql, $tagparams, 'id ASC')) {
1492         // Loop through and fire an event for each tag that it was flagged.
1493         foreach ($tags as $tag) {
1494             $event = \core\event\tag_flagged::create(array(
1495                 'objectid' => $tag->id,
1496                 'relateduserid' => $tag->userid,
1497                 'context' => context_system::instance(),
1498                 'other' => array(
1499                     'name' => $tag->name,
1500                     'rawname' => $tag->rawname
1501                 )
1502
1503             ));
1504             $event->add_record_snapshot('tag', $tag);
1505             $event->trigger();
1506         }
1507     }
1508 }
1509
1510 /**
1511  * Remove the inappropriate flag on a tag.
1512  *
1513  * @param int|array $tagids a single tagid, or an array of tagids
1514  */
1515 function tag_unset_flag($tagids) {
1516     global $DB;
1517
1518     $tagids = (array) $tagids;
1519
1520     // Use the tagids to create a select statement to be used later.
1521     list($tagsql, $tagparams) = $DB->get_in_or_equal($tagids, SQL_PARAMS_NAMED);
1522
1523     // Update all the tags to unflagged.
1524     $sql = "UPDATE {tag}
1525                SET flag = 0, timemodified = :time
1526              WHERE id $tagsql";
1527
1528     // Update all the tags.
1529     $DB->execute($sql, array_merge(array('time' => time()), $tagparams));
1530
1531     // Get all the tags.
1532     if ($tags = $DB->get_records_select('tag', 'id '. $tagsql, $tagparams, 'id ASC')) {
1533         // Loop through and fire an event for each tag that it was unflagged.
1534         foreach ($tags as $tag) {
1535             $event = \core\event\tag_unflagged::create(array(
1536                 'objectid' => $tag->id,
1537                 'relateduserid' => $tag->userid,
1538                 'context' => context_system::instance(),
1539                 'other' => array(
1540                     'name' => $tag->name,
1541                     'rawname' => $tag->rawname
1542                 )
1543             ));
1544             $event->add_record_snapshot('tag', $tag);
1545             $event->trigger();
1546         }
1547     }
1548 }
1549
1550 /**
1551  * Return a list of page types
1552  *
1553  * @package core_tag
1554  * @access  private
1555  * @param   string   $pagetype       current page type
1556  * @param   stdClass $parentcontext  Block's parent context
1557  * @param   stdClass $currentcontext Current context of block
1558  */
1559 function tag_page_type_list($pagetype, $parentcontext, $currentcontext) {
1560     return array(
1561         'tag-*'=>get_string('page-tag-x', 'tag'),
1562         'tag-index'=>get_string('page-tag-index', 'tag'),
1563         'tag-search'=>get_string('page-tag-search', 'tag'),
1564         'tag-manage'=>get_string('page-tag-manage', 'tag')
1565     );
1566 }