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