tag/lib.php

   1 <?php
   2
   3 // This file is part of Moodle - http://moodle.org/
   4 //
   5 // Moodle is free software: you can redistribute it and/or modify
   6 // it under the terms of the GNU General Public License as published by
   7 // the Free Software Foundation, either version 3 of the License, or
   8 // (at your option) any later version.
   9 //
  10 // Moodle is distributed in the hope that it will be useful,
  11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 // GNU General Public License for more details.
  14 //
  15 // You should have received a copy of the GNU General Public License
  16 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  17
  18 /**
  19  * Moodle tag library
  20  *
  21  * Tag strings : you can use any character in tags, except the comma (which is
  22  * the separator) and the '\' (backslash).  Note that many spaces (or other
  23  * blank characters) will get "compressed" into one. A tag string is always a
  24  * rawurlencode'd string. This is the same behavior as http://del.icio.us.
  25  *
  26  * A "record" is a php array (note that an object will work too) that contains
  27  * the following variables :
  28  *  - type: the table containing the record that we are tagging (eg: for a
  29  *    blog, this is table 'post', and for a user it is 'user')
  30  *  - id: the id of the record
  31  *
  32  * TODO: turn this into a full-fledged categorization system. This could start
  33  * by modifying (removing, probably) the 'tag type' to use another table
  34  * describing the relationship between tags (parents, sibling, etc.), which
  35  * could then be merged with the 'course categorization' system...
  36  *
  37  * BASIC INSTRUCTIONS :
  38  *  - to "tag a blog post" (for example):
  39  *        tag_set('post', $blog_post->id, $array_of_tags);
  40  *
  41  *  - to "remove all the tags on a blog post":
  42  *        tag_set('post', $blog_post->id, array());
  43  *
  44  * Tag set will create tags that need to be created.
  45  *
  46  * @package    core
  47  * @subpackage tag
  48  * @see http://www.php.net/manual/en/function.urlencode.php
  49  * @copyright  2007 Luiz Cruz <luiz.laydner@gmail.com>
  50  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  51  */
  52
  53 define('TAG_RETURN_ARRAY', 0);
  54 define('TAG_RETURN_OBJECT', 1);
  55 define('TAG_RETURN_TEXT', 2);
  56 define('TAG_RETURN_HTML', 3);
  57
  58 define('TAG_CASE_LOWER', 0);
  59 define('TAG_CASE_ORIGINAL', 1);
  60
  61 define('TAG_RELATED_ALL', 0);
  62 define('TAG_RELATED_MANUAL', 1);
  63 define('TAG_RELATED_CORRELATED', 2);
  64
  65 ///////////////////////////////////////////////////////
  66 /////////////////// PUBLIC TAG API ////////////////////
  67
  68 /// Functions for settings tags  //////////////////////
  69
  70 /**
  71  * Set the tags assigned to a record.  This overwrites the current tags.
  72  *
  73  * This function is meant to be fed the string coming up from the user
  74  * interface, which contains all tags assigned to a record.
  75  *
  76  * @param string $record_type the type of record to tag ('post' for blogs,
  77  *     'user' for users, 'tag' for tags, etc.
  78  * @param int $record_id the id of the record to tag
  79  * @param array $tags the array of tags to set on the record. If
  80  *     given an empty array, all tags will be removed.
  81  * @return void
  82  */
  83 function tag_set($record_type, $record_id, $tags) {
  84
  85     static $in_recursion_semaphore = false; // this is to prevent loops when tagging a tag
  86     if ( $record_type == 'tag' && !$in_recursion_semaphore) {
  87         $current_tagged_tag_name = tag_get_name($record_id);
  88     }
  89
  90     $tags_ids = tag_get_id($tags, TAG_RETURN_ARRAY); // force an array, even if we only have one tag.
  91     $cleaned_tags = tag_normalize($tags);
  92     //echo 'tags-in-tag_set'; var_dump($tags); var_dump($tags_ids); var_dump($cleaned_tags);
  93
  94     $current_ids = tag_get_tags_ids($record_type, $record_id);
  95     //var_dump($current_ids);
  96
  97     // for data coherence reasons, it's better to remove deleted tags
  98     // before adding new data: ordering could be duplicated.
  99     foreach($current_ids as $current_id) {
 100         if (!in_array($current_id, $tags_ids)) {
 101             tag_delete_instance($record_type, $record_id, $current_id);
 102             if ( $record_type == 'tag' && !$in_recursion_semaphore) {
 103                 // if we are removing a tag-on-a-tag (manually related tag),
 104                 // we need to remove the opposite relationship as well.
 105                 tag_delete_instance('tag', $current_id, $record_id);
 106             }
 107         }
 108     }
 109
 110     if (empty($tags)) {
 111         return true;
 112     }
 113
 114     foreach($tags as $ordering => $tag) {
 115         $tag = trim($tag);
 116         if (!$tag) {
 117             continue;
 118         }
 119
 120         $clean_tag = $cleaned_tags[$tag];
 121         $tag_current_id = $tags_ids[$clean_tag];
 122
 123         if ( is_null($tag_current_id) ) {
 124             // create new tags
 125             //echo "call to add tag $tag\n";
 126             $new_tag = tag_add($tag);
 127             $tag_current_id = $new_tag[$clean_tag];
 128         }
 129
 130         tag_assign($record_type, $record_id, $tag_current_id, $ordering);
 131
 132         // if we are tagging a tag (adding a manually-assigned related tag), we
 133         // need to create the opposite relationship as well.
 134         if ( $record_type == 'tag' && !$in_recursion_semaphore) {
 135             $in_recursion_semaphore = true;
 136             tag_set_add('tag', $tag_current_id, $current_tagged_tag_name);
 137             $in_recursion_semaphore = false;
 138         }
 139     }
 140 }
 141
 142 /**
 143  * Adds a tag to a record, without overwriting the current tags.
 144  *
 145  * @param string $record_type the type of record to tag ('post' for blogs,
 146  *     'user' for users, etc.
 147  * @param int $record_id the id of the record to tag
 148  * @param string $tag the tag to add
 149  * @return void
 150  */
 151 function tag_set_add($record_type, $record_id, $tag) {
 152
 153     $new_tags = array();
 154     foreach( tag_get_tags($record_type, $record_id) as $current_tag ) {
 155         $new_tags[] = $current_tag->rawname;
 156     }
 157     $new_tags[] = $tag;
 158
 159     return tag_set($record_type, $record_id, $new_tags);
 160 }
 161
 162 /**
 163  * Removes a tag from a record, without overwriting other current tags.
 164  *
 165  * @param string $record_type the type of record to tag ('post' for blogs,
 166  *     'user' for users, etc.
 167  * @param int $record_id the id of the record to tag
 168  * @param string $tag the tag to delete
 169  * @return void
 170  */
 171 function tag_set_delete($record_type, $record_id, $tag) {
 172
 173     $new_tags = array();
 174     foreach( tag_get_tags($record_type, $record_id) as $current_tag ) {
 175         if ($current_tag->name != $tag) {  // Keep all tags but the one specified
 176             $new_tags[] = $current_tag->name;
 177         }
 178     }
 179
 180     return tag_set($record_type, $record_id, $new_tags);
 181 }
 182
 183 /**
 184  * Set the type of a tag.  At this time (version 1.9) the possible values
 185  * are 'default' or 'official'.  Official tags will be displayed separately "at
 186  * tagging time" (while selecting the tags to apply to a record).
 187  *
 188  * @param string $tagid tagid to modify
 189  * @param string $type either 'default' or 'official'
 190  * @return true on success, false otherwise
 191  */
 192 function tag_type_set($tagid, $type) {
 193     global $DB;
 194
 195     if ($tag = $DB->get_record('tag', array('id'=>$tagid), 'id')) {
 196         $tag->tagtype = $type;
 197         $tag->timemodified = time();
 198         return $DB->update_record('tag', $tag);
 199     }
 200     return false;
 201 }
 202
 203
 204 /**
 205  * Set the description of a tag
 206  *
 207  * @param int $tagid the id of the tag
 208  * @param string $description the description
 209  * @param int $descriptionformat the moodle text format of the description
 210  * @return true on success, false otherwise
 211  */
 212 function tag_description_set($tagid, $description, $descriptionformat) {
 213     global $DB;
 214
 215     if ($tag = $DB->get_record('tag', array('id'=>$tagid),'id')) {
 216         $tag->description = $description;
 217         $tag->descriptionformat = $descriptionformat;
 218         $tag->timemodified = time();
 219         return $DB->update_record('tag', $tag);
 220     }
 221     return false;
 222 }
 223
 224
 225
 226
 227
 228
 229 /// Functions for getting information about tags //////
 230
 231 /**
 232  * Simple function to just return a single tag object when you know the name or something
 233  *
 234  * @param string $field which field do we use to identify the tag: id, name or rawname
 235  * @param string $value the required value of the aforementioned field
 236  * @param string $returnfields which fields do we want returned?
 237  * @return tag object
 238  *
 239  **/
 240 function tag_get($field, $value, $returnfields='id, name, rawname') {
 241     global $DB;
 242
 243     if ($field == 'name') {
 244         $value = moodle_strtolower($value);   // To cope with input that might just be wrong case
 245     }
 246     return $DB->get_record('tag', array($field=>$value), $returnfields);
 247 }
 248
 249
 250 /**
 251  * Get the array of db record of tags associated to a record (instances).  Use
 252  * tag_get_tags_csv to get the same information in a comma-separated string.
 253  * This should really be called tag_get_tag_instances()
 254  *
 255  * @param string $record_type the record type for which we want to get the tags
 256  * @param int $record_id the record id for which we want to get the tags
 257  * @param string $type the tag type (either 'default' or 'official'). By default,
 258  *     all tags are returned.
 259  * @param int $userid optional only required for course tagging
 260  * @return array the array of tags
 261  */
 262 function tag_get_tags($record_type, $record_id, $type=null, $userid=0) {
 263     global $CFG, $DB;
 264
 265     $params = array();
 266
 267     if ($type) {
 268         $sql_type = "AND tg.tagtype = :type";
 269         $params['type'] = $type;
 270     } else {
 271         $sql_type = '';
 272     }
 273
 274    $u = null;
 275     if ($userid) {
 276         $u =  "AND ti.tiuserid = :userid ";
 277         $params['userid'] = $userid;
 278     }
 279
 280     $sql = "SELECT tg.id, tg.tagtype, tg.name, tg.rawname, tg.flag, ti.ordering
 281               FROM {tag_instance} ti
 282               JOIN {tag} tg ON tg.id = ti.tagid
 283               WHERE ti.itemtype = :recordtype AND ti.itemid = :recordid $u $sql_type
 284            ORDER BY ti.ordering ASC";
 285     $params['recordtype'] = $record_type;
 286     $params['recordid']   = $record_id;
 287
 288     // if the fields in this query are changed, you need to do the same changes in tag_get_correlated_tags
 289     return $DB->get_records_sql($sql, $params);
 290     // This version of the query, reversing the ON clause, "correctly" returns
 291     // a row with NULL values for instances that are still in the DB even though
 292     // the tag has been deleted.  This shouldn't happen, but if it did, using
 293     // this query could help "clean it up".  This causes bugs at this time.
 294     //$tags = $DB->get_records_sql("SELECT ti.tagid, tg.tagtype, tg.name, tg.rawname, tg.flag, ti.ordering ".
 295     //    "FROM {tag_instance} ti LEFT JOIN {tag} tg ON ti.tagid = tg.id ".
 296     //    "WHERE ti.itemtype = '{$record_type}' AND ti.itemid = '{$record_id}' {$type} ".
 297     //    "ORDER BY ti.ordering ASC");
 298 }
 299
 300 /**
 301  * Get the array of tags display names, indexed by id.
 302  *
 303  * @param string $record_type the record type for which we want to get the tags
 304  * @param int $record_id the record id for which we want to get the tags
 305  * @param string $type the tag type (either 'default' or 'official'). By default,
 306  *     all tags are returned.
 307  * @return array the array of tags (with the value returned by tag_display_name), indexed by id
 308  */
 309 function tag_get_tags_array($record_type, $record_id, $type=null) {
 310     $tags = array();
 311     foreach(tag_get_tags($record_type, $record_id, $type) as $tag) {
 312         $tags[$tag->id] = tag_display_name($tag);
 313     }
 314     return $tags;
 315 }
 316
 317 /**
 318  * Get a comma-separated string of tags associated to a record.  Use tag_get_tags
 319  * to get the same information in an array.
 320  *
 321  * @param string $record_type the record type for which we want to get the tags
 322  * @param int $record_id the record id for which we want to get the tags
 323  * @param int $html either TAG_RETURN_HTML or TAG_RETURN_TEXT, depending
 324  *     on the type of output desired
 325  * @param string $type either 'official' or 'default', if null, all tags are
 326  *     returned
 327  * @return string the comma-separated list of tags.
 328  */
 329 function tag_get_tags_csv($record_type, $record_id, $html=TAG_RETURN_HTML, $type=null) {
 330     global $CFG;
 331
 332     $tags_names = array();
 333     foreach(tag_get_tags($record_type, $record_id, $type) as $tag) {
 334         if ($html == TAG_RETURN_TEXT) {
 335             $tags_names[] = tag_display_name($tag, TAG_RETURN_TEXT);
 336         } else { // TAG_RETURN_HTML
 337             $tags_names[] = '<a href="'. $CFG->wwwroot .'/tag/index.php?tag='. rawurlencode($tag->name) .'">'. tag_display_name($tag) .'</a>';
 338         }
 339     }
 340     return implode(', ', $tags_names);
 341 }
 342
 343 /**
 344  * Get an array of tag ids associated to a record.
 345  *
 346  * @param string $record_type the record type for which we want to get the tags
 347  * @param int $record_id the record id for which we want to get the tags
 348  * @return array of tag ids, indexed and sorted by 'ordering'
 349  */
 350 function tag_get_tags_ids($record_type, $record_id) {
 351
 352     $tag_ids = array();
 353     foreach (tag_get_tags($record_type, $record_id) as $tag) {
 354         if ( array_key_exists($tag->ordering, $tag_ids) ) {
 355             // until we can add a unique constraint, in table tag_instance,
 356             // on (itemtype, itemid, ordering), this is needed to prevent a bug
 357             // TODO : modify database in 2.0
 358             $tag->ordering++;
 359         }
 360         $tag_ids[$tag->ordering] = $tag->id;
 361     }
 362     ksort($tag_ids);
 363     return $tag_ids;
 364 }
 365
 366 /**
 367  * Returns the database ID of a set of tags.
 368  *
 369  * @param mixed $tags one tag, or array of tags, to look for.
 370  * @param bool $return_value specify the type of the returned value. Either
 371  *     TAG_RETURN_OBJECT, or TAG_RETURN_ARRAY (default). If TAG_RETURN_ARRAY
 372  *     is specified, an array will be returned even if only one tag was
 373  *     passed in $tags.
 374  * @return mixed tag-indexed array of ids (or objects, if second parameter is
 375  *     TAG_RETURN_OBJECT), or only an int, if only one tag is given *and* the
 376  *     second parameter is null. No value for a key means the tag wasn't found.
 377  */
 378 function tag_get_id($tags, $return_value=null) {
 379     global $CFG, $DB;
 380
 381     static $tag_id_cache = array();
 382
 383     $return_an_int = false;
 384     if (!is_array($tags)) {
 385         if(is_null($return_value) || $return_value == TAG_RETURN_OBJECT) {
 386             $return_an_int = true;
 387         }
 388         $tags = array($tags);
 389     }
 390
 391     $result = array();
 392
 393     //TODO: test this and see if it helps performance without breaking anything
 394     //foreach($tags as $key => $tag) {
 395     //    $clean_tag = moodle_strtolower($tag);
 396     //    if ( array_key_exists($clean_tag), $tag_id_cache) ) {
 397     //        $result[$clean_tag] = $tag_id_cache[$clean_tag];
 398     //        $tags[$key] = ''; // prevent further processing for this one.
 399     //    }
 400     //}
 401
 402     $tags = array_values(tag_normalize($tags));
 403     foreach($tags as $key => $tag) {
 404         $tags[$key] = moodle_strtolower($tag);
 405         $result[moodle_strtolower($tag)] = null; // key must exists : no value for a key means the tag wasn't found.
 406     }
 407
 408     if (empty($tags)) {
 409         return array();
 410     }
 411
 412     list($tag_string, $params) = $DB->get_in_or_equal($tags);
 413
 414     $rs = $DB->get_recordset_sql("SELECT * FROM {tag} WHERE name $tag_string ORDER BY name", $params);
 415     foreach ($rs as $record) {
 416         if ($return_value == TAG_RETURN_OBJECT) {
 417             $result[$record->name] = $record;
 418         } else { // TAG_RETURN_ARRAY
 419             $result[$record->name] = $record->id;
 420         }
 421     }
 422     $rs->close();
 423
 424     if ($return_an_int) {
 425         return array_pop($result);
 426     }
 427
 428     return $result;
 429 }
 430
 431
 432 /**
 433  * Returns tags related to a tag
 434  *
 435  * Related tags of a tag come from two sources:
 436  *   - manually added related tags, which are tag_instance entries for that tag
 437  *   - correlated tags, which are a calculated
 438  *
 439  * @param string $tag_name_or_id is a single **normalized** tag name or the id
 440  *     of a tag
 441  * @param int $type the function will return either manually
 442  *     (TAG_RELATED_MANUAL) related tags or correlated (TAG_RELATED_CORRELATED)
 443  *     tags. Default is TAG_RELATED_ALL, which returns everything.
 444  * @param int $limitnum return a subset comprising this many records (optional,
 445  *     default is 10)
 446  * @return array an array of tag objects
 447  */
 448 function tag_get_related_tags($tagid, $type=TAG_RELATED_ALL, $limitnum=10) {
 449
 450     $related_tags = array();
 451
 452     if ( $type == TAG_RELATED_ALL || $type == TAG_RELATED_MANUAL) {
 453         //gets the manually added related tags
 454         $related_tags = tag_get_tags('tag', $tagid);
 455     }
 456
 457     if ( $type == TAG_RELATED_ALL || $type == TAG_RELATED_CORRELATED ) {
 458         //gets the correlated tags
 459         $automatic_related_tags = tag_get_correlated($tagid, $limitnum);
 460         if (is_array($automatic_related_tags)) {
 461             $related_tags = array_merge($related_tags, $automatic_related_tags);
 462         }
 463     }
 464
 465     return array_slice(object_array_unique($related_tags), 0 , $limitnum);
 466 }
 467
 468 /**
 469  * Get a comma-separated list of tags related to another tag.
 470  *
 471  * @param array $related_tags the array returned by tag_get_related_tags
 472  * @param int $html either TAG_RETURN_HTML (default) or TAG_RETURN_TEXT : return html links, or just text.
 473  * @return string comma-separated list
 474  */
 475 function tag_get_related_tags_csv($related_tags, $html=TAG_RETURN_HTML) {
 476     global $CFG;
 477
 478     $tags_names = array();
 479     foreach($related_tags as $tag) {
 480         if ( $html == TAG_RETURN_TEXT) {
 481             $tags_names[] = tag_display_name($tag, TAG_RETURN_TEXT);
 482         } else {
 483             // TAG_RETURN_HTML
 484             $tags_names[] = '<a href="'. $CFG->wwwroot .'/tag/index.php?tag='. rawurlencode($tag->name) .'">'. tag_display_name($tag) .'</a>';
 485         }
 486     }
 487
 488     return implode(', ', $tags_names);
 489 }
 490
 491 /**
 492  * Change the "value" of a tag, and update the associated 'name'.
 493  *
 494  * @param int $tagid the id of the tag to modify
 495  * @param string $newtag the new rawname
 496  * @return bool true on success, false otherwise
 497  */
 498 function tag_rename($tagid, $newrawname) {
 499     global $DB;
 500
 501     if (! $newrawname_clean = array_shift(tag_normalize($newrawname, TAG_CASE_ORIGINAL)) ) {
 502         return false;
 503     }
 504
 505     if (! $newname_clean = moodle_strtolower($newrawname_clean)) {
 506         return false;
 507     }
 508
 509     // Prevent the rename if a tag with that name already exists
 510     if ($existing = tag_get('name', $newname_clean, 'id, name, rawname')) {
 511         if ($existing->id != $tagid) {  // Another tag already exists with this name
 512             return false;
 513         }
 514     }
 515
 516     if ($tag = tag_get('id', $tagid, 'id, name, rawname')) {
 517         $tag->rawname      = $newrawname_clean;
 518         $tag->name         = $newname_clean;
 519         $tag->timemodified = time();
 520         return $DB->update_record('tag', $tag);
 521     }
 522     return false;
 523 }
 524
 525
 526 /**
 527  * Delete one or more tag, and all their instances if there are any left.
 528  *
 529  * @param mixed $tagids one tagid (int), or one array of tagids to delete
 530  * @return bool true on success, false otherwise
 531  */
 532 function tag_delete($tagids) {
 533     global $DB;
 534
 535     if (!is_array($tagids)) {
 536         $tagids = array($tagids);
 537     }
 538
 539     $success = true;
 540     $context = get_context_instance(CONTEXT_SYSTEM);
 541     foreach ($tagids as $tagid) {
 542         if (is_null($tagid)) { // can happen if tag doesn't exists
 543             continue;
 544         }
 545         // only delete the main entry if there were no problems deleting all the
 546         // instances - that (and the fact we won't often delete lots of tags)
 547         // is the reason for not using $DB->delete_records_select()
 548         if ($DB->delete_records('tag_instance', array('tagid'=>$tagid)) && $DB->delete_records('tag_correlation', array('tagid' => $tagid))) {
 549             $success &= (bool) $DB->delete_records('tag', array('id'=>$tagid));
 550             // Delete all files associated with this tag
 551             $fs = get_file_storage();
 552             $files = $fs->get_area_files($context->id, 'tag', 'description', $tagid);
 553             foreach ($files as $file) {
 554                 $file->delete();
 555             }
 556         }
 557     }
 558
 559     return $success;
 560 }
 561
 562 /**
 563  * Delete one instance of a tag.  If the last instance was deleted, it will
 564  * also delete the tag, unless its type is 'official'.
 565  *
 566  * @param string $record_type the type of the record for which to remove the instance
 567  * @param int $record_id the id of the record for which to remove the instance
 568  * @param int $tagid the tagid that needs to be removed
 569  * @return bool true on success, false otherwise
 570  */
 571 function tag_delete_instance($record_type, $record_id, $tagid) {
 572     global $CFG, $DB;
 573
 574     if ($DB->delete_records('tag_instance', array('tagid'=>$tagid, 'itemtype'=>$record_type, 'itemid'=>$record_id))) {
 575         if (!$DB->record_exists_sql("SELECT * ".
 576                                       "FROM {tag} tg ".
 577                                      "WHERE tg.id = ? AND ( tg.tagtype = 'official' OR ".
 578                                         "EXISTS (SELECT 1
 579                                                    FROM {tag_instance} ti
 580                                                   WHERE ti.tagid = ?) )",
 581                                      array($tagid, $tagid))) {
 582             return tag_delete($tagid);
 583         }
 584     } else {
 585         return false;
 586     }
 587
 588     return true;
 589 }
 590
 591
 592 /**
 593  * Function that returns the name that should be displayed for a specific tag
 594  *
 595  * @param object $tag_object a line out of tag table, as returned by the adobd functions
 596  * @param int $html TAG_RETURN_HTML (default) will return htmlspecialchars encoded string, TAG_RETURN_TEXT will not encode.
 597  * @return string
 598  */
 599 function tag_display_name($tagobject, $html=TAG_RETURN_HTML) {
 600
 601     global $CFG;
 602
 603     if (!isset($tagobject->name)) {
 604         return '';
 605     }
 606
 607     if (empty($CFG->keeptagnamecase)) {
 608         //this is the normalized tag name
 609         $textlib = textlib_get_instance();
 610         $tagname = $textlib->strtotitle($tagobject->name);
 611     } else {
 612         //original casing of the tag name
 613         $tagname = $tagobject->rawname;
 614     }
 615
 616     // clean up a bit just in case the rules change again
 617     $tagname = clean_param($tagname, PARAM_TAG);
 618
 619     if ($html == TAG_RETURN_TEXT) {
 620         return $tagname;
 621     } else { // TAG_RETURN_HTML
 622         return htmlspecialchars($tagname);
 623     }
 624 }
 625
 626 /**
 627  * Find all records tagged with a tag of a given type ('post', 'user', etc.)
 628  *
 629  * @param string $tag tag to look for
 630  * @param string $type type to restrict search to.  If null, every matching
 631  *     record will be returned
 632  * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
 633  * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
 634  * @return array of matching objects, indexed by record id, from the table containing the type requested
 635  */
 636 function tag_find_records($tag, $type, $limitfrom='', $limitnum='') {
 637     global $CFG, $DB;
 638
 639     if (!$tag || !$type) {
 640         return array();
 641     }
 642
 643     $tagid = tag_get_id($tag);
 644
 645     $query = "SELECT it.*
 646                 FROM {".$type."} it INNER JOIN {tag_instance} tt ON it.id = tt.itemid
 647                WHERE tt.itemtype = ? AND tt.tagid = ?";
 648     $params = array($type, $tagid);
 649
 650     return $DB->get_records_sql($query, $params, $limitfrom, $limitnum);
 651 }
 652
 653
 654
 655
 656 ///////////////////////////////////////////////////////
 657 /////////////////// PRIVATE TAG API ///////////////////
 658
 659 /**
 660  * Adds one or more tag in the database.  This function should not be called
 661  * directly : you should use tag_set.
 662  *
 663  * @param mixed $tags one tag, or an array of tags, to be created
 664  * @param string $type type of tag to be created ("default" is the default
 665  *     value and "official" is the only other supported value at this time). An
 666  *     official tag is kept even if there are no records tagged with it.
 667  * @return an array of tags ids, indexed by their lowercase normalized names.
 668  *     Any boolean false in the array indicates an error while adding the tag.
 669  */
 670 function tag_add($tags, $type="default") {
 671     global $USER, $DB;
 672
 673     if (!is_array($tags)) {
 674         $tags = array($tags);
 675     }
 676
 677     $tag_object = new StdClass;
 678     $tag_object->tagtype      = $type;
 679     $tag_object->userid       = $USER->id;
 680     $tag_object->timemodified = time();
 681
 682     $clean_tags = tag_normalize($tags, TAG_CASE_ORIGINAL);
 683
 684     $tags_ids = array();
 685     foreach($clean_tags as $tag) {
 686         $tag = trim($tag);
 687         if (!$tag) {
 688             $tags_ids[$tag] = false;
 689         } else {
 690             // note that the difference between rawname and name is only
 691             // capitalization : the rawname is NOT the same at the rawtag.
 692             $tag_object->rawname = $tag;
 693             $tag_name_lc         = moodle_strtolower($tag);
 694             $tag_object->name    = $tag_name_lc;
 695             //var_dump($tag_object);
 696             $tags_ids[$tag_name_lc] = $DB->insert_record('tag', $tag_object);
 697         }
 698     }
 699
 700     return $tags_ids;
 701 }
 702
 703 /**
 704  * Assigns a tag to a record: if the record already exists, the time and
 705  * ordering will be updated.
 706  *
 707  * @param string $record_type the type of the record that will be tagged
 708  * @param int $record_id the id of the record that will be tagged
 709  * @param string $tagid the tag id to set on the record.
 710  * @param int $ordering the order of the instance for this record
 711  * @param int $userid optional only required for course tagging
 712  * @return bool true on success, false otherwise
 713  */
 714 function tag_assign($record_type, $record_id, $tagid, $ordering, $userid = 0) {
 715     global $DB;
 716
 717     if ( $tag_instance_object = $DB->get_record('tag_instance', array('tagid'=>$tagid, 'itemtype'=>$record_type, 'itemid'=>$record_id, 'tiuserid'=>$userid), 'id')) {
 718         $tag_instance_object->ordering     = $ordering;
 719         $tag_instance_object->timemodified = time();
 720         return $DB->update_record('tag_instance', $tag_instance_object);
 721     } else {
 722         $tag_instance_object = new StdClass;
 723         $tag_instance_object->tagid        = $tagid;
 724         $tag_instance_object->itemid       = $record_id;
 725         $tag_instance_object->itemtype     = $record_type;
 726         $tag_instance_object->ordering     = $ordering;
 727         $tag_instance_object->timemodified = time();
 728         $tag_instance_object->tiuserid     = $userid;
 729         return $DB->insert_record('tag_instance', $tag_instance_object);
 730     }
 731 }
 732
 733 /**
 734  * Function that returns tags that start with some text, for use by the autocomplete feature
 735  *
 736  * @param string $text string that the tag names will be matched against
 737  * @return mixed an array of objects, or false if no records were found or an error occured.
 738  */
 739 function tag_autocomplete($text) {
 740     global $DB;
 741     return $DB->get_records_sql("SELECT tg.id, tg.name, tg.rawname
 742                                    FROM {tag} tg
 743                                   WHERE tg.name LIKE ?", array(moodle_strtolower($text)."%"));
 744 }
 745
 746 /**
 747  * Clean up the tag tables, making sure all tagged object still exists.
 748  *
 749  * This should normally not be necessary, but in case related tags are not deleted
 750  * when the tagged record is removed, this should be done once in a while, perhaps on
 751  * an occasional cron run.  On a site with lots of tags, this could become an expensive
 752  * function to call: don't run at peak time.
 753  */
 754 function tag_cleanup() {
 755     global $DB;
 756
 757     $instances = $DB->get_recordset('tag_instance');
 758
 759     // cleanup tag instances
 760     foreach ($instances as $instance) {
 761         $delete = false;
 762
 763         if (!$DB->record_exists('tag', array('id'=>$instance->tagid))) {
 764             // if the tag has been removed, instance should be deleted.
 765             $delete = true;
 766         } else {
 767             switch ($instance->itemtype) {
 768                 case 'user': // users are marked as deleted, but not actually deleted
 769                     if ($DB->record_exists('user', array('id'=>$instance->itemid, 'deleted'=>1))) {
 770                         $delete = true;
 771                     }
 772                     break;
 773                 default: // anything else, if the instance is not there, delete.
 774                     if (!$DB->record_exists($instance->itemtype, array('id'=>$instance->itemid))) {
 775                         $delete = true;
 776                     }
 777                     break;
 778             }
 779         }
 780         if ($delete) {
 781             tag_delete_instance($instance->itemtype, $instance->itemid, $instance->tagid);
 782             //debugging('deleting tag_instance #'. $instance->id .', linked to tag id #'. $instance->tagid, DEBUG_DEVELOPER);
 783         }
 784     }
 785     $instances->close();
 786
 787     // TODO: this will only clean tags of type 'default'.  This is good as
 788     // it won't delete 'official' tags, but the day we get more than two
 789     // types, we need to fix this.
 790     $unused_tags = $DB->get_recordset_sql("SELECT tg.id
 791                                              FROM {tag} tg
 792                                             WHERE tg.tagtype = 'default'
 793                                                   AND NOT EXISTS (
 794                                                       SELECT 'x'
 795                                                         FROM {tag_instance} ti
 796                                                        WHERE ti.tagid = tg.id
 797                                                   )");
 798
 799     // cleanup tags
 800     foreach ($unused_tags as $unused_tag) {
 801         tag_delete($unused_tag->id);
 802         //debugging('deleting unused tag #'. $unused_tag->id,  DEBUG_DEVELOPER);
 803     }
 804     $unused_tags->close();
 805 }
 806
 807 /**
 808  * Calculates and stores the correlated tags of all tags.
 809  * The correlations are stored in the 'tag_correlation' table.
 810  *
 811  * Two tags are correlated if they appear together a lot.
 812  * Ex.: Users tagged with "computers" will probably also be tagged with "algorithms".
 813  *
 814  * The rationale for the 'tag_correlation' table is performance.
 815  * It works as a cache for a potentially heavy load query done at the 'tag_instance' table.
 816  * So, the 'tag_correlation' table stores redundant information derived from the 'tag_instance' table.
 817  *
 818  * @global moodle_database $DB
 819  * @param int $mincorrelation Only tags with more than $mincorrelation correlations will
 820  *                             be identified.
 821  * @return void
 822  */
 823 function tag_compute_correlations($mincorrelation = 2) {
 824     global $DB;
 825
 826     // This mighty one line query fetches a row from the database for every
 827     // individual tag correlation. We then need to process the rows collecting
 828     // the correlations for each tag id.
 829     // The fields used by this query are as follows:
 830     //   tagid         : This is the tag id, there should be at least $mincorrelation
 831     //                   rows for each tag id.
 832     //   correlation   : This is the tag id that correlates to the above tagid field.
 833     //   correlationid : This is the id of the row in the tag_correlation table that
 834     //                   relates to the tagid field and will be NULL if there are no
 835     //                   existing correlations
 836     $sql = 'SELECT pairs.tagid, pairs.correlation, pairs.ocurrences, co.id AS correlationid
 837               FROM (
 838                        SELECT ta.tagid, tb.tagid AS correlation, COUNT(*) AS ocurrences
 839                          FROM {tag_instance} ta
 840                          JOIN {tag_instance} tb ON (ta.itemtype = tb.itemtype AND ta.itemid = tb.itemid AND ta.tagid <> tb.tagid)
 841                      GROUP BY ta.tagid, tb.tagid
 842                        HAVING COUNT(*) > :mincorrelation
 843                    ) pairs
 844          LEFT JOIN {tag_correlation} co ON co.tagid = pairs.tagid
 845           ORDER BY pairs.tagid ASC, pairs.ocurrences DESC, pairs.correlation ASC';
 846     $rs = $DB->get_recordset_sql($sql, array('mincorrelation' => $mincorrelation));
 847
 848     // Set up an empty tag correlation object
 849     $tagcorrelation = new stdClass;
 850     $tagcorrelation->id = null;
 851     $tagcorrelation->tagid = null;
 852     $tagcorrelation->correlatedtags = array();
 853
 854     // We store each correlation id in this array so we can remove any correlations
 855     // that no longer exist.
 856     $correlations = array();
 857
 858     // Iterate each row of the result set and build them into tag correlations.
 859     // We add all of a tag's correlations to $tagcorrelation->correlatedtags[]
 860     // then save the $tagcorrelation object
 861     foreach ($rs as $row) {
 862         if ($row->tagid != $tagcorrelation->tagid) {
 863             // The tag id has changed so we have all of the correlations for this tag
 864             $tagcorrelationid = tag_process_computed_correlation($tagcorrelation);
 865             if ($tagcorrelationid) {
 866                 $correlations[] = $tagcorrelationid;
 867             }
 868             // Now we reset the tag correlation object so we can reuse it and set it
 869             // up for the current record.
 870             $tagcorrelation = new stdClass;
 871             $tagcorrelation->id = $row->correlationid;
 872             $tagcorrelation->tagid = $row->tagid;
 873             $tagcorrelation->correlatedtags = array();
 874         }
 875         //Save the correlation on the tag correlation object
 876         $tagcorrelation->correlatedtags[] = $row->correlation;
 877     }
 878     // Update the current correlation after the last record.
 879     $tagcorrelationid = tag_process_computed_correlation($tagcorrelation);
 880     if ($tagcorrelationid) {
 881         $correlations[] = $tagcorrelationid;
 882     }
 883
 884
 885     // Close the recordset
 886     $rs->close();
 887
 888     // Remove any correlations that weren't just identified
 889     if (empty($correlations)) {
 890         //there are no tag correlations
 891         $DB->delete_records('tag_correlation');
 892     } else {
 893         list($sql, $params) = $DB->get_in_or_equal($correlations, SQL_PARAMS_NAMED, 'param0000', false);
 894         $DB->delete_records_select('tag_correlation', 'id '.$sql, $params);
 895     }
 896 }
 897
 898 /**
 899  * This function processes a tag correlation and makes changes in the database
 900  * as required.
 901  *
 902  * The tag correlation object needs have both a tagid property and a correlatedtags
 903  * property that is an array.
 904  *
 905  * @param stdClass $tagcorrelation
 906  * @return int The id of the tag correlation that was just processed.
 907  */
 908 function tag_process_computed_correlation(stdClass $tagcorrelation) {
 909     global $DB;
 910
 911     // You must provide a tagid and correlatedtags must be set and be an array
 912     if (empty($tagcorrelation->tagid) || !isset($tagcorrelation->correlatedtags) || !is_array($tagcorrelation->correlatedtags)) {
 913         return false;
 914     }
 915
 916     $tagcorrelation->correlatedtags = join(',', $tagcorrelation->correlatedtags);
 917     if (!empty($tagcorrelation->id)) {
 918         // The tag correlation already exists so update it
 919         $DB->update_record('tag_correlation', $tagcorrelation);
 920     } else {
 921         // This is a new correlation to insert
 922         $tagcorrelation->id = $DB->insert_record('tag_correlation', $tagcorrelation);
 923     }
 924     return $tagcorrelation->id;
 925 }
 926
 927 /**
 928  * Tasks that should be performed at cron time
 929  */
 930 function tag_cron() {
 931     tag_compute_correlations();
 932     tag_cleanup();
 933 }
 934
 935 /**
 936  * Search for tags with names that match some text
 937  *
 938  * @param string $text escaped string that the tag names will be matched against
 939  * @param boolean $ordered If true, tags are ordered by their popularity. If false, no ordering.
 940  * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
 941  * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
 942  * @return mixed an array of objects, or false if no records were found or an error occured.
 943  */
 944 function tag_find_tags($text, $ordered=true, $limitfrom='', $limitnum='') {
 945     global $DB;
 946
 947     $text = array_shift(tag_normalize($text, TAG_CASE_LOWER));
 948
 949     if ($ordered) {
 950         $query = "SELECT tg.id, tg.name, tg.rawname, COUNT(ti.id) AS count
 951                     FROM {tag} tg LEFT JOIN {tag_instance} ti ON tg.id = ti.tagid
 952                    WHERE tg.name LIKE ?
 953                 GROUP BY tg.id, tg.name, tg.rawname
 954                 ORDER BY count DESC";
 955     } else {
 956         $query = "SELECT tg.id, tg.name, tg.rawname
 957                     FROM {tag} tg
 958                    WHERE tg.name LIKE ?";
 959     }
 960     $params = array("%{$text}%");
 961     return $DB->get_records_sql($query, $params, $limitfrom , $limitnum);
 962 }
 963
 964 /**
 965  * Get the name of a tag
 966  *
 967  * @param mixed $tagids the id of the tag, or an array of ids
 968  * @return mixed string name of one tag, or id-indexed array of strings
 969  */
 970 function tag_get_name($tagids) {
 971     global $DB;
 972
 973     if (!is_array($tagids)) {
 974         if ($tag = $DB->get_record('tag', array('id'=>$tagids))) {
 975             return $tag->name;
 976         }
 977         return false;
 978     }
 979
 980     $tag_names = array();
 981     foreach($DB->get_records_list('tag', 'id', $tagids) as $tag) {
 982         $tag_names[$tag->id] = $tag->name;
 983     }
 984
 985     return $tag_names;
 986 }
 987
 988 /**
 989  * Returns the correlated tags of a tag, retrieved from the tag_correlation
 990  * table.  Make sure cron runs, otherwise the table will be empty and this
 991  * function won't return anything.
 992  *
 993  * @param int $tag_id is a single tag id
 994  * @return array an array of tag objects, empty if no correlated tags are found
 995  */
 996 function tag_get_correlated($tag_id, $limitnum=null) {
 997     global $DB;
 998
 999     $tag_correlation = $DB->get_record('tag_correlation', array('tagid'=>$tag_id));
1000
1001     if (!$tag_correlation || empty($tag_correlation->correlatedtags)) {
1002         return array();
1003     }
1004
1005     // this is (and has to) return the same fields as the query in tag_get_tags
1006     $sql = "SELECT DISTINCT tg.id, tg.tagtype, tg.name, tg.rawname, tg.flag, ti.ordering
1007               FROM {tag} tg
1008         INNER JOIN {tag_instance} ti ON tg.id = ti.tagid
1009              WHERE tg.id IN ({$tag_correlation->correlatedtags})";
1010     $result = $DB->get_records_sql($sql);
1011     if (!$result) {
1012         return array();
1013     }
1014
1015     return $result;
1016 }
1017
1018 /**
1019  * Function that normalizes a list of tag names.
1020  *
1021  * @param mixed $tags array of tags, or a single tag.
1022  * @param int $case case to use for returned value (default: lower case).
1023  *     Either TAG_CASE_LOWER (default) or TAG_CASE_ORIGINAL
1024  * @return array of lowercased normalized tags, indexed by the normalized tag,
1025  *     in the same order as the original array. (Eg: 'Banana' => 'banana').
1026  */
1027 function tag_normalize($rawtags, $case = TAG_CASE_LOWER) {
1028
1029     // cache normalized tags, to prevent costly repeated calls to clean_param
1030     static $cleaned_tags_lc = array(); // lower case - use for comparison
1031     static $cleaned_tags_mc = array(); // mixed case - use for saving to database
1032
1033     if ( !is_array($rawtags) ) {
1034         $rawtags = array($rawtags);
1035     }
1036
1037     $result = array();
1038     foreach($rawtags as $rawtag) {
1039         $rawtag = trim($rawtag);
1040         if (!$rawtag) {
1041             continue;
1042         }
1043         if ( !array_key_exists($rawtag, $cleaned_tags_lc) ) {
1044             $cleaned_tags_lc[$rawtag] = moodle_strtolower( clean_param($rawtag, PARAM_TAG) );
1045             $cleaned_tags_mc[$rawtag] = clean_param($rawtag, PARAM_TAG);
1046         }
1047         if ( $case == TAG_CASE_LOWER ) {
1048             $result[$rawtag] = $cleaned_tags_lc[$rawtag];
1049         } else { // TAG_CASE_ORIGINAL
1050             $result[$rawtag] = $cleaned_tags_mc[$rawtag];
1051         }
1052     }
1053
1054     return $result;
1055 }
1056
1057 /**
1058  * Count how many records are tagged with a specific tag,
1059  *
1060  * @param string $record record to look for ('post', 'user', etc.)
1061  * @param int $tag is a single tag id
1062  * @return int number of mathing tags.
1063  */
1064 function tag_record_count($record_type, $tagid) {
1065     global $DB;
1066     return $DB->count_records('tag_instance', array('itemtype'=>$record_type, 'tagid'=>$tagid));
1067 }
1068
1069 /**
1070  * Determine if a record is tagged with a specific tag
1071  *
1072  * @param string $record_type the record type to look for
1073  * @param int $record_id the record id to look for
1074  * @param string $tag a tag name
1075  * @return bool true if it is tagged, false otherwise
1076  */
1077 function tag_record_tagged_with($record_type, $record_id, $tag) {
1078     global $DB;
1079     if ($tagid = tag_get_id($tag)) {
1080         return $DB->count_records('tag_instance', array('itemtype'=>$record_type, 'itemid'=>$record_id, 'tagid'=>$tagid));
1081     } else {
1082         return 0; // tag doesn't exist
1083     }
1084 }
1085
1086 /**
1087  * Flag a tag as inapropriate
1088  *
1089  * @param mixed $tagids one (int) tagid, or an array of tagids
1090  * @return void
1091  */
1092 function tag_set_flag($tagids) {
1093     global $DB;
1094
1095     $tagids = (array)$tagids;
1096     foreach ($tagids as $tagid) {
1097         $tag = $DB->get_record('tag', array('id'=>$tagid), 'id, flag');
1098         $tag->flag++;
1099         $tag->timemodified = time();
1100         $DB->update_record('tag', $tag);
1101     }
1102 }
1103
1104 /**
1105  * Remove the inapropriate flag on a tag
1106  *
1107  * @param mixed $tagids one (int) tagid, or an array of tagids
1108  * @return bool true if function succeeds, false otherwise
1109  */
1110 function tag_unset_flag($tagids) {
1111     global $DB;
1112
1113     if ( is_array($tagids) ) {
1114         $tagids = implode(',', $tagids);
1115     }
1116     $timemodified = time();
1117     return $DB->execute("UPDATE {tag} SET flag = 0, timemodified = ? WHERE id IN ($tagids)", array($timemodified));
1118 }
1119
1120
1121 /**
1122  * Return a list of page types
1123  * @param string $pagetype current page type
1124  * @param stdClass $parentcontext Block's parent context
1125  * @param stdClass $currentcontext Current context of block
1126  */
1127 function tag_page_type_list($pagetype, $parentcontext, $currentcontext) {
1128     return array(
1129         'tag-*'=>get_string('page-tag-x', 'tag'),
1130         'tag-index'=>get_string('page-tag-index', 'tag'),
1131         'tag-search'=>get_string('page-tag-search', 'tag'),
1132         'tag-manage'=>get_string('page-tag-manage', 'tag')
1133     );
1134 }