MDL-15310: moving capability checks out of the library + code formatting adjustments
[moodle.git] / tag / lib.php
1 <?php // $Id$
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  * @version: $Id$
32  * @licence http://www.gnu.org/copyleft/gpl.html GNU Public License
33  * @package moodlecore
34  * @subpackage tag
35  * @see http://www.php.net/manual/en/function.urlencode.php
36  */
38 define('TAG_RETURN_ARRAY', 0);
39 define('TAG_RETURN_OBJECT', 1);
40 define('TAG_RETURN_TEXT', 2);
41 define('TAG_RETURN_HTML', 3);
43 define('TAG_CASE_LOWER', 0);
44 define('TAG_CASE_ORIGINAL', 1);
46 define('TAG_RELATED_ALL', 0);
47 define('TAG_RELATED_MANUAL', 1);
48 define('TAG_RELATED_CORRELATED', 2);
50 ///////////////////////////////////////////////////////
51 /////////////////// PUBLIC TAG API ////////////////////
53 /// Functions for settings tags  //////////////////////
55 /**
56  * Set the tags assigned to a record.  This overwrites the current tags.
57  *
58  * This function is meant to be fed the string coming up from the user
59  * interface, which contains all tags assigned to a record.
60  *
61  * @param string $record_type the type of record to tag ('post' for blogs,
62  *     'user' for users, 'tag' for tags, etc.
63  * @param int $record_id the id of the record to tag
64  * @param array $tags the array of tags to set on the record. If
65  *     given an empty array, all tags will be removed.
66  * @return void
67  */
68 function tag_set($record_type, $record_id, $tags) {
70     static $in_recursion_semaphore = false; // this is to prevent loops when tagging a tag
71     if ( $record_type == 'tag' && !$in_recursion_semaphore) {
72         $current_tagged_tag_name = tag_get_name($record_id);
73     }
75     $tags_ids = tag_get_id($tags, TAG_RETURN_ARRAY); // force an array, even if we only have one tag.
76     $cleaned_tags = tag_normalize($tags);
77     //echo 'tags-in-tag_set'; var_dump($tags); var_dump($tags_ids); var_dump($cleaned_tags);
79     $current_ids = tag_get_tags_ids($record_type, $record_id);
80     //var_dump($current_ids);
82     // for data coherence reasons, it's better to remove deleted tags
83     // before adding new data: ordering could be duplicated.
84     foreach($current_ids as $current_id) {
85         if (!in_array($current_id, $tags_ids)) {
86             tag_delete_instance($record_type, $record_id, $current_id);
87             if ( $record_type == 'tag' && !$in_recursion_semaphore) {
88                 // if we are removing a tag-on-a-tag (manually related tag),
89                 // we need to remove the opposite relationship as well.
90                 tag_delete_instance('tag', $current_id, $record_id);
91             }
92         }
93     }
95     foreach($tags as $ordering => $tag) {
96         $tag = trim($tag);
97         if (!$tag) {
98             continue;
99         }
101         $clean_tag = $cleaned_tags[$tag];
102         $tag_current_id = $tags_ids[$clean_tag];
104         if ( is_null($tag_current_id) ) {
105             // create new tags
106             //echo "call to add tag $tag\n";
107             $new_tag = tag_add($tag);
108             $tag_current_id = $new_tag[$clean_tag];
109         }
111         tag_assign($record_type, $record_id, $tag_current_id, $ordering);
113         // if we are tagging a tag (adding a manually-assigned related tag), we
114         // need to create the opposite relationship as well.
115         if ( $record_type == 'tag' && !$in_recursion_semaphore) {
116             $in_recursion_semaphore = true;
117             tag_set_add('tag', $tag_current_id, $current_tagged_tag_name);
118             $in_recursion_semaphore = false;
119         }
120     }
123 /**
124  * Adds a tag to a record, without overwriting the current tags.
125  *
126  * @param string $record_type the type of record to tag ('post' for blogs,
127  *     'user' for users, etc.
128  * @param int $record_id the id of the record to tag
129  * @param string $tag the tag to add
130  * @return void
131  */
132 function tag_set_add($record_type, $record_id, $tag) {
134     $new_tags = array();
135     foreach( tag_get_tags($record_type, $record_id) as $current_tag ) {
136         $new_tags[] = $current_tag->rawname;
137     }
138     $new_tags[] = $tag;
140     return tag_set($record_type, $record_id, $new_tags);
143 /**
144  * Removes a tag from a record, without overwriting other current tags.
145  *
146  * @param string $record_type the type of record to tag ('post' for blogs,
147  *     'user' for users, etc.
148  * @param int $record_id the id of the record to tag
149  * @param string $tag the tag to delete
150  * @return void
151  */
152 function tag_set_delete($record_type, $record_id, $tag) {
154     $new_tags = array();
155     foreach( tag_get_tags($record_type, $record_id) as $current_tag ) {
156         if ($current_tag->name != $tag) {  // Keep all tags but the one specified
157             $new_tags[] = $current_tag->name;
158         }
159     }
161     return tag_set($record_type, $record_id, $new_tags);
164 /**
165  * Set the type of a tag.  At this time (version 1.9) the possible values
166  * are 'default' or 'official'.  Official tags will be displayed separately "at
167  * tagging time" (while selecting the tags to apply to a record).
168  *
169  * @param string $tagid tagid to modify
170  * @param string $type either 'default' or 'official'
171  * @return true on success, false otherwise
172  */
173 function tag_type_set($tagid, $type) {
174     global $DB;
176     if ($tag = $DB->get_record('tag', array('id'=>$tagid), 'id')) {
177         $tag->tagtype = $type;
178         $tag->timemodified = time();
179         return $DB->update_record('tag', $tag);
180     }
181     return false;
185 /**
186  * Set the description of a tag
187  *
188  * @param int $tagid the id of the tag
189  * @param string $description the description
190  * @param int $descriptionformat the moodle text format of the description
191  * @return true on success, false otherwise
192  */
193 function tag_description_set($tagid, $description, $descriptionformat) {
194     global $DB;
196     if ($tag = $DB->get_record('tag', array('id'=>$tagid),'id')) {
197         $tag->description = $description;
198         $tag->descriptionformat = $descriptionformat;
199         $tag->timemodified = time();
200         return $DB->update_record('tag', $tag);
201     }
202     return false;
210 /// Functions for getting information about tags //////
212 /**
213  * Simple function to just return a single tag object when you know the name or something
214  *
215  * @param string $field which field do we use to identify the tag: id, name or rawname
216  * @param string $value the required value of the aforementioned field
217  * @param string $returnfields which fields do we want returned?
218  * @return tag object
219  *
220  **/
221 function tag_get($field, $value, $returnfields='id, name, rawname') {
222     global $DB;
224     if ($field == 'name') {
225         $value = moodle_strtolower($value);   // To cope with input that might just be wrong case
226     }
227     return $DB->get_record('tag', array($field=>$value), $returnfields);
231 /**
232  * Get the array of db record of tags associated to a record (instances).  Use
233  * tag_get_tags_csv to get the same information in a comma-separated string.
234  *
235  * @param string $record_type the record type for which we want to get the tags
236  * @param int $record_id the record id for which we want to get the tags
237  * @param string $type the tag type (either 'default' or 'official'). By default,
238  *     all tags are returned.
239  * @return array the array of tags
240  */
241 function tag_get_tags($record_type, $record_id, $type=null) {
242     global $CFG, $DB;
244     $params = array();
246     if ($type) {
247         $sql_type = "AND tg.tagtype = :type";
248         $params['type'] = $type;
249     } else {
250         $sql_type = '';
251     }
253     $sql = "SELECT tg.id, tg.tagtype, tg.name, tg.rawname, tg.flag, ti.ordering
254               FROM {tag_instance} ti JOIN {tag} tg ON tg.id = ti.tagid
255               WHERE ti.itemtype = :recordtype AND ti.itemid = :recordid $sql_type
256            ORDER BY ti.ordering ASC";
257     $params['recordtype'] = $record_type;
258     $params['recordid']   = $record_id;
260     // if the fields in this query are changed, you need to do the same changes in tag_get_correlated_tags
261     return $DB->get_records_sql($sql, $params);
262     // This version of the query, reversing the ON clause, "correctly" returns
263     // a row with NULL values for instances that are still in the DB even though
264     // the tag has been deleted.  This shouldn't happen, but if it did, using
265     // this query could help "clean it up".  This causes bugs at this time.
266     //$tags = $DB->get_records_sql("SELECT ti.tagid, tg.tagtype, tg.name, tg.rawname, tg.flag, ti.ordering ".
267     //    "FROM {tag_instance} ti LEFT JOIN {tag} tg ON ti.tagid = tg.id ".
268     //    "WHERE ti.itemtype = '{$record_type}' AND ti.itemid = '{$record_id}' {$type} ".
269     //    "ORDER BY ti.ordering ASC");
272 /**
273  * Get the array of tags display names, indexed by id.
274  *
275  * @param string $record_type the record type for which we want to get the tags
276  * @param int $record_id the record id for which we want to get the tags
277  * @param string $type the tag type (either 'default' or 'official'). By default,
278  *     all tags are returned.
279  * @return array the array of tags (with the value returned by tag_display_name), indexed by id
280  */
281 function tag_get_tags_array($record_type, $record_id, $type=null) {
282     $tags = array();
283     foreach(tag_get_tags($record_type, $record_id, $type) as $tag) {
284         $tags[$tag->id] = tag_display_name($tag);
285     }
286     return $tags;
289 /**
290  * Get a comma-separated string of tags associated to a record.  Use tag_get_tags
291  * to get the same information in an array.
292  *
293  * @param string $record_type the record type for which we want to get the tags
294  * @param int $record_id the record id for which we want to get the tags
295  * @param int $html either TAG_RETURN_HTML or TAG_RETURN_TEXT, depending
296  *     on the type of output desired
297  * @param string $type either 'official' or 'default', if null, all tags are
298  *     returned
299  * @return string the comma-separated list of tags.
300  */
301 function tag_get_tags_csv($record_type, $record_id, $html=TAG_RETURN_HTML, $type=null) {
302     global $CFG;
304     $tags_names = array();
305     foreach(tag_get_tags($record_type, $record_id, $type) as $tag) {
306         if ($html == TAG_RETURN_TEXT) {
307             $tags_names[] = tag_display_name($tag);
308         } else { // TAG_RETURN_HTML
309             $tags_names[] = '<a href="'. $CFG->wwwroot .'/tag/index.php?tag='. rawurlencode($tag->name) .'">'. tag_display_name($tag) .'</a>';
310         }
311     }
312     return implode(', ', $tags_names);
315 /**
316  * Get an array of tag ids associated to a record.
317  *
318  * @param string $record_type the record type for which we want to get the tags
319  * @param int $record_id the record id for which we want to get the tags
320  * @return array of tag ids, indexed and sorted by 'ordering'
321  */
322 function tag_get_tags_ids($record_type, $record_id) {
324     $tag_ids = array();
325     foreach (tag_get_tags($record_type, $record_id) as $tag) {
326         if ( array_key_exists($tag->ordering, $tag_ids) ) {
327             // until we can add a unique constraint, in table tag_instance,
328             // on (itemtype, itemid, ordering), this is needed to prevent a bug
329             // TODO : modify database in 2.0
330             $tag->ordering++;
331         }
332         $tag_ids[$tag->ordering] = $tag->id;
333     }
334     ksort($tag_ids);
335     return $tag_ids;
338 /**
339  * Returns the database ID of a set of tags.
340  *
341  * @param mixed $tags one tag, or array of tags, to look for.
342  * @param bool $return_value specify the type of the returned value. Either
343  *     TAG_RETURN_OBJECT, or TAG_RETURN_ARRAY (default). If TAG_RETURN_ARRAY
344  *     is specified, an array will be returned even if only one tag was
345  *     passed in $tags.
346  * @return mixed tag-indexed array of ids (or objects, if second parameter is
347  *     TAG_RETURN_OBJECT), or only an int, if only one tag is given *and* the
348  *     second parameter is null. No value for a key means the tag wasn't found.
349  */
350 function tag_get_id($tags, $return_value=null) {
351     global $CFG, $DB;
353     static $tag_id_cache = array();
355     $return_an_int = false;
356     if (!is_array($tags)) {
357         if(is_null($return_value) || $return_value == TAG_RETURN_OBJECT) {
358             $return_an_int = true;
359         }
360         $tags = array($tags);
361     }
363     $result = array();
365     //TODO: test this and see if it helps performance without breaking anything
366     //foreach($tags as $key => $tag) {
367     //    $clean_tag = moodle_strtolower($tag);
368     //    if ( array_key_exists($clean_tag), $tag_id_cache) ) {
369     //        $result[$clean_tag] = $tag_id_cache[$clean_tag];
370     //        $tags[$key] = ''; // prevent further processing for this one.
371     //    }
372     //}
374     $tags = array_values(tag_normalize($tags));
375     foreach($tags as $key => $tag) {
376         $tags[$key] = moodle_strtolower($tag);
377         $result[moodle_strtolower($tag)] = null; // key must exists : no value for a key means the tag wasn't found.
378     }
380     if (empty($tags)) {
381         return array();
382     }
384     list($tag_string, $params) = $DB->get_in_or_equal($tags);
386     if ($rs = $DB->get_recordset_sql("SELECT * FROM {tag} WHERE name $tag_string ORDER BY name", $params)) {
387         foreach ($rs as $record) {
388             if ($return_value == TAG_RETURN_OBJECT) {
389                 $result[$record->name] = $record;
390             } else { // TAG_RETURN_ARRAY
391                 $result[$record->name] = $record->id;
392             }
393         }
394         $rs->close();
395     }
397     if ($return_an_int) {
398         return array_pop($result);
399     }
401     return $result;
405 /**
406  * Returns tags related to a tag
407  *
408  * Related tags of a tag come from two sources:
409  *   - manually added related tags, which are tag_instance entries for that tag
410  *   - correlated tags, which are a calculated
411  *
412  * @param string $tag_name_or_id is a single **normalized** tag name or the id
413  *     of a tag
414  * @param int $type the function will return either manually
415  *     (TAG_RELATED_MANUAL) related tags or correlated (TAG_RELATED_CORRELATED)
416  *     tags. Default is TAG_RELATED_ALL, which returns everything.
417  * @param int $limitnum return a subset comprising this many records (optional,
418  *     default is 10)
419  * @return array an array of tag objects
420  */
421 function tag_get_related_tags($tagid, $type=TAG_RELATED_ALL, $limitnum=10) {
423     $related_tags = array();
425     if ( $type == TAG_RELATED_ALL || $type == TAG_RELATED_MANUAL) {
426         //gets the manually added related tags
427         $related_tags = tag_get_tags('tag', $tagid);
428     }
430     if ( $type == TAG_RELATED_ALL || $type == TAG_RELATED_CORRELATED ) {
431         //gets the correlated tags
432         $automatic_related_tags = tag_get_correlated($tagid, $limitnum);
433         if (is_array($automatic_related_tags)) {
434             $related_tags = array_merge($related_tags, $automatic_related_tags);
435         }
436     }
438     return array_slice(object_array_unique($related_tags), 0 , $limitnum);
441 /**
442  * Get a comma-separated list of tags related to another tag.
443  *
444  * @param array $related_tags the array returned by tag_get_related_tags
445  * @param int $html either TAG_RETURN_HTML (default) or TAG_RETURN_TEXT : return html links, or just text.
446  * @return string comma-separated list
447  */
448 function tag_get_related_tags_csv($related_tags, $html=TAG_RETURN_HTML) {
449     global $CFG;
451     $tags_names = array();
452     foreach($related_tags as $tag) {
453         if ( $html == TAG_RETURN_TEXT) {
454             $tags_names[] = tag_display_name($tag);
455         } else {
456             // TAG_RETURN_HTML
457             $tags_names[] = '<a href="'. $CFG->wwwroot .'/tag/index.php?tag='. rawurlencode($tag->name) .'">'. tag_display_name($tag) .'</a>';
458         }
459     }
461     return implode(', ', $tags_names);
464 /**
465  * Change the "value" of a tag, and update the associated 'name'.
466  *
467  * @param int $tagid the id of the tag to modify
468  * @param string $newtag the new rawname
469  * @return bool true on success, false otherwise
470  */
471 function tag_rename($tagid, $newrawname) {
472     global $DB;
474     if (! $newrawname_clean = array_shift(tag_normalize($newrawname, TAG_CASE_ORIGINAL)) ) {
475         return false;
476     }
478     if (! $newname_clean = moodle_strtolower($newrawname_clean)) {
479         return false;
480     }
482     // Prevent the rename if a tag with that name already exists
483     if ($existing = tag_get('name', $newname_clean, 'id, name, rawname')) {
484         if ($existing->id != $tagid) {  // Another tag already exists with this name
485             return false;
486         }
487     }
489     if ($tag = tag_get('id', $tagid, 'id, name, rawname')) {
490         $tag->rawname      = $newrawname_clean;
491         $tag->name         = $newname_clean;
492         $tag->timemodified = time();
493         return $DB->update_record('tag', $tag);
494     }
495     return false;
499 /**
500  * Delete one or more tag, and all their instances if there are any left.
501  *
502  * @param mixed $tagids one tagid (int), or one array of tagids to delete
503  * @return bool true on success, false otherwise
504  */
505 function tag_delete($tagids) {
506     global $DB;
508     if (!is_array($tagids)) {
509         $tagids = array($tagids);
510     }
512     $success = true;
513     foreach( $tagids as $tagid ) {
514         if (is_null($tagid)) { // can happen if tag doesn't exists
515             continue;
516         }
517         // only delete the main entry if there were no problems deleting all the
518         // instances - that (and the fact we won't often delete lots of tags)
519         // is the reason for not using $DB->delete_records_select()
520         if ($DB->delete_records('tag_instance', array('tagid'=>$tagid)) ) {
521             $success &= (bool) $DB->delete_records('tag', array('id'=>$tagid));
522         }
523     }
525     return $success;
528 /**
529  * Delete one instance of a tag.  If the last instance was deleted, it will
530  * also delete the tag, unless it's type is 'official'.
531  *
532  * @param string $record_type the type of the record for which to remove the instance
533  * @param int $record_id the id of the record for which to remove the instance
534  * @param int $tagid the tagid that needs to be removed
535  * @return bool true on success, false otherwise
536  */
537 function tag_delete_instance($record_type, $record_id, $tagid) {
538     global $CFG, $DB;
540     if ($DB->delete_records('tag_instance', array('tagid'=>$tagid, 'itemtype'=>$record_type, 'itemid'=>$record_id))) {
541         if (!$DB->record_exists_sql("SELECT *
542                                        FROM {tag} tg, {tag_instance} ti
543                                       WHERE (tg.id = ti.tagid AND ti.tagid = ? )
544                                             OR (tg.id = ? AND tg.tagtype = 'official')",
545                                      array($tagid, $tagid)) ) {
546             return tag_delete($tagid);
547         }
548     } else {
549         return false;
550     }
552     return true;
556 /**
557  * Function that returns the name that should be displayed for a specific tag
558  *
559  * @param object $tag_object a line out of tag table, as returned by the adobd functions
560  * @return string
561  */
562 function tag_display_name($tag_object) {
564     global $CFG;
566     if(!isset($tag_object->name)) {
567         return '';
568     }
570     if (empty($CFG->keeptagnamecase)) {
571         //this is the normalized tag name
572         $textlib = textlib_get_instance();
573         return htmlspecialchars($textlib->strtotitle($tag_object->name));
574     } else {
575         //original casing of the tag name
576         return htmlspecialchars($tag_object->rawname);
577     }
580 /**
581  * Find all records tagged with a tag of a given type ('post', 'user', etc.)
582  *
583  * @param string $tag tag to look for
584  * @param string $type type to restrict search to.  If null, every matching
585  *     record will be returned
586  * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
587  * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
588  * @return array of matching objects, indexed by record id, from the table containing the type requested
589  */
590 function tag_find_records($tag, $type, $limitfrom='', $limitnum='') {
591     global $CFG, $DB;
593     if (!$tag || !$type) {
594         return array();
595     }
597     $tagid = tag_get_id($tag);
599     $query = "SELECT it.*
600                 FROM {".$type."} it INNER JOIN {tag_instance} tt ON it.id = tt.itemid
601                WHERE tt.itemtype = ? AND tt.tagid = ?";
602     $params = array($type, $tagid);
604     return $DB->get_records_sql($query, $params, $limitfrom, $limitnum);
610 ///////////////////////////////////////////////////////
611 /////////////////// PRIVATE TAG API ///////////////////
613 /**
614  * Adds one or more tag in the database.  This function should not be called
615  * directly : you should use tag_set.
616  *
617  * @param mixed $tags one tag, or an array of tags, to be created
618  * @param string $type type of tag to be created ("default" is the default
619  *     value and "official" is the only other supported value at this time). An
620  *     official tag is kept even if there are no records tagged with it.
621  * @return an array of tags ids, indexed by their lowercase normalized names.
622  *     Any boolean false in the array indicates an error while adding the tag.
623  */
624 function tag_add($tags, $type="default") {
625     global $USER, $DB;
627     if (!is_array($tags)) {
628         $tags = array($tags);
629     }
631     $tag_object = new StdClass;
632     $tag_object->tagtype      = $type;
633     $tag_object->userid       = $USER->id;
634     $tag_object->timemodified = time();
636     $clean_tags = tag_normalize($tags, TAG_CASE_ORIGINAL);
638     $tags_ids = array();
639     foreach($clean_tags as $tag) {
640         $tag = trim($tag);
641         if (!$tag) {
642             $tags_ids[$tag] = false;
643         } else {
644             // note that the difference between rawname and name is only
645             // capitalization : the rawname is NOT the same at the rawtag.
646             $tag_object->rawname = $tag;
647             $tag_name_lc         = moodle_strtolower($tag);
648             $tag_object->name    = $tag_name_lc;
649             //var_dump($tag_object);
650             $tags_ids[$tag_name_lc] = $DB->insert_record('tag', $tag_object);
651         }
652     }
654     return $tags_ids;
657 /**
658  * Assigns a tag to a record: if the record already exists, the time and
659  * ordering will be updated.
660  *
661  * @param string $record_type the type of the record that will be tagged
662  * @param int $record_id the id of the record that will be tagged
663  * @param string $tagid the tag id to set on the record.
664  * @param int $ordering the order of the instance for this record
665  * @return bool true on success, false otherwise
666  */
667 function tag_assign($record_type, $record_id, $tagid, $ordering) {
668     global $DB;
670     if ( $tag_instance_object = $DB->get_record('tag_instance', array('tagid'=>$tagid, 'itemtype'=>$record_type, 'itemid'=>$record_id), 'id')) {
671         $tag_instance_object->ordering     = $ordering;
672         $tag_instance_object->timemodified = time();
673         return $DB->update_record('tag_instance', $tag_instance_object);
674     } else {
675         $tag_instance_object = new StdClass;
676         $tag_instance_object->tagid        = $tagid;
677         $tag_instance_object->itemid       = $record_id;
678         $tag_instance_object->itemtype     = $record_type;
679         $tag_instance_object->ordering     = $ordering;
680         $tag_instance_object->timemodified = time();
681         return $DB->insert_record('tag_instance', $tag_instance_object);
682     }
685 /**
686  * Function that returns tags that start with some text, for use by the autocomplete feature
687  *
688  * @param string $text string that the tag names will be matched against
689  * @return mixed an array of objects, or false if no records were found or an error occured.
690  */
691 function tag_autocomplete($text) {
692     global $DB;
693     return $DB->get_records_sql("SELECT tg.id, tg.name, tg.rawname
694                                    FROM {tag} tg
695                                   WHERE tg.name LIKE ?", array(moodle_strtolower($text)."%"));
698 /**
699  * Clean up the tag tables, making sure all tagged object still exists.
700  *
701  * This should normally not be necessary, but in case related tags are not deleted
702  * when the tagged record is removed, this should be done once in a while, perhaps on
703  * an occasional cron run.  On a site with lots of tags, this could become an expensive
704  * function to call: don't run at peak time.
705  */
706 function tag_cleanup() {
707     global $DB;
709     $instances = $DB->get_recordset('tag_instance');
711     // cleanup tag instances
712     foreach ($instances as $instance) {
713         $delete = false;
715         if (!$DB->record_exists('tag', array('id'=>$instance->tagid))) {
716             // if the tag has been removed, instance should be deleted.
717             $delete = true;
718         } else {
719             switch ($instance->itemtype) {
720                 case 'user': // users are marked as deleted, but not actually deleted
721                     if ($DB->record_exists('user', array('id'=>$instance->itemid, 'deleted'=>1))) {
722                         $delete = true;
723                     }
724                     break;
725                 default: // anything else, if the instance is not there, delete.
726                     if (!$DB->record_exists($instance->itemtype, array('id'=>$instance->itemid))) {
727                         $delete = true;
728                     }
729                     break;
730             }
731         }
732         if ($delete) {
733             tag_delete_instance($instance->itemtype, $instance->itemid, $instance->tagid);
734             //debugging('deleting tag_instance #'. $instance->id .', linked to tag id #'. $instance->tagid, DEBUG_DEVELOPER);
735         }
736     }
737     $instances->close();
739     // TODO: this will only clean tags of type 'default'.  This is good as
740     // it won't delete 'official' tags, but the day we get more than two
741     // types, we need to fix this.
742     $unused_tags = $DB->get_recordset_sql("SELECT tg.id
743                                              FROM {tag} tg
744                                             WHERE tg.tagtype = 'default'
745                                                   AND NOT EXISTS (
746                                                       SELECT 'x'
747                                                         FROM {tag_instance} ti
748                                                        WHERE ti.tagid = tg.id
749                                                   )");
751     // cleanup tags
752     foreach ($unused_tags as $unused_tag) {
753         tag_delete($unused_tag->id);
754         //debugging('deleting unused tag #'. $unused_tag->id,  DEBUG_DEVELOPER);
755     }
756     $unused_tags->close();
759 /**
760  * Calculates and stores the correlated tags of all tags.
761  * The correlations are stored in the 'tag_correlation' table.
762  *
763  * Two tags are correlated if they appear together a lot.
764  * Ex.: Users tagged with "computers" will probably also be tagged with "algorithms".
765  *
766  * The rationale for the 'tag_correlation' table is performance.
767  * It works as a cache for a potentially heavy load query done at the 'tag_instance' table.
768  * So, the 'tag_correlation' table stores redundant information derived from the 'tag_instance' table.
769  *
770  * @param number $min_correlation cutoff percentage (optional, default is 2)
771  */
772 function tag_compute_correlations($min_correlation=2) {
773     global $DB;
775     if (!$all_tags = $DB->get_records('tag')) {
776         return;
777     }
779     $tag_correlation_obj = new object();
780     foreach($all_tags as $tag) {
782         // query that counts how many times any tag appears together in items
783         // with the tag passed as argument ($tag_id)
784         $query = "SELECT tb.tagid , COUNT(*) AS nr
785                     FROM {tag_instance} ta JOIN {tag_instance} tb ON ta.itemid = tb.itemid
786                    WHERE ta.tagid = ? AND tb.tagid <> ?
787                 GROUP BY tb.tagid
788                   HAVING nr > ?
789                 ORDER BY nr DESC";
790         $params = array($tag->id, $tag->id, $min_correlation);
792         $correlated = array();
794         // Correlated tags happen when they appear together in more occasions
795         // than $min_correlation.
796         if ($tag_correlations = $DB->get_records_sql($query, $params)) {
797             foreach($tag_correlations as $correlation) {
798             // commented out - now done in query. kept here in case it breaks on some db
799             // if($correlation->nr >= $min_correlation){
800                     $correlated[] = $correlation->tagid;
801             // }
802             }
803         }
805         if (empty($correlated)) {
806             continue;
807         }
809         $correlated = implode(',', $correlated);
810         //var_dump($correlated);
812         //saves correlation info in the caching table
813         if ($tag_correlation_obj = $DB->get_record('tag_correlation', array('tagid'=>$tag->id), 'tagid')) {
814             $tag_correlation_obj->correlatedtags = $correlated;
815             $DB->update_record('tag_correlation', $tag_correlation_obj);
816         } else {
817             $tag_correlation_obj->tagid          = $tag->id;
818             $tag_correlation_obj->correlatedtags = $correlated;
819             $DB->insert_record('tag_correlation', $tag_correlation_obj);
820         }
821     }
824 /**
825  * Tasks that should be performed at cron time
826  */
827 function tag_cron() {
828     tag_compute_correlations();
829     tag_cleanup();
832 /**
833  * Search for tags with names that match some text
834  *
835  * @param string $text escaped string that the tag names will be matched against
836  * @param boolean $ordered If true, tags are ordered by their popularity. If false, no ordering.
837  * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
838  * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
839  * @return mixed an array of objects, or false if no records were found or an error occured.
840  */
841 function tag_find_tags($text, $ordered=true, $limitfrom='', $limitnum='') {
842     global $DB;
844     $text = array_shift(tag_normalize($text, TAG_CASE_LOWER));
846     if ($ordered) {
847         $query = "SELECT tg.id, tg.name, tg.rawname, COUNT(ti.id) AS count
848                     FROM {tag} tg LEFT JOIN {tag_instance} ti ON tg.id = ti.tagid
849                    WHERE tg.name LIKE ?
850                 GROUP BY tg.id, tg.name, tg.rawname
851                 ORDER BY count DESC";
852     } else {
853         $query = "SELECT tg.id, tg.name, tg.rawname
854                     FROM {tag} tg
855                    WHERE tg.name LIKE ?";
856     }
857     $params = array("%{$text}%");
858     return $DB->get_records_sql($query, $params, $limitfrom , $limitnum);
861 /**
862  * Get the name of a tag
863  *
864  * @param mixed $tagids the id of the tag, or an array of ids
865  * @return mixed string name of one tag, or id-indexed array of strings
866  */
867 function tag_get_name($tagids) {
868     global $DB;
870     if (!is_array($tagids)) {
871         if ($tag = $DB->get_record('tag', array('id'=>$tagids))) {
872             return $tag->name;
873         }
874         return false;
875     }
877     $tag_names = array();
878     foreach($DB->get_records_list('tag', 'id', $tagids) as $tag) {
879         $tag_names[$tag->id] = $tag->name;
880     }
882     return $tag_names;
885 /**
886  * Returns the correlated tags of a tag, retrieved from the tag_correlation
887  * table.  Make sure cron runs, otherwise the table will be empty and this
888  * function won't return anything.
889  *
890  * @param int $tag_id is a single tag id
891  * @return array an array of tag objects, empty if no correlated tags are found
892  */
893 function tag_get_correlated($tag_id, $limitnum=null) {
894     global $DB;
896     $tag_correlation = $DB->get_record('tag_correlation', array('tagid'=>$tag_id));
898     if (!$tag_correlation || empty($tag_correlation->correlatedtags)) {
899         return array();
900     }
902     // this is (and has to) return the same fields as the query in tag_get_tags
903     if ( !$result = $DB->get_records_sql("SELECT tg.id, tg.tagtype, tg.name, tg.rawname, tg.flag, ti.ordering
904                                             FROM {tag} tg INNER JOIN {tag_instance} ti ON tg.id = ti.tagid
905                                            WHERE tg.id IN ({$tag_correlation->correlatedtags})") ) {
906         return array();
907     }
909     return $result;
912 /**
913  * Function that normalizes a list of tag names.
914  *
915  * @param mixed $tags array of tags, or a single tag.
916  * @param int $case case to use for returned value (default: lower case).
917  *     Either TAG_CASE_LOWER (default) or TAG_CASE_ORIGINAL
918  * @return array of lowercased normalized tags, indexed by the normalized tag,
919  *     in the same order as the original array. (Eg: 'Banana' => 'banana').
920  */
921 function tag_normalize($rawtags, $case = TAG_CASE_LOWER) {
923     // cache normalized tags, to prevent costly repeated calls to clean_param
924     static $cleaned_tags_lc = array(); // lower case - use for comparison
925     static $cleaned_tags_mc = array(); // mixed case - use for saving to database
927     if ( !is_array($rawtags) ) {
928         $rawtags = array($rawtags);
929     }
931     $result = array();
932     foreach($rawtags as $rawtag) {
933         $rawtag = trim($rawtag);
934         if (!$rawtag) {
935             continue;
936         }
937         if ( !array_key_exists($rawtag, $cleaned_tags_lc) ) {
938             $cleaned_tags_lc[$rawtag] = moodle_strtolower( clean_param($rawtag, PARAM_TAG) );
939             $cleaned_tags_mc[$rawtag] = clean_param($rawtag, PARAM_TAG);
940         }
941         if ( $case == TAG_CASE_LOWER ) {
942             $result[$rawtag] = $cleaned_tags_lc[$rawtag];
943         } else { // TAG_CASE_ORIGINAL
944             $result[$rawtag] = $cleaned_tags_mc[$rawtag];
945         }
946     }
948     return $result;
951 /**
952  * Count how many records are tagged with a specific tag,
953  *
954  * @param string $record record to look for ('post', 'user', etc.)
955  * @param int $tag is a single tag id
956  * @return int number of mathing tags.
957  */
958 function tag_record_count($record_type, $tagid) {
959     global $DB;
960     return $DB->count_records('tag_instance', array('itemtype'=>$record_type, 'tagid'=>$tagid));
963 /**
964  * Determine if a record is tagged with a specific tag
965  *
966  * @param string $record_type the record type to look for
967  * @param int $record_id the record id to look for
968  * @param string $tag a tag name
969  * @return bool true if it is tagged, false otherwise
970  */
971 function tag_record_tagged_with($record_type, $record_id, $tag) {
972     global $DB;
973     if ($tagid = tag_get_id($tag)) {
974         return $DB->count_records('tag_instance', array('itemtype'=>$record_type, 'itemid'=>$record_id, 'tagid'=>$tagid));
975     } else {
976         return 0; // tag doesn't exist
977     }
980 /**
981  * Flag a tag as inapropriate
982  *
983  * @param mixed $tagids one (int) tagid, or an array of tagids
984  * @return void
985  */
986 function tag_set_flag($tagids) {
987     global $DB;
989     $tagids = (array)$tagids;
990     foreach ($tagids as $tagid) {
991         $tag = $DB->get_record('tag', array('id'=>$tagid), 'id, flag');
992         $tag->flag++;
993         $tag->timemodified = time();
994         $DB->update_record('tag', $tag);
995     }
998 /**
999  * Remove the inapropriate flag on a tag
1000  *
1001  * @param mixed $tagids one (int) tagid, or an array of tagids
1002  * @return bool true if function succeeds, false otherwise
1003  */
1004 function tag_unset_flag($tagids) {
1005     global $DB;
1007     if ( is_array($tagids) ) {
1008         $tagids = implode(',', $tagids);
1009     }
1010     $timemodified = time();
1011     return $DB->execute("UPDATE {tag} tg SET tg.flag = 0, tg.timemodified = ? WHERE tg.id IN ($tagids)", array($timemodified));
1014 ?>