Search moodle.org's
Developer Documentation
Developer Documentation
See Release Notes
Long Term Support Release
- Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
- Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
- PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.
/tag/classes/ -> tag.php (source)
Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401] [Versions 401 and 402] [Versions 401 and 403]
Contains class core_tag_tag
| Copyright: | 2015 Marina Glancy |
| License: | http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later |
| File Size: | 1773 lines (74 kb) |
| Included or required: | 0 times |
| Referenced: | 0 times |
| Includes or requires: | 0 files |
Defines 1 class
core_tag_tag:: (53 methods):
__construct()
__get()
__isset()
to_object()
get_display_name()
make_display_name()
add()
get()
get_bulk()
get_by_name()
guess_by_name()
get_by_name_bulk()
normalize()
create_if_missing()
make_url()
get_view_url()
ensure_fields_exist()
delete_instance_as_record()
delete_instance()
delete_instances_as_record()
delete_instances_by_id()
delete_instances()
add_instance()
update_instance_ordering()
get_items_tags()
get_item_tags()
get_item_tags_array()
set_item_tags()
remove_all_item_tags()
add_item_tag()
remove_item_tag()
move_context()
change_items_context()
change_instances_context()
update()
flag()
reset_flag()
set_related_tags()
add_related_tags()
get_correlated_tags()
get_manual_related_tags()
get_related_tags()
get_tagged_items()
count_tagged_items()
is_item_tagged_with()
is_enabled()
get_tag_index()
get_formatted_description()
get_links()
delete_tags()
combine_correlated_tags()
combine_tags()
get_tags_by_area_in_contexts()
Class: core_tag_tag - X-Ref
Represents one tag and also contains lots of useful tag-related methods as static functions.Tags can be added to any database records.
$itemtype refers to the DB table name
$itemid refers to id field in this DB table
$component is the component that is responsible for the tag instance
$context is the affected context
BASIC INSTRUCTIONS :
- to "tag a blog post" (for example):
core_tag_tag::set_item_tags('post', 'core', $blogpost->id, $context, $arrayoftags);
- to "remove all the tags on a blog post":
core_tag_tag::remove_all_item_tags('post', 'core', $blogpost->id);
set_item_tags() will create tags that do not exist yet.
| __construct($record) X-Ref |
| Constructor. Use functions get(), get_by_name(), etc. param: stdClass $record |
| __get($name) X-Ref |
| Magic getter param: string $name return: mixed |
| __isset($name) X-Ref |
| Magic isset method param: string $name return: bool |
| to_object() X-Ref |
| Converts to object return: stdClass |
| get_display_name($ashtml = true) X-Ref |
| Returns tag name ready to be displayed param: bool $ashtml (default true) if true will return htmlspecialchars encoded string return: string |
| make_display_name($tag, $ashtml = true) X-Ref |
| Prepares tag name ready to be displayed param: stdClass|core_tag_tag $tag record from db table tag, must contain properties name and rawname param: bool $ashtml (default true) if true will return htmlspecialchars encoded string return: string |
| add($tagcollid, $tags, $isstandard = false) X-Ref |
| Adds one or more tag in the database. This function should not be called directly : you should use tag_set. param: int $tagcollid param: string|array $tags one tag, or an array of tags, to be created param: bool $isstandard type of tag to be created. A standard tag is kept even if there are no records tagged with it. return: array tag objects indexed by their lowercase normalized names. Any boolean false in the array |
| get($id, $returnfields = 'id, name, rawname, tagcollid', $strictness = IGNORE_MISSING) X-Ref |
| Simple function to just return a single tag object by its id param: int $id param: string $returnfields which fields do we want returned from table {tag}. param: int $strictness IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found; return: core_tag_tag|false tag object |
| get_bulk($ids, $returnfields = 'id, name, rawname, tagcollid') X-Ref |
| Simple function to just return an array of tag objects by their ids param: int[] $ids param: string $returnfields which fields do we want returned from table {tag}. return: core_tag_tag[] array of retrieved tags |
| get_by_name($tagcollid, $name, $returnfields='id, name, rawname, tagcollid',$strictness = IGNORE_MISSING) X-Ref |
| Simple function to just return a single tag object by tagcollid and name param: int $tagcollid tag collection to use, param: string $name tag name param: string $returnfields which fields do we want returned. This is a comma separated string param: int $strictness IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found; return: core_tag_tag|false tag object |
| guess_by_name($name, $returnfields='id, name, rawname, tagcollid') X-Ref |
| Looking in all tag collections for the tag with the given name param: string $name tag name param: string $returnfields return: array array of core_tag_tag instances |
| get_by_name_bulk($tagcollid, $tags, $returnfields = 'id, name, rawname, tagcollid') X-Ref |
| Returns the list of tag objects by tag collection id and the list of tag names param: int $tagcollid param: array $tags array of tags to look for param: string $returnfields list of DB fields to return, must contain 'id', 'name' and 'rawname' return: array tag-indexed array of objects. No value for a key means the tag wasn't found. |
| normalize($rawtags, $tolowercase = true) X-Ref |
| Function that normalizes a list of tag names. param: array $rawtags array of tags param: bool $tolowercase convert to lower case? return: array lowercased normalized tags, indexed by the normalized tag, in the same order as the original array. |
| create_if_missing($tagcollid, $tags, $isstandard = false) X-Ref |
| Retrieves tags and/or creates them if do not exist yet param: int $tagcollid param: array $tags array of raw tag names, do not have to be normalised param: bool $isstandard create as standard tag (default false) return: core_tag_tag[] array of tag objects indexed with lowercase normalised tag name |
| make_url($tagcollid, $name, $exclusivemode = 0, $fromctx = 0, $ctx = 0, $rec = 1) X-Ref |
| Creates a URL to view a tag param: int $tagcollid param: string $name param: int $exclusivemode param: int $fromctx context id where this tag cloud is displayed param: int $ctx context id for tag view link param: int $rec recursive argument for tag view link return: \moodle_url |
| get_view_url($exclusivemode = 0, $fromctx = 0, $ctx = 0, $rec = 1) X-Ref |
| Returns URL to view the tag param: int $exclusivemode param: int $fromctx context id where this tag cloud is displayed param: int $ctx context id for tag view link param: int $rec recursive argument for tag view link return: \moodle_url |
| ensure_fields_exist($list, $caller) X-Ref |
| Validates that the required fields were retrieved and retrieves them if missing param: array $list array of the fields that need to be validated param: string $caller name of the function that requested it, for the debugging message |
| delete_instance_as_record($taginstance, $fullobject = false) X-Ref |
| Deletes the tag instance given the record from tag_instance DB table param: stdClass $taginstance param: bool $fullobject whether $taginstance contains all fields from DB table tag_instance return: bool |
| delete_instance($component, $itemtype, $itemid, $tiuserid = 0) X-Ref |
| Delete one instance of a tag. If the last instance was deleted, it will also delete the tag, unless it is standard. param: string $component component responsible for tagging. For BC it can be empty but in this case the param: string $itemtype the type of the record for which to remove the instance param: int $itemid the id of the record for which to remove the instance param: int $tiuserid tag instance user id, only needed for tag areas with user tagging (such as core/course) |
| delete_instances_as_record(array $taginstances) X-Ref |
| Bulk delete all tag instances. param: stdClass[] $taginstances A list of tag_instance records to delete. Each |
| delete_instances_by_id(array $taginstanceids) X-Ref |
| Bulk delete all tag instances by tag id. param: int[] $taginstanceids List of tag instance ids to be deleted. |
| delete_instances($component, $itemtype = null, $contextid = null) X-Ref |
| Bulk delete all tag instances for a component or tag area param: string $component param: string $itemtype (optional) param: int $contextid (optional) |
| add_instance($component, $itemtype, $itemid, context $context, $ordering, $tiuserid = 0) X-Ref |
| Adds a tag instance param: string $component param: string $itemtype param: string $itemid param: context $context param: int $ordering param: int $tiuserid tag instance user id, only needed for tag areas with user tagging (such as core/course) return: int id of tag_instance |
| update_instance_ordering($instanceid, $ordering) X-Ref |
| Updates the ordering on tag instance param: int $instanceid param: int $ordering |
| get_items_tags($component, $itemtype, $itemids, $standardonly = self::BOTH_STANDARD_AND_NOT,$tiuserid = 0) X-Ref |
| Get the array of core_tag_tag objects associated with a list of items. Use {@link core_tag_tag::get_item_tags_array()} if you wish to get the same data as simple array. param: string $component component responsible for tagging. For BC it can be empty but in this case the param: string $itemtype type of the tagged item param: int[] $itemids param: int $standardonly wether to return only standard tags or any param: int $tiuserid tag instance user id, only needed for tag areas with user tagging return: core_tag_tag[][] first array key is itemid. For each itemid, |
| get_item_tags($component, $itemtype, $itemid, $standardonly = self::BOTH_STANDARD_AND_NOT,$tiuserid = 0) X-Ref |
| Get the array of core_tag_tag objects associated with an item (instances). Use {@link core_tag_tag::get_item_tags_array()} if you wish to get the same data as simple array. param: string $component component responsible for tagging. For BC it can be empty but in this case the param: string $itemtype type of the tagged item param: int $itemid param: int $standardonly wether to return only standard tags or any param: int $tiuserid tag instance user id, only needed for tag areas with user tagging return: core_tag_tag[] each object contains additional fields taginstanceid, taginstancecontextid and ordering |
| get_item_tags_array($component, $itemtype, $itemid, $standardonly = self::BOTH_STANDARD_AND_NOT,$tiuserid = 0, $ashtml = true) X-Ref |
| Returns the list of display names of the tags that are associated with an item This method is usually used to prefill the form data for the 'tags' form element param: string $component component responsible for tagging. For BC it can be empty but in this case the param: string $itemtype type of the tagged item param: int $itemid param: int $standardonly wether to return only standard tags or any param: int $tiuserid tag instance user id, only needed for tag areas with user tagging param: bool $ashtml (default true) if true will return htmlspecialchars encoded tag names return: string[] array of tags display names |
| set_item_tags($component, $itemtype, $itemid, context $context, $tagnames, $tiuserid = 0) X-Ref |
| Sets the list of tag instances for one item (table record). Extra exsisting instances are removed, new ones are added. New tags are created if needed. This method can not be used for setting tags relations, please use set_related_tags() param: string $component component responsible for tagging param: string $itemtype type of the tagged item param: int $itemid param: context $context param: array $tagnames param: int $tiuserid tag instance user id, only needed for tag areas with user tagging (such as core/course) |
| remove_all_item_tags($component, $itemtype, $itemid, $tiuserid = 0) X-Ref |
| Removes all tags from an item. All tags will be removed even if tagging is disabled in this area. This is usually called when the item itself has been deleted. param: string $component component responsible for tagging param: string $itemtype type of the tagged item param: int $itemid param: int $tiuserid tag instance user id, only needed for tag areas with user tagging (such as core/course) |
| add_item_tag($component, $itemtype, $itemid, context $context, $tagname, $tiuserid = 0) X-Ref |
| Adds a tag to an item, without overwriting the current tags. If the tag has already been added to the record, no changes are made. param: string $component the component that was tagged param: string $itemtype the type of record to tag ('post' for blogs, 'user' for users, etc.) param: int $itemid the id of the record to tag param: context $context the context of where this tag was assigned param: string $tagname the tag to add param: int $tiuserid tag instance user id, only needed for tag areas with user tagging (such as core/course) return: int id of tag_instance that was either created or already existed or null if tagging is not enabled |
| remove_item_tag($component, $itemtype, $itemid, $tagname, $tiuserid = 0) X-Ref |
| Removes the tag from an item without changing the other tags param: string $component the component that was tagged param: string $itemtype the type of record to tag ('post' for blogs, 'user' for users, etc.) param: int $itemid the id of the record to tag param: string $tagname the tag to remove param: int $tiuserid tag instance user id, only needed for tag areas with user tagging (such as core/course) |
| move_context($component, $itemtype, $oldcontext, $newcontext) X-Ref |
| Allows to move all tag instances from one context to another param: string $component the component that was tagged param: string $itemtype the type of record to tag ('post' for blogs, 'user' for users, etc.) param: context $oldcontext param: context $newcontext |
| change_items_context($component, $itemtype, $itemids, $newcontext) X-Ref |
| Moves all tags of the specified items to the new context param: string $component the component that was tagged param: string $itemtype the type of record to tag ('post' for blogs, 'user' for users, etc.) param: array $itemids param: context|int $newcontext target context to move tags to |
| change_instances_context(array $taginstanceids, context $newcontext) X-Ref |
| Moves all of the specified tag instances into a new context. param: array $taginstanceids The list of tag instance ids that should be moved param: context $newcontext The context to move the tag instances into |
| update($data) X-Ref |
| Updates the information about the tag param: array|stdClass $data data to update, may contain: isstandard, description, descriptionformat, rawname return: bool whether the tag was updated. False may be returned if: all new values match the existing, |
| flag() X-Ref |
| Flag a tag as inappropriate |
| reset_flag() X-Ref |
| Remove the inappropriate flag on a tag. |
| set_related_tags($tagnames) X-Ref |
| Sets the list of tags related to this one. Tag relations are recorded by two instances linking two tags to each other. For tag relations ordering is not used and may be random. param: array $tagnames |
| add_related_tags($tagnames) X-Ref |
| Adds to the list of related tags without removing existing Tag relations are recorded by two instances linking two tags to each other. For tag relations ordering is not used and may be random. param: array $tagnames |
| get_correlated_tags($keepduplicates = false) X-Ref |
| Returns the correlated tags of a tag, retrieved from the tag_correlation table. Correlated tags are calculated in cron based on existing tag instances. param: bool $keepduplicates if true, will return one record for each existing return: core_tag_tag[] an array of tag objects |
| get_manual_related_tags() X-Ref |
| Returns tags that this tag was manually set as related to return: core_tag_tag[] |
| get_related_tags() X-Ref |
| Returns tags related to a tag Related tags of a tag come from two sources: - manually added related tags, which are tag_instance entries for that tag - correlated tags, which are calculated return: core_tag_tag[] an array of tag objects |
| get_tagged_items($component, $itemtype, $limitfrom = '', $limitnum = '', $subquery = '', $params = array() X-Ref |
| Find all items tagged with a tag of a given type ('post', 'user', etc.) param: string $component component responsible for tagging. For BC it can be empty but in this case the param: string $itemtype type to restrict search to param: int $limitfrom (optional, required if $limitnum is set) return a subset of records, starting at this point. param: int $limitnum (optional, required if $limitfrom is set) return a subset comprising this many records. param: string $subquery additional query to be appended to WHERE clause, refer to the itemtable as 'it' param: array $params additional parameters for the DB query return: array of matching objects, indexed by record id, from the table containing the type requested |
| count_tagged_items($component, $itemtype, $subquery = '', $params = array() X-Ref |
| Count how many items are tagged with a specific tag. param: string $component component responsible for tagging. For BC it can be empty but in this case the param: string $itemtype type to restrict search to param: string $subquery additional query to be appended to WHERE clause, refer to the itemtable as 'it' param: array $params additional parameters for the DB query return: int number of mathing tags. |
| is_item_tagged_with($component, $itemtype, $itemid, $tagname) X-Ref |
| Determine if an item is tagged with a specific tag Note that this is a static method and not a method of core_tag object because the tag might not exist yet, for example user searches for "php" and we offer him to add "php" to his interests. param: string $component component responsible for tagging. For BC it can be empty but in this case the param: string $itemtype the record type to look for param: int $itemid the record id to look for param: string $tagname a tag name return: int 1 if it is tagged, 0 otherwise |
| is_enabled($component, $itemtype) X-Ref |
| Returns whether the tag area is enabled param: string $component component responsible for tagging param: string $itemtype what is being tagged, for example, 'post', 'course', 'user', etc. return: bool|null |
| get_tag_index($tagarea, $exclusivemode, $fromctx, $ctx, $rec, $page = 0) X-Ref |
| Retrieves contents of tag area for the tag/index.php page param: stdClass $tagarea param: bool $exclusivemode if set to true it means that no other entities tagged with this tag param: int $fromctx context id where the link was displayed, may be used by callbacks param: int $ctx context id where to search for records param: bool $rec search in subcontexts as well param: int $page 0-based number of page being displayed return: \core_tag\output\tagindex |
| get_formatted_description($options = array() X-Ref |
| Returns formatted description of the tag param: array $options return: string |
| get_links() X-Ref |
| Returns the list of tag links available for the current user (edit, flag, etc.) return: array |
| delete_tags($tagids) X-Ref |
| Delete one or more tag, and all their instances if there are any left. param: int|array $tagids one tagid (int), or one array of tagids to delete return: bool true on success, false otherwise |
| combine_correlated_tags($tags) X-Ref |
| Combine together correlated tags of several tags This is a help method for method combine_tags() param: core_tag_tag[] $tags |
| combine_tags($tags) X-Ref |
| Combines several other tags into this one Combining rules: - current tag becomes the "main" one, all instances pointing to other tags are changed to point to it. - if any of the tags is standard, the "main" tag becomes standard too - all tags except for the current ("main") are deleted, even when they are standard param: core_tag_tag[] $tags tags to combine into this one |
| get_tags_by_area_in_contexts($component, $itemtype, array $contexts) X-Ref |
| Retrieve a list of tags that have been used to tag the given $component and $itemtype in the provided $contexts. param: string $component The tag instance component param: string $itemtype The tag instance item type param: context[] $contexts The list of contexts to look for tag instances in return: core_tag_tag[] |
