Search moodle.org's
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.

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


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[]