3eef874146be765e522354743e6a701aba5a5e7d
[moodle.git] / tag / lib.php
1 <?php
3 /**
4  * Moodle tag library
5  *
6  * Tag strings : you can use any character in tags, except the comma (which is
7  * the separator) and the '\' (backslash).  Note that many spaces (or other
8  * blank characters) will get "compressed" into one. A tag string is always a
9  * rawurlencode'd string. This is the same behavior as http://del.icio.us.
10  *
11  * A "record" is a php array (note that an object will work too) that contains
12  * the following variables :
13  *  - type: the table containing the record that we are tagging (eg: for a
14  *    blog, this is table 'post', and for a user it is 'user')
15  *  - id: the id of the record
16  *
17  * TODO: turn this into a full-fledged categorization system. This could start
18  * by modifying (removing, probably) the 'tag type' to use another table
19  * describing the relationship between tags (parents, sibling, etc.), which
20  * could then be merged with the 'course categorization' system...
21  *
22  * BASIC INSTRUCTIONS :
23  *  - to "tag a blog post" (for example):
24  *        tag_set('post', $blog_post->id, $array_of_tags);
25  *
26  *  - to "remove all the tags on a blog post":
27  *        tag_set('post', $blog_post->id, array());
28  *
29  * Tag set will create tags that need to be created.
30  *
31  * @licence http://www.gnu.org/copyleft/gpl.html GNU Public License
32  * @package moodlecore
33  * @subpackage tag
34  * @see http://www.php.net/manual/en/function.urlencode.php
35  */
37 define('TAG_RETURN_ARRAY', 0);
38 define('TAG_RETURN_OBJECT', 1);
39 define('TAG_RETURN_TEXT', 2);
40 define('TAG_RETURN_HTML', 3);
42 define('TAG_CASE_LOWER', 0);
43 define('TAG_CASE_ORIGINAL', 1);
45 define('TAG_RELATED_ALL', 0);
46 define('TAG_RELATED_MANUAL', 1);
47 define('TAG_RELATED_CORRELATED', 2);
49 ///////////////////////////////////////////////////////
50 /////////////////// PUBLIC TAG API ////////////////////
52 /// Functions for settings tags  //////////////////////
54 /**
55  * Set the tags assigned to a record.  This overwrites the current tags.
56  *
57  * This function is meant to be fed the string coming up from the user
58  * interface, which contains all tags assigned to a record.
59  *
60  * @param string $record_type the type of record to tag ('post' for blogs,
61  *     'user' for users, 'tag' for tags, etc.
62  * @param int $record_id the id of the record to tag
63  * @param array $tags the array of tags to set on the record. If
64  *     given an empty array, all tags will be removed.
65  * @return void
66  */
67 function tag_set($record_type, $record_id, $tags) {
69     static $in_recursion_semaphore = false; // this is to prevent loops when tagging a tag
70     if ( $record_type == 'tag' && !$in_recursion_semaphore) {
71         $current_tagged_tag_name = tag_get_name($record_id);
72     }
74     $tags_ids = tag_get_id($tags, TAG_RETURN_ARRAY); // force an array, even if we only have one tag.
75     $cleaned_tags = tag_normalize($tags);
76     //echo 'tags-in-tag_set'; var_dump($tags); var_dump($tags_ids); var_dump($cleaned_tags);
78     $current_ids = tag_get_tags_ids($record_type, $record_id);
79     //var_dump($current_ids);
81     // for data coherence reasons, it's better to remove deleted tags
82     // before adding new data: ordering could be duplicated.
83     foreach($current_ids as $current_id) {
84         if (!in_array($current_id, $tags_ids)) {
85             tag_delete_instance($record_type, $record_id, $current_id);
86             if ( $record_type == 'tag' && !$in_recursion_semaphore) {
87                 // if we are removing a tag-on-a-tag (manually related tag),
88                 // we need to remove the opposite relationship as well.
89                 tag_delete_instance('tag', $current_id, $record_id);
90             }
91         }
92     }
94     if (empty($tags)) {
95         return true;
96     }
98     foreach($tags as $ordering => $tag) {
99         $tag = trim($tag);
100         if (!$tag) {
101             continue;
102         }
104         $clean_tag = $cleaned_tags[$tag];
105         $tag_current_id = $tags_ids[$clean_tag];
107         if ( is_null($tag_current_id) ) {
108             // create new tags
109             //echo "call to add tag $tag\n";
110             $new_tag = tag_add($tag);
111             $tag_current_id = $new_tag[$clean_tag];
112         }
114         tag_assign($record_type, $record_id, $tag_current_id, $ordering);
116         // if we are tagging a tag (adding a manually-assigned related tag), we
117         // need to create the opposite relationship as well.
118         if ( $record_type == 'tag' && !$in_recursion_semaphore) {
119             $in_recursion_semaphore = true;
120             tag_set_add('tag', $tag_current_id, $current_tagged_tag_name);
121             $in_recursion_semaphore = false;
122         }
123     }
126 /**
127  * Adds a tag to a record, without overwriting the current tags.
128  *
129  * @param string $record_type the type of record to tag ('post' for blogs,
130  *     'user' for users, etc.
131  * @param int $record_id the id of the record to tag
132  * @param string $tag the tag to add
133  * @return void
134  */
135 function tag_set_add($record_type, $record_id, $tag) {
137     $new_tags = array();
138     foreach( tag_get_tags($record_type, $record_id) as $current_tag ) {
139         $new_tags[] = $current_tag->rawname;
140     }
141     $new_tags[] = $tag;
143     return tag_set($record_type, $record_id, $new_tags);
146 /**
147  * Removes a tag from a record, without overwriting other current tags.
148  *
149  * @param string $record_type the type of record to tag ('post' for blogs,
150  *     'user' for users, etc.
151  * @param int $record_id the id of the record to tag
152  * @param string $tag the tag to delete
153  * @return void
154  */
155 function tag_set_delete($record_type, $record_id, $tag) {
157     $new_tags = array();
158     foreach( tag_get_tags($record_type, $record_id) as $current_tag ) {
159         if ($current_tag->name != $tag) {  // Keep all tags but the one specified
160             $new_tags[] = $current_tag->name;
161         }
162     }
164     return tag_set($record_type, $record_id, $new_tags);
167 /**
168  * Set the type of a tag.  At this time (version 1.9) the possible values
169  * are 'default' or 'official'.  Official tags will be displayed separately "at
170  * tagging time" (while selecting the tags to apply to a record).
171  *
172  * @param string $tagid tagid to modify
173  * @param string $type either 'default' or 'official'
174  * @return true on success, false otherwise
175  */
176 function tag_type_set($tagid, $type) {
177     global $DB;
179     if ($tag = $DB->get_record('tag', array('id'=>$tagid), 'id')) {
180         $tag->tagtype = $type;
181         $tag->timemodified = time();
182         return $DB->update_record('tag', $tag);
183     }
184     return false;
188 /**
189  * Set the description of a tag
190  *
191  * @param int $tagid the id of the tag
192  * @param string $description the description
193  * @param int $descriptionformat the moodle text format of the description
194  * @return true on success, false otherwise
195  */
196 function tag_description_set($tagid, $description, $descriptionformat) {
197     global $DB;
199     if ($tag = $DB->get_record('tag', array('id'=>$tagid),'id')) {
200         $tag->description = $description;
201         $tag->descriptionformat = $descriptionformat;
202         $tag->timemodified = time();
203         return $DB->update_record('tag', $tag);
204     }
205     return false;
213 /// Functions for getting information about tags //////
215 /**
216  * Simple function to just return a single tag object when you know the name or something
217  *
218  * @param string $field which field do we use to identify the tag: id, name or rawname
219  * @param string $value the required value of the aforementioned field
220  * @param string $returnfields which fields do we want returned?
221  * @return tag object
222  *
223  **/
224 function tag_get($field, $value, $returnfields='id, name, rawname') {
225     global $DB;
227     if ($field == 'name') {
228         $value = moodle_strtolower($value);   // To cope with input that might just be wrong case
229     }
230     return $DB->get_record('tag', array($field=>$value), $returnfields);
234 /**
235  * Get the array of db record of tags associated to a record (instances).  Use
236  * tag_get_tags_csv to get the same information in a comma-separated string.
237  *
238  * @param string $record_type the record type for which we want to get the tags
239  * @param int $record_id the record id for which we want to get the tags
240  * @param string $type the tag type (either 'default' or 'official'). By default,
241  *     all tags are returned.
242  * @param int $userid optional only required for course tagging
243  * @return array the array of tags
244  */
245 function tag_get_tags($record_type, $record_id, $type=null, $userid=0) {
246     global $CFG, $DB;
248     $params = array();
250     if ($type) {
251         $sql_type = "AND tg.tagtype = :type";
252         $params['type'] = $type;
253     } else {
254         $sql_type = '';
255     }
257    $u = null;
258     if ($userid) {
259         $u =  "AND ti.tiuserid = :userid ";
260         $params['userid'] = $userid;
261     }
263     $sql = "SELECT tg.id, tg.tagtype, tg.name, tg.rawname, tg.flag, ti.ordering
264               FROM {tag_instance} ti JOIN {tag} tg ON tg.id = ti.tagid
265               WHERE ti.itemtype = :recordtype AND ti.itemid = :recordid $u $sql_type
266            ORDER BY ti.ordering ASC";
267     $params['recordtype'] = $record_type;
268     $params['recordid']   = $record_id;
270     // if the fields in this query are changed, you need to do the same changes in tag_get_correlated_tags
271     return $DB->get_records_sql($sql, $params);
272     // This version of the query, reversing the ON clause, "correctly" returns
273     // a row with NULL values for instances that are still in the DB even though
274     // the tag has been deleted.  This shouldn't happen, but if it did, using
275     // this query could help "clean it up".  This causes bugs at this time.
276     //$tags = $DB->get_records_sql("SELECT ti.tagid, tg.tagtype, tg.name, tg.rawname, tg.flag, ti.ordering ".
277     //    "FROM {tag_instance} ti LEFT JOIN {tag} tg ON ti.tagid = tg.id ".
278     //    "WHERE ti.itemtype = '{$record_type}' AND ti.itemid = '{$record_id}' {$type} ".
279     //    "ORDER BY ti.ordering ASC");
282 /**
283  * Get the array of tags display names, indexed by id.
284  *
285  * @param string $record_type the record type for which we want to get the tags
286  * @param int $record_id the record id for which we want to get the tags
287  * @param string $type the tag type (either 'default' or 'official'). By default,
288  *     all tags are returned.
289  * @return array the array of tags (with the value returned by tag_display_name), indexed by id
290  */
291 function tag_get_tags_array($record_type, $record_id, $type=null) {
292     $tags = array();
293     foreach(tag_get_tags($record_type, $record_id, $type) as $tag) {
294         $tags[$tag->id] = tag_display_name($tag);
295     }
296     return $tags;
299 /**
300  * Get a comma-separated string of tags associated to a record.  Use tag_get_tags
301  * to get the same information in an array.
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 int $html either TAG_RETURN_HTML or TAG_RETURN_TEXT, depending
306  *     on the type of output desired
307  * @param string $type either 'official' or 'default', if null, all tags are
308  *     returned
309  * @return string the comma-separated list of tags.
310  */
311 function tag_get_tags_csv($record_type, $record_id, $html=TAG_RETURN_HTML, $type=null) {
312     global $CFG;
314     $tags_names = array();
315     foreach(tag_get_tags($record_type, $record_id, $type) as $tag) {
316         if ($html == TAG_RETURN_TEXT) {
317             $tags_names[] = tag_display_name($tag, TAG_RETURN_TEXT);
318         } else { // TAG_RETURN_HTML
319             $tags_names[] = '<a href="'. $CFG->wwwroot .'/tag/index.php?tag='. rawurlencode($tag->name) .'">'. tag_display_name($tag) .'</a>';
320         }
321     }
322     return implode(', ', $tags_names);
325 /**
326  * Get an array of tag ids associated to a record.
327  *
328  * @param string $record_type the record type for which we want to get the tags
329  * @param int $record_id the record id for which we want to get the tags
330  * @return array of tag ids, indexed and sorted by 'ordering'
331  */
332 function tag_get_tags_ids($record_type, $record_id) {
334     $tag_ids = array();
335     foreach (tag_get_tags($record_type, $record_id) as $tag) {
336         if ( array_key_exists($tag->ordering, $tag_ids) ) {
337             // until we can add a unique constraint, in table tag_instance,
338             // on (itemtype, itemid, ordering), this is needed to prevent a bug
339             // TODO : modify database in 2.0
340             $tag->ordering++;
341         }
342         $tag_ids[$tag->ordering] = $tag->id;
343     }
344     ksort($tag_ids);
345     return $tag_ids;
348 /**
349  * Returns the database ID of a set of tags.
350  *
351  * @param mixed $tags one tag, or array of tags, to look for.
352  * @param bool $return_value specify the type of the returned value. Either
353  *     TAG_RETURN_OBJECT, or TAG_RETURN_ARRAY (default). If TAG_RETURN_ARRAY
354  *     is specified, an array will be returned even if only one tag was
355  *     passed in $tags.
356  * @return mixed tag-indexed array of ids (or objects, if second parameter is
357  *     TAG_RETURN_OBJECT), or only an int, if only one tag is given *and* the
358  *     second parameter is null. No value for a key means the tag wasn't found.
359  */
360 function tag_get_id($tags, $return_value=null) {
361     global $CFG, $DB;
363     static $tag_id_cache = array();
365     $return_an_int = false;
366     if (!is_array($tags)) {
367         if(is_null($return_value) || $return_value == TAG_RETURN_OBJECT) {
368             $return_an_int = true;
369         }
370         $tags = array($tags);
371     }
373     $result = array();
375     //TODO: test this and see if it helps performance without breaking anything
376     //foreach($tags as $key => $tag) {
377     //    $clean_tag = moodle_strtolower($tag);
378     //    if ( array_key_exists($clean_tag), $tag_id_cache) ) {
379     //        $result[$clean_tag] = $tag_id_cache[$clean_tag];
380     //        $tags[$key] = ''; // prevent further processing for this one.
381     //    }
382     //}
384     $tags = array_values(tag_normalize($tags));
385     foreach($tags as $key => $tag) {
386         $tags[$key] = moodle_strtolower($tag);
387         $result[moodle_strtolower($tag)] = null; // key must exists : no value for a key means the tag wasn't found.
388     }
390     if (empty($tags)) {
391         return array();
392     }
394     list($tag_string, $params) = $DB->get_in_or_equal($tags);
396     if ($rs = $DB->get_recordset_sql("SELECT * FROM {tag} WHERE name $tag_string ORDER BY name", $params)) {
397         foreach ($rs as $record) {
398             if ($return_value == TAG_RETURN_OBJECT) {
399                 $result[$record->name] = $record;
400             } else { // TAG_RETURN_ARRAY
401                 $result[$record->name] = $record->id;
402             }
403         }
404         $rs->close();
405     }
407     if ($return_an_int) {
408         return array_pop($result);
409     }
411     return $result;
415 /**
416  * Returns tags related to a tag
417  *
418  * Related tags of a tag come from two sources:
419  *   - manually added related tags, which are tag_instance entries for that tag
420  *   - correlated tags, which are a calculated
421  *
422  * @param string $tag_name_or_id is a single **normalized** tag name or the id
423  *     of a tag
424  * @param int $type the function will return either manually
425  *     (TAG_RELATED_MANUAL) related tags or correlated (TAG_RELATED_CORRELATED)
426  *     tags. Default is TAG_RELATED_ALL, which returns everything.
427  * @param int $limitnum return a subset comprising this many records (optional,
428  *     default is 10)
429  * @return array an array of tag objects
430  */
431 function tag_get_related_tags($tagid, $type=TAG_RELATED_ALL, $limitnum=10) {
433     $related_tags = array();
435     if ( $type == TAG_RELATED_ALL || $type == TAG_RELATED_MANUAL) {
436         //gets the manually added related tags
437         $related_tags = tag_get_tags('tag', $tagid);
438     }
440     if ( $type == TAG_RELATED_ALL || $type == TAG_RELATED_CORRELATED ) {
441         //gets the correlated tags
442         $automatic_related_tags = tag_get_correlated($tagid, $limitnum);
443         if (is_array($automatic_related_tags)) {
444             $related_tags = array_merge($related_tags, $automatic_related_tags);
445         }
446     }
448     return array_slice(object_array_unique($related_tags), 0 , $limitnum);
451 /**
452  * Get a comma-separated list of tags related to another tag.
453  *
454  * @param array $related_tags the array returned by tag_get_related_tags
455  * @param int $html either TAG_RETURN_HTML (default) or TAG_RETURN_TEXT : return html links, or just text.
456  * @return string comma-separated list
457  */
458 function tag_get_related_tags_csv($related_tags, $html=TAG_RETURN_HTML) {
459     global $CFG;
461     $tags_names = array();
462     foreach($related_tags as $tag) {
463         if ( $html == TAG_RETURN_TEXT) {
464             $tags_names[] = tag_display_name($tag, TAG_RETURN_TEXT);
465         } else {
466             // TAG_RETURN_HTML
467             $tags_names[] = '<a href="'. $CFG->wwwroot .'/tag/index.php?tag='. rawurlencode($tag->name) .'">'. tag_display_name($tag) .'</a>';
468         }
469     }
471     return implode(', ', $tags_names);
474 /**
475  * Change the "value" of a tag, and update the associated 'name'.
476  *
477  * @param int $tagid the id of the tag to modify
478  * @param string $newtag the new rawname
479  * @return bool true on success, false otherwise
480  */
481 function tag_rename($tagid, $newrawname) {
482     global $DB;
484     if (! $newrawname_clean = array_shift(tag_normalize($newrawname, TAG_CASE_ORIGINAL)) ) {
485         return false;
486     }
488     if (! $newname_clean = moodle_strtolower($newrawname_clean)) {
489         return false;
490     }
492     // Prevent the rename if a tag with that name already exists
493     if ($existing = tag_get('name', $newname_clean, 'id, name, rawname')) {
494         if ($existing->id != $tagid) {  // Another tag already exists with this name
495             return false;
496         }
497     }
499     if ($tag = tag_get('id', $tagid, 'id, name, rawname')) {
500         $tag->rawname      = $newrawname_clean;
501         $tag->name         = $newname_clean;
502         $tag->timemodified = time();
503         return $DB->update_record('tag', $tag);
504     }
505     return false;
509 /**
510  * Delete one or more tag, and all their instances if there are any left.
511  *
512  * @param mixed $tagids one tagid (int), or one array of tagids to delete
513  * @return bool true on success, false otherwise
514  */
515 function tag_delete($tagids) {
516     global $DB;
518     if (!is_array($tagids)) {
519         $tagids = array($tagids);
520     }
522     $success = true;
523     $context = get_context_instance(CONTEXT_SYSTEM);
524     foreach( $tagids as $tagid ) {
525         if (is_null($tagid)) { // can happen if tag doesn't exists
526             continue;
527         }
528         // only delete the main entry if there were no problems deleting all the
529         // instances - that (and the fact we won't often delete lots of tags)
530         // is the reason for not using $DB->delete_records_select()
531         if ($DB->delete_records('tag_instance', array('tagid'=>$tagid)) ) {
532             $success &= (bool) $DB->delete_records('tag', array('id'=>$tagid));
533             // Delete all files associated with this tag
534             $fs = get_file_storage();
535             $files = $fs->get_area_files($context->id, 'tag', 'description', $tagid);
536             foreach ($files as $file) {
537                 $file->delete();
538             }
539         }
540     }
542     return $success;
545 /**
546  * Delete one instance of a tag.  If the last instance was deleted, it will
547  * also delete the tag, unless its type is 'official'.
548  *
549  * @param string $record_type the type of the record for which to remove the instance
550  * @param int $record_id the id of the record for which to remove the instance
551  * @param int $tagid the tagid that needs to be removed
552  * @return bool true on success, false otherwise
553  */
554 function tag_delete_instance($record_type, $record_id, $tagid) {
555     global $CFG, $DB;
557     if ($DB->delete_records('tag_instance', array('tagid'=>$tagid, 'itemtype'=>$record_type, 'itemid'=>$record_id))) {
558         if (!$DB->record_exists_sql("SELECT * ".
559                                       "FROM {tag} tg ".
560                                      "WHERE tg.id = ? AND ( tg.tagtype = 'official' OR ".
561                                         "EXISTS (SELECT 1
562                                                    FROM {tag_instance} ti
563                                                   WHERE ti.tagid = ?) )",
564                                      array($tagid, $tagid))) {
565             return tag_delete($tagid);
566         }
567     } else {
568         return false;
569     }
571     return true;
575 /**
576  * Function that returns the name that should be displayed for a specific tag
577  *
578  * @param object $tag_object a line out of tag table, as returned by the adobd functions
579  * @param int $html TAG_RETURN_HTML (default) will return htmlspecialchars encoded string, TAG_RETURN_TEXT will not encode.
580  * @return string
581  */
582 function tag_display_name($tagobject, $html=TAG_RETURN_HTML) {
584     global $CFG;
586     if(!isset($tagobject->name)) {
587         return '';
588     }
590     if (empty($CFG->keeptagnamecase)) {
591         //this is the normalized tag name
592         $textlib = textlib_get_instance();
593         $tagname = $textlib->strtotitle($tagobject->name);
594     } else {
595         //original casing of the tag name
596         $tagname = $tagobject->rawname;
597     }
599     if ($html == TAG_RETURN_TEXT) {
600         return $tagname;
601     } else { // TAG_RETURN_HTML
602         return htmlspecialchars($tagname);
603     }
606 /**
607  * Find all records tagged with a tag of a given type ('post', 'user', etc.)
608  *
609  * @param string $tag tag to look for
610  * @param string $type type to restrict search to.  If null, every matching
611  *     record will be returned
612  * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
613  * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
614  * @return array of matching objects, indexed by record id, from the table containing the type requested
615  */
616 function tag_find_records($tag, $type, $limitfrom='', $limitnum='') {
617     global $CFG, $DB;
619     if (!$tag || !$type) {
620         return array();
621     }
623     $tagid = tag_get_id($tag);
625     $query = "SELECT it.*
626                 FROM {".$type."} it INNER JOIN {tag_instance} tt ON it.id = tt.itemid
627                WHERE tt.itemtype = ? AND tt.tagid = ?";
628     $params = array($type, $tagid);
630     return $DB->get_records_sql($query, $params, $limitfrom, $limitnum);
636 ///////////////////////////////////////////////////////
637 /////////////////// PRIVATE TAG API ///////////////////
639 /**
640  * Adds one or more tag in the database.  This function should not be called
641  * directly : you should use tag_set.
642  *
643  * @param mixed $tags one tag, or an array of tags, to be created
644  * @param string $type type of tag to be created ("default" is the default
645  *     value and "official" is the only other supported value at this time). An
646  *     official tag is kept even if there are no records tagged with it.
647  * @return an array of tags ids, indexed by their lowercase normalized names.
648  *     Any boolean false in the array indicates an error while adding the tag.
649  */
650 function tag_add($tags, $type="default") {
651     global $USER, $DB;
653     if (!is_array($tags)) {
654         $tags = array($tags);
655     }
657     $tag_object = new StdClass;
658     $tag_object->tagtype      = $type;
659     $tag_object->userid       = $USER->id;
660     $tag_object->timemodified = time();
662     $clean_tags = tag_normalize($tags, TAG_CASE_ORIGINAL);
664     $tags_ids = array();
665     foreach($clean_tags as $tag) {
666         $tag = trim($tag);
667         if (!$tag) {
668             $tags_ids[$tag] = false;
669         } else {
670             // note that the difference between rawname and name is only
671             // capitalization : the rawname is NOT the same at the rawtag.
672             $tag_object->rawname = $tag;
673             $tag_name_lc         = moodle_strtolower($tag);
674             $tag_object->name    = $tag_name_lc;
675             //var_dump($tag_object);
676             $tags_ids[$tag_name_lc] = $DB->insert_record('tag', $tag_object);
677         }
678     }
680     return $tags_ids;
683 /**
684  * Assigns a tag to a record: if the record already exists, the time and
685  * ordering will be updated.
686  *
687  * @param string $record_type the type of the record that will be tagged
688  * @param int $record_id the id of the record that will be tagged
689  * @param string $tagid the tag id to set on the record.
690  * @param int $ordering the order of the instance for this record
691  * @param int $userid optional only required for course tagging
692  * @return bool true on success, false otherwise
693  */
694 function tag_assign($record_type, $record_id, $tagid, $ordering, $userid = 0) {
695     global $DB;
697     if ( $tag_instance_object = $DB->get_record('tag_instance', array('tagid'=>$tagid, 'itemtype'=>$record_type, 'itemid'=>$record_id, 'tiuserid'=>$userid), 'id')) {
698         $tag_instance_object->ordering     = $ordering;
699         $tag_instance_object->timemodified = time();
700         return $DB->update_record('tag_instance', $tag_instance_object);
701     } else {
702         $tag_instance_object = new StdClass;
703         $tag_instance_object->tagid        = $tagid;
704         $tag_instance_object->itemid       = $record_id;
705         $tag_instance_object->itemtype     = $record_type;
706         $tag_instance_object->ordering     = $ordering;
707         $tag_instance_object->timemodified = time();
708         $tag_instance_object->tiuserid     = $userid;
709         return $DB->insert_record('tag_instance', $tag_instance_object);
710     }
713 /**
714  * Function that returns tags that start with some text, for use by the autocomplete feature
715  *
716  * @param string $text string that the tag names will be matched against
717  * @return mixed an array of objects, or false if no records were found or an error occured.
718  */
719 function tag_autocomplete($text) {
720     global $DB;
721     return $DB->get_records_sql("SELECT tg.id, tg.name, tg.rawname
722                                    FROM {tag} tg
723                                   WHERE tg.name LIKE ?", array(moodle_strtolower($text)."%"));
726 /**
727  * Clean up the tag tables, making sure all tagged object still exists.
728  *
729  * This should normally not be necessary, but in case related tags are not deleted
730  * when the tagged record is removed, this should be done once in a while, perhaps on
731  * an occasional cron run.  On a site with lots of tags, this could become an expensive
732  * function to call: don't run at peak time.
733  */
734 function tag_cleanup() {
735     global $DB;
737     $instances = $DB->get_recordset('tag_instance');
739     // cleanup tag instances
740     foreach ($instances as $instance) {
741         $delete = false;
743         if (!$DB->record_exists('tag', array('id'=>$instance->tagid))) {
744             // if the tag has been removed, instance should be deleted.
745             $delete = true;
746         } else {
747             switch ($instance->itemtype) {
748                 case 'user': // users are marked as deleted, but not actually deleted
749                     if ($DB->record_exists('user', array('id'=>$instance->itemid, 'deleted'=>1))) {
750                         $delete = true;
751                     }
752                     break;
753                 default: // anything else, if the instance is not there, delete.
754                     if (!$DB->record_exists($instance->itemtype, array('id'=>$instance->itemid))) {
755                         $delete = true;
756                     }
757                     break;
758             }
759         }
760         if ($delete) {
761             tag_delete_instance($instance->itemtype, $instance->itemid, $instance->tagid);
762             //debugging('deleting tag_instance #'. $instance->id .', linked to tag id #'. $instance->tagid, DEBUG_DEVELOPER);
763         }
764     }
765     $instances->close();
767     // TODO: this will only clean tags of type 'default'.  This is good as
768     // it won't delete 'official' tags, but the day we get more than two
769     // types, we need to fix this.
770     $unused_tags = $DB->get_recordset_sql("SELECT tg.id
771                                              FROM {tag} tg
772                                             WHERE tg.tagtype = 'default'
773                                                   AND NOT EXISTS (
774                                                       SELECT 'x'
775                                                         FROM {tag_instance} ti
776                                                        WHERE ti.tagid = tg.id
777                                                   )");
779     // cleanup tags
780     foreach ($unused_tags as $unused_tag) {
781         tag_delete($unused_tag->id);
782         //debugging('deleting unused tag #'. $unused_tag->id,  DEBUG_DEVELOPER);
783     }
784     $unused_tags->close();
787 /**
788  * Calculates and stores the correlated tags of all tags.
789  * The correlations are stored in the 'tag_correlation' table.
790  *
791  * Two tags are correlated if they appear together a lot.
792  * Ex.: Users tagged with "computers" will probably also be tagged with "algorithms".
793  *
794  * The rationale for the 'tag_correlation' table is performance.
795  * It works as a cache for a potentially heavy load query done at the 'tag_instance' table.
796  * So, the 'tag_correlation' table stores redundant information derived from the 'tag_instance' table.
797  *
798  * @param number $min_correlation cutoff percentage (optional, default is 2)
799  */
800 function tag_compute_correlations($min_correlation=2) {
801     global $DB;
803     if (!$all_tags = $DB->get_records('tag')) {
804         return;
805     }
807     $tag_correlation_obj = new object();
808     foreach($all_tags as $tag) {
810         // query that counts how many times any tag appears together in items
811         // with the tag passed as argument ($tag_id)
812         $query = "SELECT tb.tagid
813                     FROM {tag_instance} ta JOIN {tag_instance} tb ON ta.itemid = tb.itemid
814                    WHERE ta.tagid = ? AND tb.tagid <> ?
815                 GROUP BY tb.tagid
816                   HAVING COUNT(*) > ?
817                 ORDER BY COUNT(*) DESC";
818         $params = array($tag->id, $tag->id, $min_correlation);
820         $correlated = array();
822         // Correlated tags happen when they appear together in more occasions
823         // than $min_correlation.
824         if ($tag_correlations = $DB->get_records_sql($query, $params)) {
825             foreach($tag_correlations as $correlation) {
826             // commented out - now done in query. kept here in case it breaks on some db
827             // if($correlation->nr >= $min_correlation){
828                     $correlated[] = $correlation->tagid;
829             // }
830             }
831         }
833         if (empty($correlated)) {
834             continue;
835         }
837         $correlated = implode(',', $correlated);
838         //var_dump($correlated);
840         //saves correlation info in the caching table
841         if ($tag_correlation_obj = $DB->get_record('tag_correlation', array('tagid'=>$tag->id), 'tagid')) {
842             $tag_correlation_obj->correlatedtags = $correlated;
843             $DB->update_record('tag_correlation', $tag_correlation_obj);
844         } else {
845             $tag_correlation_obj->tagid          = $tag->id;
846             $tag_correlation_obj->correlatedtags = $correlated;
847             $DB->insert_record('tag_correlation', $tag_correlation_obj);
848         }
849     }
852 /**
853  * Tasks that should be performed at cron time
854  */
855 function tag_cron() {
856     tag_compute_correlations();
857     tag_cleanup();
860 /**
861  * Search for tags with names that match some text
862  *
863  * @param string $text escaped string that the tag names will be matched against
864  * @param boolean $ordered If true, tags are ordered by their popularity. If false, no ordering.
865  * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
866  * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
867  * @return mixed an array of objects, or false if no records were found or an error occured.
868  */
869 function tag_find_tags($text, $ordered=true, $limitfrom='', $limitnum='') {
870     global $DB;
872     $text = array_shift(tag_normalize($text, TAG_CASE_LOWER));
874     if ($ordered) {
875         $query = "SELECT tg.id, tg.name, tg.rawname, COUNT(ti.id) AS count
876                     FROM {tag} tg LEFT JOIN {tag_instance} ti ON tg.id = ti.tagid
877                    WHERE tg.name LIKE ?
878                 GROUP BY tg.id, tg.name, tg.rawname
879                 ORDER BY count DESC";
880     } else {
881         $query = "SELECT tg.id, tg.name, tg.rawname
882                     FROM {tag} tg
883                    WHERE tg.name LIKE ?";
884     }
885     $params = array("%{$text}%");
886     return $DB->get_records_sql($query, $params, $limitfrom , $limitnum);
889 /**
890  * Get the name of a tag
891  *
892  * @param mixed $tagids the id of the tag, or an array of ids
893  * @return mixed string name of one tag, or id-indexed array of strings
894  */
895 function tag_get_name($tagids) {
896     global $DB;
898     if (!is_array($tagids)) {
899         if ($tag = $DB->get_record('tag', array('id'=>$tagids))) {
900             return $tag->name;
901         }
902         return false;
903     }
905     $tag_names = array();
906     foreach($DB->get_records_list('tag', 'id', $tagids) as $tag) {
907         $tag_names[$tag->id] = $tag->name;
908     }
910     return $tag_names;
913 /**
914  * Returns the correlated tags of a tag, retrieved from the tag_correlation
915  * table.  Make sure cron runs, otherwise the table will be empty and this
916  * function won't return anything.
917  *
918  * @param int $tag_id is a single tag id
919  * @return array an array of tag objects, empty if no correlated tags are found
920  */
921 function tag_get_correlated($tag_id, $limitnum=null) {
922     global $DB;
924     $tag_correlation = $DB->get_record('tag_correlation', array('tagid'=>$tag_id));
926     if (!$tag_correlation || empty($tag_correlation->correlatedtags)) {
927         return array();
928     }
930     // this is (and has to) return the same fields as the query in tag_get_tags
931     if ( !$result = $DB->get_records_sql("SELECT tg.id, tg.tagtype, tg.name, tg.rawname, tg.flag, ti.ordering
932                                             FROM {tag} tg INNER JOIN {tag_instance} ti ON tg.id = ti.tagid
933                                            WHERE tg.id IN ({$tag_correlation->correlatedtags})") ) {
934         return array();
935     }
937     return $result;
940 /**
941  * Function that normalizes a list of tag names.
942  *
943  * @param mixed $tags array of tags, or a single tag.
944  * @param int $case case to use for returned value (default: lower case).
945  *     Either TAG_CASE_LOWER (default) or TAG_CASE_ORIGINAL
946  * @return array of lowercased normalized tags, indexed by the normalized tag,
947  *     in the same order as the original array. (Eg: 'Banana' => 'banana').
948  */
949 function tag_normalize($rawtags, $case = TAG_CASE_LOWER) {
951     // cache normalized tags, to prevent costly repeated calls to clean_param
952     static $cleaned_tags_lc = array(); // lower case - use for comparison
953     static $cleaned_tags_mc = array(); // mixed case - use for saving to database
955     if ( !is_array($rawtags) ) {
956         $rawtags = array($rawtags);
957     }
959     $result = array();
960     foreach($rawtags as $rawtag) {
961         $rawtag = trim($rawtag);
962         if (!$rawtag) {
963             continue;
964         }
965         if ( !array_key_exists($rawtag, $cleaned_tags_lc) ) {
966             $cleaned_tags_lc[$rawtag] = moodle_strtolower( clean_param($rawtag, PARAM_TAG) );
967             $cleaned_tags_mc[$rawtag] = clean_param($rawtag, PARAM_TAG);
968         }
969         if ( $case == TAG_CASE_LOWER ) {
970             $result[$rawtag] = $cleaned_tags_lc[$rawtag];
971         } else { // TAG_CASE_ORIGINAL
972             $result[$rawtag] = $cleaned_tags_mc[$rawtag];
973         }
974     }
976     return $result;
979 /**
980  * Count how many records are tagged with a specific tag,
981  *
982  * @param string $record record to look for ('post', 'user', etc.)
983  * @param int $tag is a single tag id
984  * @return int number of mathing tags.
985  */
986 function tag_record_count($record_type, $tagid) {
987     global $DB;
988     return $DB->count_records('tag_instance', array('itemtype'=>$record_type, 'tagid'=>$tagid));
991 /**
992  * Determine if a record is tagged with a specific tag
993  *
994  * @param string $record_type the record type to look for
995  * @param int $record_id the record id to look for
996  * @param string $tag a tag name
997  * @return bool true if it is tagged, false otherwise
998  */
999 function tag_record_tagged_with($record_type, $record_id, $tag) {
1000     global $DB;
1001     if ($tagid = tag_get_id($tag)) {
1002         return $DB->count_records('tag_instance', array('itemtype'=>$record_type, 'itemid'=>$record_id, 'tagid'=>$tagid));
1003     } else {
1004         return 0; // tag doesn't exist
1005     }
1008 /**
1009  * Flag a tag as inapropriate
1010  *
1011  * @param mixed $tagids one (int) tagid, or an array of tagids
1012  * @return void
1013  */
1014 function tag_set_flag($tagids) {
1015     global $DB;
1017     $tagids = (array)$tagids;
1018     foreach ($tagids as $tagid) {
1019         $tag = $DB->get_record('tag', array('id'=>$tagid), 'id, flag');
1020         $tag->flag++;
1021         $tag->timemodified = time();
1022         $DB->update_record('tag', $tag);
1023     }
1026 /**
1027  * Remove the inapropriate flag on a tag
1028  *
1029  * @param mixed $tagids one (int) tagid, or an array of tagids
1030  * @return bool true if function succeeds, false otherwise
1031  */
1032 function tag_unset_flag($tagids) {
1033     global $DB;
1035     if ( is_array($tagids) ) {
1036         $tagids = implode(',', $tagids);
1037     }
1038     $timemodified = time();
1039     return $DB->execute("UPDATE {tag} SET flag = 0, timemodified = ? WHERE id IN ($tagids)", array($timemodified));