46834b47407c7c952df53f0894aaafd8bcbb9568
[moodle.git] / tag / lib.php
1 <?php
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/>.
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  */
53 define('TAG_RETURN_ARRAY', 0);
54 define('TAG_RETURN_OBJECT', 1);
55 define('TAG_RETURN_TEXT', 2);
56 define('TAG_RETURN_HTML', 3);
58 define('TAG_CASE_LOWER', 0);
59 define('TAG_CASE_ORIGINAL', 1);
61 define('TAG_RELATED_ALL', 0);
62 define('TAG_RELATED_MANUAL', 1);
63 define('TAG_RELATED_CORRELATED', 2);
65 ///////////////////////////////////////////////////////
66 /////////////////// PUBLIC TAG API ////////////////////
68 /// Functions for settings tags  //////////////////////
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) {
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     }
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);
94     $current_ids = tag_get_tags_ids($record_type, $record_id);
95     //var_dump($current_ids);
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     }
110     if (empty($tags)) {
111         return true;
112     }
114     foreach($tags as $ordering => $tag) {
115         $tag = trim($tag);
116         if (!$tag) {
117             continue;
118         }
120         $clean_tag = $cleaned_tags[$tag];
121         $tag_current_id = $tags_ids[$clean_tag];
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         }
130         tag_assign($record_type, $record_id, $tag_current_id, $ordering);
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     }
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) {
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;
159     return tag_set($record_type, $record_id, $new_tags);
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) {
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     }
180     return tag_set($record_type, $record_id, $new_tags);
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;
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;
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;
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;
229 /// Functions for getting information about tags //////
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;
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);
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  *
254  * @param string $record_type the record type for which we want to get the tags
255  * @param int $record_id the record id for which we want to get the tags
256  * @param string $type the tag type (either 'default' or 'official'). By default,
257  *     all tags are returned.
258  * @param int $userid optional only required for course tagging
259  * @return array the array of tags
260  */
261 function tag_get_tags($record_type, $record_id, $type=null, $userid=0) {
262     global $CFG, $DB;
264     $params = array();
266     if ($type) {
267         $sql_type = "AND tg.tagtype = :type";
268         $params['type'] = $type;
269     } else {
270         $sql_type = '';
271     }
273    $u = null;
274     if ($userid) {
275         $u =  "AND ti.tiuserid = :userid ";
276         $params['userid'] = $userid;
277     }
279     $sql = "SELECT tg.id, tg.tagtype, tg.name, tg.rawname, tg.flag, ti.ordering
280               FROM {tag_instance} ti JOIN {tag} tg ON tg.id = ti.tagid
281               WHERE ti.itemtype = :recordtype AND ti.itemid = :recordid $u $sql_type
282            ORDER BY ti.ordering ASC";
283     $params['recordtype'] = $record_type;
284     $params['recordid']   = $record_id;
286     // if the fields in this query are changed, you need to do the same changes in tag_get_correlated_tags
287     return $DB->get_records_sql($sql, $params);
288     // This version of the query, reversing the ON clause, "correctly" returns
289     // a row with NULL values for instances that are still in the DB even though
290     // the tag has been deleted.  This shouldn't happen, but if it did, using
291     // this query could help "clean it up".  This causes bugs at this time.
292     //$tags = $DB->get_records_sql("SELECT ti.tagid, tg.tagtype, tg.name, tg.rawname, tg.flag, ti.ordering ".
293     //    "FROM {tag_instance} ti LEFT JOIN {tag} tg ON ti.tagid = tg.id ".
294     //    "WHERE ti.itemtype = '{$record_type}' AND ti.itemid = '{$record_id}' {$type} ".
295     //    "ORDER BY ti.ordering ASC");
298 /**
299  * Get the array of tags display names, indexed by id.
300  *
301  * @param string $record_type the record type for which we want to get the tags
302  * @param int $record_id the record id for which we want to get the tags
303  * @param string $type the tag type (either 'default' or 'official'). By default,
304  *     all tags are returned.
305  * @return array the array of tags (with the value returned by tag_display_name), indexed by id
306  */
307 function tag_get_tags_array($record_type, $record_id, $type=null) {
308     $tags = array();
309     foreach(tag_get_tags($record_type, $record_id, $type) as $tag) {
310         $tags[$tag->id] = tag_display_name($tag);
311     }
312     return $tags;
315 /**
316  * Get a comma-separated string of tags associated to a record.  Use tag_get_tags
317  * to get the same information in an array.
318  *
319  * @param string $record_type the record type for which we want to get the tags
320  * @param int $record_id the record id for which we want to get the tags
321  * @param int $html either TAG_RETURN_HTML or TAG_RETURN_TEXT, depending
322  *     on the type of output desired
323  * @param string $type either 'official' or 'default', if null, all tags are
324  *     returned
325  * @return string the comma-separated list of tags.
326  */
327 function tag_get_tags_csv($record_type, $record_id, $html=TAG_RETURN_HTML, $type=null) {
328     global $CFG;
330     $tags_names = array();
331     foreach(tag_get_tags($record_type, $record_id, $type) as $tag) {
332         if ($html == TAG_RETURN_TEXT) {
333             $tags_names[] = tag_display_name($tag, TAG_RETURN_TEXT);
334         } else { // TAG_RETURN_HTML
335             $tags_names[] = '<a href="'. $CFG->wwwroot .'/tag/index.php?tag='. rawurlencode($tag->name) .'">'. tag_display_name($tag) .'</a>';
336         }
337     }
338     return implode(', ', $tags_names);
341 /**
342  * Get an array of tag ids associated to a record.
343  *
344  * @param string $record_type the record type for which we want to get the tags
345  * @param int $record_id the record id for which we want to get the tags
346  * @return array of tag ids, indexed and sorted by 'ordering'
347  */
348 function tag_get_tags_ids($record_type, $record_id) {
350     $tag_ids = array();
351     foreach (tag_get_tags($record_type, $record_id) as $tag) {
352         if ( array_key_exists($tag->ordering, $tag_ids) ) {
353             // until we can add a unique constraint, in table tag_instance,
354             // on (itemtype, itemid, ordering), this is needed to prevent a bug
355             // TODO : modify database in 2.0
356             $tag->ordering++;
357         }
358         $tag_ids[$tag->ordering] = $tag->id;
359     }
360     ksort($tag_ids);
361     return $tag_ids;
364 /**
365  * Returns the database ID of a set of tags.
366  *
367  * @param mixed $tags one tag, or array of tags, to look for.
368  * @param bool $return_value specify the type of the returned value. Either
369  *     TAG_RETURN_OBJECT, or TAG_RETURN_ARRAY (default). If TAG_RETURN_ARRAY
370  *     is specified, an array will be returned even if only one tag was
371  *     passed in $tags.
372  * @return mixed tag-indexed array of ids (or objects, if second parameter is
373  *     TAG_RETURN_OBJECT), or only an int, if only one tag is given *and* the
374  *     second parameter is null. No value for a key means the tag wasn't found.
375  */
376 function tag_get_id($tags, $return_value=null) {
377     global $CFG, $DB;
379     static $tag_id_cache = array();
381     $return_an_int = false;
382     if (!is_array($tags)) {
383         if(is_null($return_value) || $return_value == TAG_RETURN_OBJECT) {
384             $return_an_int = true;
385         }
386         $tags = array($tags);
387     }
389     $result = array();
391     //TODO: test this and see if it helps performance without breaking anything
392     //foreach($tags as $key => $tag) {
393     //    $clean_tag = moodle_strtolower($tag);
394     //    if ( array_key_exists($clean_tag), $tag_id_cache) ) {
395     //        $result[$clean_tag] = $tag_id_cache[$clean_tag];
396     //        $tags[$key] = ''; // prevent further processing for this one.
397     //    }
398     //}
400     $tags = array_values(tag_normalize($tags));
401     foreach($tags as $key => $tag) {
402         $tags[$key] = moodle_strtolower($tag);
403         $result[moodle_strtolower($tag)] = null; // key must exists : no value for a key means the tag wasn't found.
404     }
406     if (empty($tags)) {
407         return array();
408     }
410     list($tag_string, $params) = $DB->get_in_or_equal($tags);
412     if ($rs = $DB->get_recordset_sql("SELECT * FROM {tag} WHERE name $tag_string ORDER BY name", $params)) {
413         foreach ($rs as $record) {
414             if ($return_value == TAG_RETURN_OBJECT) {
415                 $result[$record->name] = $record;
416             } else { // TAG_RETURN_ARRAY
417                 $result[$record->name] = $record->id;
418             }
419         }
420         $rs->close();
421     }
423     if ($return_an_int) {
424         return array_pop($result);
425     }
427     return $result;
431 /**
432  * Returns tags related to a tag
433  *
434  * Related tags of a tag come from two sources:
435  *   - manually added related tags, which are tag_instance entries for that tag
436  *   - correlated tags, which are a calculated
437  *
438  * @param string $tag_name_or_id is a single **normalized** tag name or the id
439  *     of a tag
440  * @param int $type the function will return either manually
441  *     (TAG_RELATED_MANUAL) related tags or correlated (TAG_RELATED_CORRELATED)
442  *     tags. Default is TAG_RELATED_ALL, which returns everything.
443  * @param int $limitnum return a subset comprising this many records (optional,
444  *     default is 10)
445  * @return array an array of tag objects
446  */
447 function tag_get_related_tags($tagid, $type=TAG_RELATED_ALL, $limitnum=10) {
449     $related_tags = array();
451     if ( $type == TAG_RELATED_ALL || $type == TAG_RELATED_MANUAL) {
452         //gets the manually added related tags
453         $related_tags = tag_get_tags('tag', $tagid);
454     }
456     if ( $type == TAG_RELATED_ALL || $type == TAG_RELATED_CORRELATED ) {
457         //gets the correlated tags
458         $automatic_related_tags = tag_get_correlated($tagid, $limitnum);
459         if (is_array($automatic_related_tags)) {
460             $related_tags = array_merge($related_tags, $automatic_related_tags);
461         }
462     }
464     return array_slice(object_array_unique($related_tags), 0 , $limitnum);
467 /**
468  * Get a comma-separated list of tags related to another tag.
469  *
470  * @param array $related_tags the array returned by tag_get_related_tags
471  * @param int $html either TAG_RETURN_HTML (default) or TAG_RETURN_TEXT : return html links, or just text.
472  * @return string comma-separated list
473  */
474 function tag_get_related_tags_csv($related_tags, $html=TAG_RETURN_HTML) {
475     global $CFG;
477     $tags_names = array();
478     foreach($related_tags as $tag) {
479         if ( $html == TAG_RETURN_TEXT) {
480             $tags_names[] = tag_display_name($tag, TAG_RETURN_TEXT);
481         } else {
482             // TAG_RETURN_HTML
483             $tags_names[] = '<a href="'. $CFG->wwwroot .'/tag/index.php?tag='. rawurlencode($tag->name) .'">'. tag_display_name($tag) .'</a>';
484         }
485     }
487     return implode(', ', $tags_names);
490 /**
491  * Change the "value" of a tag, and update the associated 'name'.
492  *
493  * @param int $tagid the id of the tag to modify
494  * @param string $newtag the new rawname
495  * @return bool true on success, false otherwise
496  */
497 function tag_rename($tagid, $newrawname) {
498     global $DB;
500     if (! $newrawname_clean = array_shift(tag_normalize($newrawname, TAG_CASE_ORIGINAL)) ) {
501         return false;
502     }
504     if (! $newname_clean = moodle_strtolower($newrawname_clean)) {
505         return false;
506     }
508     // Prevent the rename if a tag with that name already exists
509     if ($existing = tag_get('name', $newname_clean, 'id, name, rawname')) {
510         if ($existing->id != $tagid) {  // Another tag already exists with this name
511             return false;
512         }
513     }
515     if ($tag = tag_get('id', $tagid, 'id, name, rawname')) {
516         $tag->rawname      = $newrawname_clean;
517         $tag->name         = $newname_clean;
518         $tag->timemodified = time();
519         return $DB->update_record('tag', $tag);
520     }
521     return false;
525 /**
526  * Delete one or more tag, and all their instances if there are any left.
527  *
528  * @param mixed $tagids one tagid (int), or one array of tagids to delete
529  * @return bool true on success, false otherwise
530  */
531 function tag_delete($tagids) {
532     global $DB;
534     if (!is_array($tagids)) {
535         $tagids = array($tagids);
536     }
538     $success = true;
539     $context = get_context_instance(CONTEXT_SYSTEM);
540     foreach( $tagids as $tagid ) {
541         if (is_null($tagid)) { // can happen if tag doesn't exists
542             continue;
543         }
544         // only delete the main entry if there were no problems deleting all the
545         // instances - that (and the fact we won't often delete lots of tags)
546         // is the reason for not using $DB->delete_records_select()
547         if ($DB->delete_records('tag_instance', array('tagid'=>$tagid)) ) {
548             $success &= (bool) $DB->delete_records('tag', array('id'=>$tagid));
549             // Delete all files associated with this tag
550             $fs = get_file_storage();
551             $files = $fs->get_area_files($context->id, 'tag', 'description', $tagid);
552             foreach ($files as $file) {
553                 $file->delete();
554             }
555         }
556     }
558     return $success;
561 /**
562  * Delete one instance of a tag.  If the last instance was deleted, it will
563  * also delete the tag, unless its type is 'official'.
564  *
565  * @param string $record_type the type of the record for which to remove the instance
566  * @param int $record_id the id of the record for which to remove the instance
567  * @param int $tagid the tagid that needs to be removed
568  * @return bool true on success, false otherwise
569  */
570 function tag_delete_instance($record_type, $record_id, $tagid) {
571     global $CFG, $DB;
573     if ($DB->delete_records('tag_instance', array('tagid'=>$tagid, 'itemtype'=>$record_type, 'itemid'=>$record_id))) {
574         if (!$DB->record_exists_sql("SELECT * ".
575                                       "FROM {tag} tg ".
576                                      "WHERE tg.id = ? AND ( tg.tagtype = 'official' OR ".
577                                         "EXISTS (SELECT 1
578                                                    FROM {tag_instance} ti
579                                                   WHERE ti.tagid = ?) )",
580                                      array($tagid, $tagid))) {
581             return tag_delete($tagid);
582         }
583     } else {
584         return false;
585     }
587     return true;
591 /**
592  * Function that returns the name that should be displayed for a specific tag
593  *
594  * @param object $tag_object a line out of tag table, as returned by the adobd functions
595  * @param int $html TAG_RETURN_HTML (default) will return htmlspecialchars encoded string, TAG_RETURN_TEXT will not encode.
596  * @return string
597  */
598 function tag_display_name($tagobject, $html=TAG_RETURN_HTML) {
600     global $CFG;
602     if(!isset($tagobject->name)) {
603         return '';
604     }
606     if (empty($CFG->keeptagnamecase)) {
607         //this is the normalized tag name
608         $textlib = textlib_get_instance();
609         $tagname = $textlib->strtotitle($tagobject->name);
610     } else {
611         //original casing of the tag name
612         $tagname = $tagobject->rawname;
613     }
615     if ($html == TAG_RETURN_TEXT) {
616         return $tagname;
617     } else { // TAG_RETURN_HTML
618         return htmlspecialchars($tagname);
619     }
622 /**
623  * Find all records tagged with a tag of a given type ('post', 'user', etc.)
624  *
625  * @param string $tag tag to look for
626  * @param string $type type to restrict search to.  If null, every matching
627  *     record will be returned
628  * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
629  * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
630  * @return array of matching objects, indexed by record id, from the table containing the type requested
631  */
632 function tag_find_records($tag, $type, $limitfrom='', $limitnum='') {
633     global $CFG, $DB;
635     if (!$tag || !$type) {
636         return array();
637     }
639     $tagid = tag_get_id($tag);
641     $query = "SELECT it.*
642                 FROM {".$type."} it INNER JOIN {tag_instance} tt ON it.id = tt.itemid
643                WHERE tt.itemtype = ? AND tt.tagid = ?";
644     $params = array($type, $tagid);
646     return $DB->get_records_sql($query, $params, $limitfrom, $limitnum);
652 ///////////////////////////////////////////////////////
653 /////////////////// PRIVATE TAG API ///////////////////
655 /**
656  * Adds one or more tag in the database.  This function should not be called
657  * directly : you should use tag_set.
658  *
659  * @param mixed $tags one tag, or an array of tags, to be created
660  * @param string $type type of tag to be created ("default" is the default
661  *     value and "official" is the only other supported value at this time). An
662  *     official tag is kept even if there are no records tagged with it.
663  * @return an array of tags ids, indexed by their lowercase normalized names.
664  *     Any boolean false in the array indicates an error while adding the tag.
665  */
666 function tag_add($tags, $type="default") {
667     global $USER, $DB;
669     if (!is_array($tags)) {
670         $tags = array($tags);
671     }
673     $tag_object = new StdClass;
674     $tag_object->tagtype      = $type;
675     $tag_object->userid       = $USER->id;
676     $tag_object->timemodified = time();
678     $clean_tags = tag_normalize($tags, TAG_CASE_ORIGINAL);
680     $tags_ids = array();
681     foreach($clean_tags as $tag) {
682         $tag = trim($tag);
683         if (!$tag) {
684             $tags_ids[$tag] = false;
685         } else {
686             // note that the difference between rawname and name is only
687             // capitalization : the rawname is NOT the same at the rawtag.
688             $tag_object->rawname = $tag;
689             $tag_name_lc         = moodle_strtolower($tag);
690             $tag_object->name    = $tag_name_lc;
691             //var_dump($tag_object);
692             $tags_ids[$tag_name_lc] = $DB->insert_record('tag', $tag_object);
693         }
694     }
696     return $tags_ids;
699 /**
700  * Assigns a tag to a record: if the record already exists, the time and
701  * ordering will be updated.
702  *
703  * @param string $record_type the type of the record that will be tagged
704  * @param int $record_id the id of the record that will be tagged
705  * @param string $tagid the tag id to set on the record.
706  * @param int $ordering the order of the instance for this record
707  * @param int $userid optional only required for course tagging
708  * @return bool true on success, false otherwise
709  */
710 function tag_assign($record_type, $record_id, $tagid, $ordering, $userid = 0) {
711     global $DB;
713     if ( $tag_instance_object = $DB->get_record('tag_instance', array('tagid'=>$tagid, 'itemtype'=>$record_type, 'itemid'=>$record_id, 'tiuserid'=>$userid), 'id')) {
714         $tag_instance_object->ordering     = $ordering;
715         $tag_instance_object->timemodified = time();
716         return $DB->update_record('tag_instance', $tag_instance_object);
717     } else {
718         $tag_instance_object = new StdClass;
719         $tag_instance_object->tagid        = $tagid;
720         $tag_instance_object->itemid       = $record_id;
721         $tag_instance_object->itemtype     = $record_type;
722         $tag_instance_object->ordering     = $ordering;
723         $tag_instance_object->timemodified = time();
724         $tag_instance_object->tiuserid     = $userid;
725         return $DB->insert_record('tag_instance', $tag_instance_object);
726     }
729 /**
730  * Function that returns tags that start with some text, for use by the autocomplete feature
731  *
732  * @param string $text string that the tag names will be matched against
733  * @return mixed an array of objects, or false if no records were found or an error occured.
734  */
735 function tag_autocomplete($text) {
736     global $DB;
737     return $DB->get_records_sql("SELECT tg.id, tg.name, tg.rawname
738                                    FROM {tag} tg
739                                   WHERE tg.name LIKE ?", array(moodle_strtolower($text)."%"));
742 /**
743  * Clean up the tag tables, making sure all tagged object still exists.
744  *
745  * This should normally not be necessary, but in case related tags are not deleted
746  * when the tagged record is removed, this should be done once in a while, perhaps on
747  * an occasional cron run.  On a site with lots of tags, this could become an expensive
748  * function to call: don't run at peak time.
749  */
750 function tag_cleanup() {
751     global $DB;
753     $instances = $DB->get_recordset('tag_instance');
755     // cleanup tag instances
756     foreach ($instances as $instance) {
757         $delete = false;
759         if (!$DB->record_exists('tag', array('id'=>$instance->tagid))) {
760             // if the tag has been removed, instance should be deleted.
761             $delete = true;
762         } else {
763             switch ($instance->itemtype) {
764                 case 'user': // users are marked as deleted, but not actually deleted
765                     if ($DB->record_exists('user', array('id'=>$instance->itemid, 'deleted'=>1))) {
766                         $delete = true;
767                     }
768                     break;
769                 default: // anything else, if the instance is not there, delete.
770                     if (!$DB->record_exists($instance->itemtype, array('id'=>$instance->itemid))) {
771                         $delete = true;
772                     }
773                     break;
774             }
775         }
776         if ($delete) {
777             tag_delete_instance($instance->itemtype, $instance->itemid, $instance->tagid);
778             //debugging('deleting tag_instance #'. $instance->id .', linked to tag id #'. $instance->tagid, DEBUG_DEVELOPER);
779         }
780     }
781     $instances->close();
783     // TODO: this will only clean tags of type 'default'.  This is good as
784     // it won't delete 'official' tags, but the day we get more than two
785     // types, we need to fix this.
786     $unused_tags = $DB->get_recordset_sql("SELECT tg.id
787                                              FROM {tag} tg
788                                             WHERE tg.tagtype = 'default'
789                                                   AND NOT EXISTS (
790                                                       SELECT 'x'
791                                                         FROM {tag_instance} ti
792                                                        WHERE ti.tagid = tg.id
793                                                   )");
795     // cleanup tags
796     foreach ($unused_tags as $unused_tag) {
797         tag_delete($unused_tag->id);
798         //debugging('deleting unused tag #'. $unused_tag->id,  DEBUG_DEVELOPER);
799     }
800     $unused_tags->close();
803 /**
804  * Calculates and stores the correlated tags of all tags.
805  * The correlations are stored in the 'tag_correlation' table.
806  *
807  * Two tags are correlated if they appear together a lot.
808  * Ex.: Users tagged with "computers" will probably also be tagged with "algorithms".
809  *
810  * The rationale for the 'tag_correlation' table is performance.
811  * It works as a cache for a potentially heavy load query done at the 'tag_instance' table.
812  * So, the 'tag_correlation' table stores redundant information derived from the 'tag_instance' table.
813  *
814  * @param number $min_correlation cutoff percentage (optional, default is 2)
815  */
816 function tag_compute_correlations($min_correlation=2) {
817     global $DB;
819     if (!$all_tags = $DB->get_records('tag')) {
820         return;
821     }
823     $tag_correlation_obj = new object();
824     foreach($all_tags as $tag) {
826         // query that counts how many times any tag appears together in items
827         // with the tag passed as argument ($tag_id)
828         $query = "SELECT tb.tagid
829                     FROM {tag_instance} ta JOIN {tag_instance} tb ON ta.itemid = tb.itemid
830                    WHERE ta.tagid = ? AND tb.tagid <> ?
831                 GROUP BY tb.tagid
832                   HAVING COUNT(*) > ?
833                 ORDER BY COUNT(*) DESC";
834         $params = array($tag->id, $tag->id, $min_correlation);
836         $correlated = array();
838         // Correlated tags happen when they appear together in more occasions
839         // than $min_correlation.
840         if ($tag_correlations = $DB->get_records_sql($query, $params)) {
841             foreach($tag_correlations as $correlation) {
842             // commented out - now done in query. kept here in case it breaks on some db
843             // if($correlation->nr >= $min_correlation){
844                     $correlated[] = $correlation->tagid;
845             // }
846             }
847         }
849         if (empty($correlated)) {
850             continue;
851         }
853         $correlated = implode(',', $correlated);
854         //var_dump($correlated);
856         //saves correlation info in the caching table
857         if ($tag_correlation_obj = $DB->get_record('tag_correlation', array('tagid'=>$tag->id), 'tagid')) {
858             $tag_correlation_obj->correlatedtags = $correlated;
859             $DB->update_record('tag_correlation', $tag_correlation_obj);
860         } else {
861             $tag_correlation_obj->tagid          = $tag->id;
862             $tag_correlation_obj->correlatedtags = $correlated;
863             $DB->insert_record('tag_correlation', $tag_correlation_obj);
864         }
865     }
868 /**
869  * Tasks that should be performed at cron time
870  */
871 function tag_cron() {
872     tag_compute_correlations();
873     tag_cleanup();
876 /**
877  * Search for tags with names that match some text
878  *
879  * @param string $text escaped string that the tag names will be matched against
880  * @param boolean $ordered If true, tags are ordered by their popularity. If false, no ordering.
881  * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
882  * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
883  * @return mixed an array of objects, or false if no records were found or an error occured.
884  */
885 function tag_find_tags($text, $ordered=true, $limitfrom='', $limitnum='') {
886     global $DB;
888     $text = array_shift(tag_normalize($text, TAG_CASE_LOWER));
890     if ($ordered) {
891         $query = "SELECT tg.id, tg.name, tg.rawname, COUNT(ti.id) AS count
892                     FROM {tag} tg LEFT JOIN {tag_instance} ti ON tg.id = ti.tagid
893                    WHERE tg.name LIKE ?
894                 GROUP BY tg.id, tg.name, tg.rawname
895                 ORDER BY count DESC";
896     } else {
897         $query = "SELECT tg.id, tg.name, tg.rawname
898                     FROM {tag} tg
899                    WHERE tg.name LIKE ?";
900     }
901     $params = array("%{$text}%");
902     return $DB->get_records_sql($query, $params, $limitfrom , $limitnum);
905 /**
906  * Get the name of a tag
907  *
908  * @param mixed $tagids the id of the tag, or an array of ids
909  * @return mixed string name of one tag, or id-indexed array of strings
910  */
911 function tag_get_name($tagids) {
912     global $DB;
914     if (!is_array($tagids)) {
915         if ($tag = $DB->get_record('tag', array('id'=>$tagids))) {
916             return $tag->name;
917         }
918         return false;
919     }
921     $tag_names = array();
922     foreach($DB->get_records_list('tag', 'id', $tagids) as $tag) {
923         $tag_names[$tag->id] = $tag->name;
924     }
926     return $tag_names;
929 /**
930  * Returns the correlated tags of a tag, retrieved from the tag_correlation
931  * table.  Make sure cron runs, otherwise the table will be empty and this
932  * function won't return anything.
933  *
934  * @param int $tag_id is a single tag id
935  * @return array an array of tag objects, empty if no correlated tags are found
936  */
937 function tag_get_correlated($tag_id, $limitnum=null) {
938     global $DB;
940     $tag_correlation = $DB->get_record('tag_correlation', array('tagid'=>$tag_id));
942     if (!$tag_correlation || empty($tag_correlation->correlatedtags)) {
943         return array();
944     }
946     // this is (and has to) return the same fields as the query in tag_get_tags
947     if ( !$result = $DB->get_records_sql("SELECT tg.id, tg.tagtype, tg.name, tg.rawname, tg.flag, ti.ordering
948                                             FROM {tag} tg INNER JOIN {tag_instance} ti ON tg.id = ti.tagid
949                                            WHERE tg.id IN ({$tag_correlation->correlatedtags})") ) {
950         return array();
951     }
953     return $result;
956 /**
957  * Function that normalizes a list of tag names.
958  *
959  * @param mixed $tags array of tags, or a single tag.
960  * @param int $case case to use for returned value (default: lower case).
961  *     Either TAG_CASE_LOWER (default) or TAG_CASE_ORIGINAL
962  * @return array of lowercased normalized tags, indexed by the normalized tag,
963  *     in the same order as the original array. (Eg: 'Banana' => 'banana').
964  */
965 function tag_normalize($rawtags, $case = TAG_CASE_LOWER) {
967     // cache normalized tags, to prevent costly repeated calls to clean_param
968     static $cleaned_tags_lc = array(); // lower case - use for comparison
969     static $cleaned_tags_mc = array(); // mixed case - use for saving to database
971     if ( !is_array($rawtags) ) {
972         $rawtags = array($rawtags);
973     }
975     $result = array();
976     foreach($rawtags as $rawtag) {
977         $rawtag = trim($rawtag);
978         if (!$rawtag) {
979             continue;
980         }
981         if ( !array_key_exists($rawtag, $cleaned_tags_lc) ) {
982             $cleaned_tags_lc[$rawtag] = moodle_strtolower( clean_param($rawtag, PARAM_TAG) );
983             $cleaned_tags_mc[$rawtag] = clean_param($rawtag, PARAM_TAG);
984         }
985         if ( $case == TAG_CASE_LOWER ) {
986             $result[$rawtag] = $cleaned_tags_lc[$rawtag];
987         } else { // TAG_CASE_ORIGINAL
988             $result[$rawtag] = $cleaned_tags_mc[$rawtag];
989         }
990     }
992     return $result;
995 /**
996  * Count how many records are tagged with a specific tag,
997  *
998  * @param string $record record to look for ('post', 'user', etc.)
999  * @param int $tag is a single tag id
1000  * @return int number of mathing tags.
1001  */
1002 function tag_record_count($record_type, $tagid) {
1003     global $DB;
1004     return $DB->count_records('tag_instance', array('itemtype'=>$record_type, 'tagid'=>$tagid));
1007 /**
1008  * Determine if a record is tagged with a specific tag
1009  *
1010  * @param string $record_type the record type to look for
1011  * @param int $record_id the record id to look for
1012  * @param string $tag a tag name
1013  * @return bool true if it is tagged, false otherwise
1014  */
1015 function tag_record_tagged_with($record_type, $record_id, $tag) {
1016     global $DB;
1017     if ($tagid = tag_get_id($tag)) {
1018         return $DB->count_records('tag_instance', array('itemtype'=>$record_type, 'itemid'=>$record_id, 'tagid'=>$tagid));
1019     } else {
1020         return 0; // tag doesn't exist
1021     }
1024 /**
1025  * Flag a tag as inapropriate
1026  *
1027  * @param mixed $tagids one (int) tagid, or an array of tagids
1028  * @return void
1029  */
1030 function tag_set_flag($tagids) {
1031     global $DB;
1033     $tagids = (array)$tagids;
1034     foreach ($tagids as $tagid) {
1035         $tag = $DB->get_record('tag', array('id'=>$tagid), 'id, flag');
1036         $tag->flag++;
1037         $tag->timemodified = time();
1038         $DB->update_record('tag', $tag);
1039     }
1042 /**
1043  * Remove the inapropriate flag on a tag
1044  *
1045  * @param mixed $tagids one (int) tagid, or an array of tagids
1046  * @return bool true if function succeeds, false otherwise
1047  */
1048 function tag_unset_flag($tagids) {
1049     global $DB;
1051     if ( is_array($tagids) ) {
1052         $tagids = implode(',', $tagids);
1053     }
1054     $timemodified = time();
1055     return $DB->execute("UPDATE {tag} SET flag = 0, timemodified = ? WHERE id IN ($tagids)", array($timemodified));