Static Public Member Functions
static	activateTagWithChecks ( $tag, $reason, User $user, $ignoreWarnings=false, array $logEntryTags=[])
	Activates a tag, checking whether it is allowed first, and adding a log entry afterwards. More...

static	addTags ( $tags, $rc_id=null, $rev_id=null, $log_id=null, $params=null, RecentChange $rc=null)
	Add tags to a change given its rc_id, rev_id and/or log_id. More...

static	addTagsAccompanyingChangeWithChecks (array $tags, $rc_id, $rev_id, $log_id, $params, User $user)
	Adds tags to a given change, checking whether it is allowed first, but without adding a log entry. More...

static	buildTagFilterSelector ( $selected='', $ooui=false, IContextSource $context=null)
	Build a text box to select a change tag. More...

static	canActivateTag ( $tag, User $user=null)
	Is it OK to allow the user to activate this tag? More...

static	canAddTagsAccompanyingChange (array $tags, User $user=null)
	Is it OK to allow the user to apply all the specified tags at the same time as they edit/make the change? More...

static	canCreateTag ( $tag, User $user=null)
	Is it OK to allow the user to create this tag? More...

static	canDeactivateTag ( $tag, User $user=null)
	Is it OK to allow the user to deactivate this tag? More...

static	canDeleteTag ( $tag, User $user=null)
	Is it OK to allow the user to delete this tag? More...

static	canUpdateTags (array $tagsToAdd, array $tagsToRemove, User $user=null)
	Is it OK to allow the user to adds and remove the given tags tags to/from a change? More...

static	createTagWithChecks ( $tag, $reason, User $user, $ignoreWarnings=false, array $logEntryTags=[])
	Creates a tag by adding it to `change_tag_def` table. More...

static	deactivateTagWithChecks ( $tag, $reason, User $user, $ignoreWarnings=false, array $logEntryTags=[])
	Deactivates a tag, checking whether it is allowed first, and adding a log entry afterwards. More...

static	defineTag ( $tag)
	Set ctd_user_defined = 1 in change_tag_def without checking that the tag name is valid. More...

static	deleteTagEverywhere ( $tag)
	Permanently removes all traces of a tag from the DB. More...

static	deleteTagWithChecks ( $tag, $reason, User $user, $ignoreWarnings=false, array $logEntryTags=[])
	Deletes a tag, checking whether it is allowed first, and adding a log entry afterwards. More...

static	formatSummaryRow ( $tags, $page, IContextSource $context=null)
	Creates HTML for the given tags. More...

static	getSoftwareTags ( $all=false)
	Loads defined core tags, checks for invalid types (if not array), and filters for supported and enabled (if $all is false) tags only. More...

static	getTags (IDatabase $db, $rc_id=null, $rev_id=null, $log_id=null)
	Return all the tags associated with the given recent change ID, revision ID, and/or log entry ID. More...

static	isTagNameValid ( $tag)
	Is the tag name valid? More...

static	listDefinedTags ()
	Basically lists defined tags which count even if they aren't applied to anything. More...

static	listExplicitlyDefinedTags ()
	Lists tags explicitly defined in the `change_tag_def` table of the database. More...

static	listSoftwareActivatedTags ()
	Lists those tags which core or extensions report as being "active". More...

static	listSoftwareDefinedTags ()
	Lists tags defined by core or extensions using the ListDefinedTags hook. More...

static	makeTagSummarySubquery ( $tables)
	Make the tag summary subquery based on the given tables and return it. More...

static	modifyDisplayQuery (&$tables, &$fields, &$conds, &$join_conds, &$options, $filter_tag='')
	Applies all tags-related changes to a query. More...

static	purgeTagCacheAll ()
	Invalidates the short-term cache of defined tags used by the list*DefinedTags functions, as well as the tag statistics cache. More...

static	showTagEditingUI (User $user)
	Indicate whether change tag editing UI is relevant. More...

static	tagDescription ( $tag, MessageLocalizer $context)
	Get a short description for a tag. More...

static	tagLongDescriptionMessage ( $tag, MessageLocalizer $context)
	Get the message object for the tag's long description. More...

static	tagShortDescriptionMessage ( $tag, MessageLocalizer $context)
	Get the message object for the tag's short description. More...

static	tagUsageStatistics ()
	Returns a map of any tags used on the wiki to number of edits tagged with them, ordered descending by the hitcount. More...

static	truncateTagDescription ( $tag, $length, IContextSource $context)
	Get truncated message for the tag's long description. More...

static	undefineTag ( $tag)
	Update ctd_user_defined = 0 field in change_tag_def. More...

static	updateTags ( $tagsToAdd, $tagsToRemove, &$rc_id=null, &$rev_id=null, &$log_id=null, $params=null, RecentChange $rc=null, User $user=null)
	Add and remove tags to/from a change given its rc_id, rev_id and/or log_id, without verifying that the tags exist or are valid. More...

static	updateTagsWithChecks ( $tagsToAdd, $tagsToRemove, $rc_id, $rev_id, $log_id, $params, $reason, User $user)
	Adds and/or removes tags to/from a given change, checking whether it is allowed first, and adding a log entry afterwards. More...

Public Attributes
const	MAX_DELETE_USES = 5000
	Can't delete tags with more than this many uses. More...

Static Protected Member Functions
static	logTagManagementAction ( $action, $tag, $reason, User $user, $tagCount=null, array $logEntryTags=[])
	Writes a tag action into the tag management log. More...

static	restrictedTagError ( $msgOne, $msgMulti, $tags)
	Helper function to generate a fatal status with a 'not-allowed' type error. More...

Static Private Attributes
static	$definedSoftwareTags
	A list of tags defined and used by MediaWiki itself. More...

Detailed Description

Definition at line 29 of file ChangeTags.php.

Member Function Documentation

◆ activateTagWithChecks()

static ChangeTags::activateTagWithChecks	(		$tag,
			$reason,
		User	$user,
			$ignoreWarnings = `false`,
		array	$logEntryTags = `[]`
	)

static

Activates a tag, checking whether it is allowed first, and adding a log entry afterwards.

Includes a call to ChangeTag::canActivateTag(), so your code doesn't need to do that.

Parameters

string	$tag
string	$reason
User	$user	Who to give credit for the action
bool	$ignoreWarnings	Can be used for API interaction, default false
array	$logEntryTags	Change tags to apply to the entry that will be created in the tag management log

Returns: Status If successful, the Status contains the ID of the added log entry as its value

Since: 1.25

Definition at line 1061 of file ChangeTags.php.

References StatusValue\newGood(), and null.

◆ addTags()

static ChangeTags::addTags	(		$tags,
			$rc_id = `null`,
			$rev_id = `null`,
			$log_id = `null`,
			$params = `null`,
		RecentChange	$rc = `null`
	)

static

Add tags to a change given its rc_id, rev_id and/or log_id.

Parameters

	string\|string[]	$tags Tags to add to the change
int \| null	$rc_id	The rc_id of the change to add the tags to
int \| null	$rev_id	The rev_id of the change to add the tags to
int \| null	$log_id	The log_id of the change to add the tags to
string \| null	$params	Params to put in the ct_params field of table 'change_tag'
RecentChange \| null	$rc	Recent change, in case the tagging accompanies the action (this should normally be the case)

Exceptions

MWException

Returns: bool False if no changes are made, otherwise true

Definition at line 251 of file ChangeTags.php.

References $params, and null.

Referenced by MovePage\moveToInternal(), ApiTag\processIndividual(), ManualLogEntry\publish(), RecentChange\save(), ChangeTagsTest\testGetTags(), and ChangeTagsTest\testGetTags_multiple_arguments().

◆ addTagsAccompanyingChangeWithChecks()

static ChangeTags::addTagsAccompanyingChangeWithChecks	(	array	$tags,
			$rc_id,
			$rev_id,
			$log_id,
			$params,
		User	$user
	)

static

Adds tags to a given change, checking whether it is allowed first, but without adding a log entry.

Useful for cases where the tag is being added along with the action that generated the change (e.g. tagging an edit as it is being made).

Extensions should not use this function, unless directly handling a user request to add a particular tag. Normally, extensions should call ChangeTags::updateTags() instead.

Parameters

array	$tags	Tags to apply
int \| null	$rc_id	The rc_id of the change to add the tags to
int \| null	$rev_id	The rev_id of the change to add the tags to
int \| null	$log_id	The log_id of the change to add the tags to
string	$params	Params to put in the ct_params field of table 'change_tag' when adding tags
User	$user	Who to give credit for the action

Returns: Status

Since: 1.25

Definition at line 564 of file ChangeTags.php.

References $params, StatusValue\newGood(), and null.

◆ buildTagFilterSelector()

static ChangeTags::buildTagFilterSelector	(		$selected = `''`,
			$ooui = `false`,
		IContextSource	$context = `null`
	)

static

Build a text box to select a change tag.

Parameters

string	$selected	Tag to select by default
bool	$ooui	Use an OOUI TextInputWidget as selector instead of a non-OOUI input field You need to call OutputPage::enableOOUI() yourself.
IContextSource \| null	$context

Note: Even though it takes null as a valid argument, an IContextSource is preferred in a new code, as the null value can change in the future

Returns: array an array of (label, selector)

Definition at line 874 of file ChangeTags.php.

References $context, RequestContext\getMain(), Xml\input(), and Html\rawElement().

Referenced by HTMLTagFilter\getDiv(), SpecialRecentChanges\getExtraOptions(), SpecialContributions\getForm(), HTMLTagFilter\getOOUI(), and HTMLTagFilter\getTableRow().

◆ canActivateTag()

static ChangeTags::canActivateTag	(		$tag,
		User	$user = `null`
	)

static

Is it OK to allow the user to activate this tag?

Parameters

string	$tag	Tag that you are interested in activating
User \| null	$user	User whose permission you wish to check, or null if you don't care (e.g. maintenance scripts)

Returns: Status

Since: 1.25

Definition at line 1016 of file ChangeTags.php.

References $user, StatusValue\newFatal(), and StatusValue\newGood().

Referenced by SpecialTags\doTagRow().

◆ canAddTagsAccompanyingChange()

static ChangeTags::canAddTagsAccompanyingChange	(	array	$tags,
		User	$user = `null`
	)

static

Is it OK to allow the user to apply all the specified tags at the same time as they edit/make the change?

Extensions should not use this function, unless directly handling a user request to add a tag to a revision or log entry that the user is making.

Parameters

array	$tags	Tags that you are interested in applying
User \| null	$user	User whose permission you wish to check, or null to check for a generic non-blocked user with the relevant rights

Returns: Status

Since: 1.25

Definition at line 521 of file ChangeTags.php.

References $user, StatusValue\newFatal(), StatusValue\newGood(), and Hooks\run().

Referenced by ApiImageRotate\execute(), ApiProtect\execute(), ApiUndelete\execute(), ApiManageTags\execute(), ApiImport\execute(), ApiMove\execute(), ApiRevisionDelete\execute(), ApiTag\execute(), ApiEditPage\execute(), ApiPatrol\execute(), ApiDelete\execute(), ApiRollback\execute(), ApiUnblock\execute(), ApiBlock\execute(), ApiSetPageLanguage\execute(), ApiUserrights\execute(), ApiBase\getParameterFromSettings(), EditPage\internalAttemptSave(), MovePage\moveIfAllowed(), ApiUpload\performUpload(), and SpecialUpload\processUpload().

◆ canCreateTag()

static ChangeTags::canCreateTag	(		$tag,
		User	$user = `null`
	)

static

Is it OK to allow the user to create this tag?

Extensions should NOT use this function. In most cases, a tag can be defined using the ListDefinedTags hook without any checking.

Parameters

string	$tag	Tag that you are interested in creating
User \| null	$user	User whose permission you wish to check, or null if you don't care (e.g. maintenance scripts)

Returns: Status

Since: 1.25

Definition at line 1189 of file ChangeTags.php.

References $user, StatusValue\newFatal(), StatusValue\newGood(), and Hooks\run().

◆ canDeactivateTag()

static ChangeTags::canDeactivateTag	(		$tag,
		User	$user = `null`
	)

static

Is it OK to allow the user to deactivate this tag?

Parameters

string	$tag	Tag that you are interested in deactivating
User \| null	$user	User whose permission you wish to check, or null if you don't care (e.g. maintenance scripts)

Returns: Status

Since: 1.25

Definition at line 1090 of file ChangeTags.php.

References $user, StatusValue\newFatal(), and StatusValue\newGood().

Referenced by SpecialTags\doTagRow().

◆ canDeleteTag()

static ChangeTags::canDeleteTag	(		$tag,
		User	$user = `null`
	)

static

Is it OK to allow the user to delete this tag?

Parameters

string	$tag	Tag that you are interested in deleting
User \| null	$user	User whose permission you wish to check, or null if you don't care (e.g. maintenance scripts)

Returns: Status

Since: 1.25

Definition at line 1307 of file ChangeTags.php.

References $user, StatusValue\newFatal(), StatusValue\newGood(), and Hooks\run().

Referenced by SpecialTags\doTagRow(), and SpecialTags\showDeleteTagForm().

◆ canUpdateTags()

static ChangeTags::canUpdateTags	(	array	$tagsToAdd,
		array	$tagsToRemove,
		User	$user = `null`
	)

static

Is it OK to allow the user to adds and remove the given tags tags to/from a change?

Extensions should not use this function, unless directly handling a user request to add or remove tags from an existing revision or log entry.

Parameters

array	$tagsToAdd	Tags that you are interested in adding
array	$tagsToRemove	Tags that you are interested in removing
User \| null	$user	User whose permission you wish to check, or null to check for a generic non-blocked user with the relevant rights

Returns: Status

Since: 1.25

Definition at line 594 of file ChangeTags.php.

References $user, StatusValue\newFatal(), and StatusValue\newGood().

◆ createTagWithChecks()

static ChangeTags::createTagWithChecks	(		$tag,
			$reason,
		User	$user,
			$ignoreWarnings = `false`,
		array	$logEntryTags = `[]`
	)

static

Creates a tag by adding it to change_tag_def table.

Extensions should NOT use this function; they can use the ListDefinedTags hook instead.

Includes a call to ChangeTag::canCreateTag(), so your code doesn't need to do that.

Parameters

string	$tag
string	$reason
User	$user	Who to give credit for the action
bool	$ignoreWarnings	Can be used for API interaction, default false
array	$logEntryTags	Change tags to apply to the entry that will be created in the tag management log

Returns: Status If successful, the Status contains the ID of the added log entry as its value

Since: 1.25

Definition at line 1236 of file ChangeTags.php.

References StatusValue\newGood(), and null.

Referenced by AddChangeTag\execute(), and SpecialTags\processCreateTagForm().

◆ deactivateTagWithChecks()

static ChangeTags::deactivateTagWithChecks	(		$tag,
			$reason,
		User	$user,
			$ignoreWarnings = `false`,
		array	$logEntryTags = `[]`
	)

static

Deactivates a tag, checking whether it is allowed first, and adding a log entry afterwards.

Includes a call to ChangeTag::canDeactivateTag(), so your code doesn't need to do that.

Parameters

string	$tag
string	$reason
User	$user	Who to give credit for the action
bool	$ignoreWarnings	Can be used for API interaction, default false
array	$logEntryTags	Change tags to apply to the entry that will be created in the tag management log

Returns: Status If successful, the Status contains the ID of the added log entry as its value

Since: 1.25

Definition at line 1126 of file ChangeTags.php.

References StatusValue\newGood(), and null.

◆ defineTag()

static ChangeTags::defineTag ( $tag )

static

Set ctd_user_defined = 1 in change_tag_def without checking that the tag name is valid.

Extensions should NOT use this function; they can use the ListDefinedTags hook instead.

Parameters

string $tag Tag to create

Since: 1.25

Definition at line 921 of file ChangeTags.php.

References DB_MASTER, and wfGetDB().

Referenced by ApiBaseTest\doGetParameterFromSettings(), ApiBlockTest\testBlockWithProhibitedTag(), ApiBlockTest\testBlockWithTag(), ApiDeleteTest\testDeleteWithoutTagPermission(), ApiDeleteTest\testDeleteWithTag(), ApiEditPageTest\testEditWithoutTagPermission(), ApiEditPageTest\testEditWithTag(), ChangeTagsTest\testListExplicitlyDefinedTags(), ApiMoveTest\testTagsNoPermission(), ApiUnblockTest\testUnblockWithProhibitedTag(), ApiUnblockTest\testUnblockWithTagNewBackend(), ApiUserrightsTest\testWithoutTagPermission(), and ApiUserrightsTest\testWithTag().

◆ deleteTagEverywhere()

static ChangeTags::deleteTagEverywhere ( $tag )

static

Permanently removes all traces of a tag from the DB.

Good for removing misspelt or temporary tags.

This function should be directly called by maintenance scripts only, never by user-facing code. See deleteTagWithChecks() for functionality that can safely be exposed to users.

Parameters

string $tag Tag to remove

Returns: Status The returned status will be good unless a hook changed it

Since: 1.25

Definition at line 1268 of file ChangeTags.php.

References DB_MASTER, StatusValue\newGood(), Hooks\run(), wfDebug(), and wfGetDB().

◆ deleteTagWithChecks()

static ChangeTags::deleteTagWithChecks	(		$tag,
			$reason,
		User	$user,
			$ignoreWarnings = `false`,
		array	$logEntryTags = `[]`
	)

static

Deletes a tag, checking whether it is allowed first, and adding a log entry afterwards.

Includes a call to ChangeTag::canDeleteTag(), so your code doesn't need to do that.

Parameters

string	$tag
string	$reason
User	$user	Who to give credit for the action
bool	$ignoreWarnings	Can be used for API interaction, default false
array	$logEntryTags	Change tags to apply to the entry that will be created in the tag management log

Returns: Status If successful, the Status contains the ID of the added log entry as its value

Since: 1.25

Definition at line 1359 of file ChangeTags.php.

References null.

◆ formatSummaryRow()

static ChangeTags::formatSummaryRow	(		$tags,
			$page,
		IContextSource	$context = `null`
	)

static

Creates HTML for the given tags.

Parameters

string	$tags	Comma-separated list of tags
string	$page	A label for the type of action which is being displayed, for example: 'history', 'contributions' or 'newpages'
IContextSource \| null	$context

Note: Even though it takes null as a valid argument, an IContextSource is preferred in a new code, as the null value is subject to change in the future

Returns

array Array with two items: (html, classes)

html: String: HTML for displaying the tags (empty string when param $tags is empty)
classes: Array of strings: CSS classes used in the generated html, one class for each tag

-taint onlysafefor_htmlnoent

Definition at line 94 of file ChangeTags.php.

References $context, as, Sanitizer\escapeClass(), RequestContext\getMain(), and Xml\tags().

Referenced by SpecialUndelete\diffHeader(), SpecialUndelete\formatRevisionRow(), SpecialNewpages\formatRow(), ContribsPager\formatRow(), ChangeTagsRevisionItem\getHTML(), ChangeTagsLogItem\getHTML(), RevDelRevisionItem\getHTML(), HistoryPager\historyLine(), ChangesList\insertTags(), LogEventsList\logLine(), and DifferenceEngine\showDiffPage().

◆ getSoftwareTags()

static ChangeTags::getSoftwareTags ( $all = false )

static

Loads defined core tags, checks for invalid types (if not array), and filters for supported and enabled (if $all is false) tags only.

Parameters

bool $all If true, return all valid defined tags. Otherwise, return only enabled ones.

Returns: array Array of all defined/enabled tags.

Definition at line 58 of file ChangeTags.php.

References $wgSoftwareTags, and wfWarn().

Referenced by WikiPage\commitRollback(), MediaWiki\Storage\PageUpdater\computeEffectiveTags(), ContentHandler\getChangeTag(), MovePage\moveToInternal(), and ChangeTagsTest\testGetSoftwareTags().

◆ getTags()

static ChangeTags::getTags	(	IDatabase	$db,
			$rc_id = `null`,
			$rev_id = `null`,
			$log_id = `null`
	)

static

Return all the tags associated with the given recent change ID, revision ID, and/or log entry ID.

Parameters

IDatabase	$db	the database to query
int \| null	$rc_id
int \| null	$rev_id
int \| null	$log_id

Returns: string[]

Definition at line 466 of file ChangeTags.php.

References as, and Wikimedia\Rdbms\IDatabase\selectFieldValues().

Referenced by ChangeTagsTest\testGetTags(), and ChangeTagsTest\testGetTags_multiple_arguments().

◆ isTagNameValid()

static ChangeTags::isTagNameValid ( $tag )

static

Is the tag name valid?

Parameters

string $tag Tag that you are interested in creating

Returns: Status

Since: 1.30

Definition at line 1153 of file ChangeTags.php.

References $title, Title\makeTitleSafe(), StatusValue\newFatal(), StatusValue\newGood(), and NS_MEDIAWIKI.

◆ listDefinedTags()

static ChangeTags::listDefinedTags ( )

static

Basically lists defined tags which count even if they aren't applied to anything.

It returns a union of the results of listExplicitlyDefinedTags()

Returns: string[] Array of strings: tags

Definition at line 1424 of file ChangeTags.php.

Referenced by ApiFeedContributions\getAllowedParams().

◆ listExplicitlyDefinedTags()

static ChangeTags::listExplicitlyDefinedTags ( )

static

Lists tags explicitly defined in the change_tag_def table of the database.

Tries memcached first.

Returns: string[] Array of strings: tags

Since: 1.25

Definition at line 1438 of file ChangeTags.php.

References $cache, $dbr, $fname, DB_REPLICA, IExpiringStore\TTL_MINUTE, IExpiringStore\TTL_PROC_LONG, use, and wfGetDB().

Referenced by ApiQueryTags\execute(), ChangesListSpecialPage\getChangeTagInfo(), ApiHelp\getHelpInternal(), ApiParamInfo\getModuleInfo(), SpecialEditTags\getTagSelect(), SpecialTags\showTagList(), and ChangeTagsTest\testListExplicitlyDefinedTags().

◆ listSoftwareActivatedTags()

static ChangeTags::listSoftwareActivatedTags ( )

static

Lists those tags which core or extensions report as being "active".

Returns: array

Since: 1.25

Definition at line 1393 of file ChangeTags.php.

References $cache, DB_REPLICA, Hooks\isRegistered(), Hooks\run(), IExpiringStore\TTL_MINUTE, IExpiringStore\TTL_PROC_LONG, use, and wfGetDB().

Referenced by ApiQueryTags\execute(), ChangesListSpecialPage\getChangeTagInfo(), SpecialTags\showDeleteTagForm(), and SpecialTags\showTagList().

◆ listSoftwareDefinedTags()

static ChangeTags::listSoftwareDefinedTags ( )

static

Lists tags defined by core or extensions using the ListDefinedTags hook.

Extensions need only define those tags they deem to be in active use.

Tries memcached first.

Returns: string[] Array of strings: tags

Since: 1.25

Definition at line 1476 of file ChangeTags.php.

References $cache, DB_REPLICA, Hooks\isRegistered(), Hooks\run(), IExpiringStore\TTL_MINUTE, IExpiringStore\TTL_PROC_LONG, use, and wfGetDB().

Referenced by ApiQueryTags\execute(), and SpecialTags\showTagList().

◆ logTagManagementAction()

static ChangeTags::logTagManagementAction	(		$action,
			$tag,
			$reason,
		User	$user,
			$tagCount = `null`,
		array	$logEntryTags = `[]`
	)

staticprotected

Writes a tag action into the tag management log.

Parameters

string	$action
string	$tag
string	$reason
User	$user	Who to attribute the action to
int \| null	$tagCount	For deletion only, how many usages the tag had before it was deleted.
array	$logEntryTags	Change tags to apply to the entry that will be created in the tag management log

Returns: int ID of the inserted log entry

Since: 1.25

Definition at line 982 of file ChangeTags.php.

References $params, DB_MASTER, Title\newFromText(), and wfGetDB().

◆ makeTagSummarySubquery()

static ChangeTags::makeTagSummarySubquery ( $tables )

static

Make the tag summary subquery based on the given tables and return it.

Parameters

string | array $tables Table names, see Database::select

Returns: string tag summary subqeury

Exceptions

MWException When unable to determine appropriate JOIN condition for tagging

Definition at line 837 of file ChangeTags.php.

References $tables, DB_REPLICA, and wfGetDB().

Referenced by ApiQueryDeletedrevs\execute(), ApiQueryLogEvents\execute(), WatchedItemQueryService\getWatchedItemsWithRCInfoQueryFields(), ApiQueryUserContribs\prepareQuery(), ApiQueryDeletedRevisions\run(), ApiQueryAllRevisions\run(), ApiQueryAllDeletedRevisions\run(), ApiQueryRevisions\run(), and ApiQueryRecentChanges\run().

◆ modifyDisplayQuery()

static ChangeTags::modifyDisplayQuery	(	&	$tables,
		&	$fields,
		&	$conds,
		&	$join_conds,
		&	$options,
			$filter_tag = `''`
	)

static

Applies all tags-related changes to a query.

Handles selecting tags, and filtering. Needs $tables to be set up properly, so we can figure out which join conditions to use.

WARNING: If $filter_tag contains more than one tag, this function will add DISTINCT, which may cause performance problems for your query unless you put the ID field of your table at the end of the ORDER BY, and set a GROUP BY equal to the ORDER BY. For example, if you had ORDER BY foo_timestamp DESC, you will now need GROUP BY foo_timestamp, foo_id ORDER BY foo_timestamp DESC, foo_id DESC.

Parameters

string \| array	&$tables	Table names, see Database::select
string \| array	&$fields	Fields used in query, see Database::select
string \| array	&$conds	Conditions used in query, see Database::select
array	&$join_conds	Join conditions, see Database::select
string \| array	&$options	Options, see Database::select
string \| array	$filter_tag	Tag(s) to select on

Exceptions

MWException When unable to determine appropriate JOIN condition for tagging

Definition at line 772 of file ChangeTags.php.

References $options, $tables, $wgUseTagFilter, and as.

Referenced by SpecialRecentChangesLinked\doMainQuery(), SpecialRecentChanges\doMainQuery(), SpecialWatchlist\doMainQuery(), ChangesListSpecialPage\doMainQuery(), ChangeTagsLogList\doQuery(), ChangeTagsRevisionList\doQuery(), RevDelArchiveList\doQuery(), RevDelRevisionList\doQuery(), NewPagesPager\getQueryInfo(), HistoryPager\getQueryInfo(), ContribsPager\getQueryInfo(), LogPager\getQueryInfo(), PageArchive\listRevisions(), and ChangeTagsTest\testModifyDisplayQuery().

◆ purgeTagCacheAll()

static ChangeTags::purgeTagCacheAll ( )

static

Invalidates the short-term cache of defined tags used by the list*DefinedTags functions, as well as the tag statistics cache.

Since: 1.25

Definition at line 1505 of file ChangeTags.php.

References $cache.

◆ restrictedTagError()

static ChangeTags::restrictedTagError	(	$msgOne,
		$msgMulti,
		$tags
	)

staticprotected

Helper function to generate a fatal status with a 'not-allowed' type error.

Parameters

string	$msgOne	Message key to use in the case of one tag
string	$msgMulti	Message key to use in the case of more than one tag
array	$tags	Restricted tags (passed as $1 into the message, count of $tags passed as $2)

Returns: Status

Since: 1.25

Definition at line 501 of file ChangeTags.php.

References $lang, RequestContext\getMain(), and StatusValue\newFatal().

◆ showTagEditingUI()

static ChangeTags::showTagEditingUI ( User $user )

static

Indicate whether change tag editing UI is relevant.

Returns true if the user has the necessary right and there are any editable tags defined.

This intentionally doesn't check "any addable || any deletable", because it seems like it would be more confusing than useful if the checkboxes suddenly showed up because some abuse filter stopped defining a tag and then suddenly disappeared when someone deleted all uses of that tag.

Parameters

User $user

Returns: bool

Definition at line 1568 of file ChangeTags.php.

References User\isAllowed().

Referenced by HistoryPager\__construct(), LogEventsList\__construct(), and SpecialLog\getActionButtons().

◆ tagDescription()

static ChangeTags::tagDescription	(		$tag,
		MessageLocalizer	$context
	)

static

Get a short description for a tag.

Checks if message key "mediawiki:tag-$tag" exists. If it does not, returns the HTML-escaped tag name. Uses the message if the message exists, provided it is not disabled. If the message is disabled, we consider the tag hidden, and return false.

Parameters

string	$tag
MessageLocalizer	$context

Returns: string|bool Tag description or false if tag is to be hidden.

Since: 1.25 Returns false if tag is to be hidden.

Definition at line 183 of file ChangeTags.php.

Referenced by SpecialTags\doTagRow(), and ApiQueryTags\execute().

◆ tagLongDescriptionMessage()

static ChangeTags::tagLongDescriptionMessage	(		$tag,
		MessageLocalizer	$context
	)

static

Get the message object for the tag's long description.

Checks if message key "mediawiki:tag-$tag-description" exists. If it does not, or if message is disabled, returns false. Otherwise, returns the message object for the long description.

Parameters

string	$tag
MessageLocalizer	$context

Returns: Message|bool Message object of the tag long description or false if there is no description.

Definition at line 200 of file ChangeTags.php.

References MessageLocalizer\msg().

Referenced by ChangesListSpecialPage\getChangeTagInfo().

◆ tagShortDescriptionMessage()

static ChangeTags::tagShortDescriptionMessage	(		$tag,
		MessageLocalizer	$context
	)

static

Get the message object for the tag's short description.

Checks if message key "mediawiki:tag-$tag" exists. If it does not, returns the tag name in a RawMessage. If the message exists, it is used, provided it is not disabled. If the message is disabled, we consider the tag hidden, and return false.

Since: 1.34

Parameters

string	$tag
MessageLocalizer	$context

Returns: Message|bool Tag description, or false if tag is to be hidden.

Definition at line 149 of file ChangeTags.php.

References MessageLocalizer\msg(), and Message\plaintextParam().

Referenced by ChangesListSpecialPage\getChangeTagInfo().

◆ tagUsageStatistics()

static ChangeTags::tagUsageStatistics ( )

static

Returns a map of any tags used on the wiki to number of edits tagged with them, ordered descending by the hitcount.

This does not include tags defined somewhere that have never been applied.

Returns: array Array of string => int

Definition at line 1522 of file ChangeTags.php.

References $cache, $dbr, $fname, $out, $res, as, DB_REPLICA, IExpiringStore\TTL_MINUTE, IExpiringStore\TTL_PROC_LONG, use, and wfGetDB().

Referenced by ApiQueryTags\execute(), ChangesListSpecialPage\getChangeTagInfo(), SpecialTags\showDeleteTagForm(), SpecialTags\showTagList(), and ChangeTagsTest\testTagUsageStatistics().

◆ truncateTagDescription()

static ChangeTags::truncateTagDescription	(		$tag,
			$length,
		IContextSource	$context
	)

static

Get truncated message for the tag's long description.

Parameters

string	$tag	Tag name.
int	$length	Maximum length of truncated message, including ellipsis.
IContextSource	$context

Returns: string Truncated long tag description.

Definition at line 223 of file ChangeTags.php.

References IContextSource\getLanguage(), and Sanitizer\stripAllTags().

◆ undefineTag()

static ChangeTags::undefineTag ( $tag )

static

Update ctd_user_defined = 0 field in change_tag_def.

The tag may remain in use by extensions, and may still show up as 'defined' if an extension is setting it from the ListDefinedTags hook.

Parameters

string $tag Tag to remove

Since: 1.25

Definition at line 948 of file ChangeTags.php.

References DB_MASTER, and wfGetDB().

◆ updateTags()

static ChangeTags::updateTags	(		$tagsToAdd,
			$tagsToRemove,
		&	$rc_id = `null`,
		&	$rev_id = `null`,
		&	$log_id = `null`,
			$params = `null`,
		RecentChange	$rc = `null`,
		User	$user = `null`
	)

static

Add and remove tags to/from a change given its rc_id, rev_id and/or log_id, without verifying that the tags exist or are valid.

If a tag is present in both $tagsToAdd and $tagsToRemove, it will be removed.

This function should only be used by extensions to manipulate tags they have registered using the ListDefinedTags hook. When dealing with user input, call updateTagsWithChecks() instead.

Parameters

string \| array \| null	$tagsToAdd	Tags to add to the change
string \| array \| null	$tagsToRemove	Tags to remove from the change
int \| null	&$rc_id	The rc_id of the change to add the tags to. Pass a variable whose value is null if the rc_id is not relevant or unknown.
int \| null	&$rev_id	The rev_id of the change to add the tags to. Pass a variable whose value is null if the rev_id is not relevant or unknown.
int \| null	&$log_id	The log_id of the change to add the tags to. Pass a variable whose value is null if the log_id is not relevant or unknown.
string \| null	$params	Params to put in the ct_params field of table 'change_tag' when adding tags
RecentChange \| null	$rc	Recent change being tagged, in case the tagging accompanies the action
User \| null	$user	Tagging user, in case the tagging is subsequent to the tagged action

Exceptions

MWException When $rc_id, $rev_id and $log_id are all null

Returns: array Index 0 is an array of tags actually added, index 1 is an array of tags actually removed, index 2 is an array of tags present on the revision or log entry before any changes were made

Since: 1.25

Definition at line 288 of file ChangeTags.php.

References $fname, $params, $user, as, DB_MASTER, null, Hooks\run(), use, and wfGetDB().

Referenced by ChangeTagsTest\testDeleteTags(), ChangeTagsTest\testListExplicitlyDefinedTags(), ChangeTagsTest\testModifyDisplayQuery(), ChangeTagsTest\testTagUsageStatistics(), ChangeTagsTest\testUpdateTags(), ChangeTagsTest\testUpdateTagsDoNothingOnRepeatedCall(), and ChangeTagsTest\testUpdateTagsSkipDuplicates().

◆ updateTagsWithChecks()

static ChangeTags::updateTagsWithChecks	(		$tagsToAdd,
			$tagsToRemove,
			$rc_id,
			$rev_id,
			$log_id,
			$params,
			$reason,
		User	$user
	)

static

Adds and/or removes tags to/from a given change, checking whether it is allowed first, and adding a log entry afterwards.

Includes a call to ChangeTags::canUpdateTags(), so your code doesn't need to do that. However, it doesn't check whether the *_id parameters are a valid combination. That is up to you to enforce. See ApiTag::execute() for an example.

Extensions should generally avoid this function. Call ChangeTags::updateTags() instead, unless directly handling a user request to add or remove tags from an existing revision or log entry.

Parameters

array \| null	$tagsToAdd	If none, pass [] or null
array \| null	$tagsToRemove	If none, pass [] or null
int \| null	$rc_id	The rc_id of the change to add the tags to
int \| null	$rev_id	The rev_id of the change to add the tags to
int \| null	$log_id	The log_id of the change to add the tags to
string \| null	$params	Params to put in the ct_params field of table 'change_tag' when adding tags
string	$reason	Comment for the log
User	$user	Who to give credit for the action

Returns

Status If successful, the value of this Status object will be an object (stdClass) with the following fields:

logId: the ID of the added log entry, or null if no log entry was added (i.e. no operation was performed)
addedTags: an array containing the tags that were actually added
removedTags: an array containing the tags that were actually removed

Since: 1.25

Definition at line 663 of file ChangeTags.php.

References $params, $rev, DB_MASTER, SpecialPage\getTitleFor(), list, StatusValue\newFatal(), Revision\newFromId(), StatusValue\newGood(), null, User\pingLimiter(), RevDelLogList\suggestTarget(), and wfGetDB().

Referenced by ApiTag\processIndividual(), ChangeTagsLogList\updateChangeTagsOnAll(), and ChangeTagsRevisionList\updateChangeTagsOnAll().

Member Data Documentation

◆ $definedSoftwareTags

ChangeTags::$definedSoftwareTags

staticprivate

Initial value:

= [
        'mw-contentmodelchange',
        'mw-new-redirect',
        'mw-removed-redirect',
        'mw-changed-redirect-target',
        'mw-blank',
        'mw-replace',
        'mw-rollback',
        'mw-undo',
    ]

A list of tags defined and used by MediaWiki itself.

Definition at line 40 of file ChangeTags.php.

◆ MAX_DELETE_USES

const ChangeTags::MAX_DELETE_USES = 5000

Can't delete tags with more than this many uses.

Similar in intent to the bigdelete user right

Todo:: Use the job queue for tag deletion to avoid this restriction

Definition at line 35 of file ChangeTags.php.

The documentation for this class was generated from the following file:

includes/changetags/ChangeTags.php

Static Public Member Functions

Public Attributes

Static Protected Member Functions

Static Private Attributes

Detailed Description

Member Function Documentation

◆ activateTagWithChecks()

◆ addTags()

◆ addTagsAccompanyingChangeWithChecks()

◆ buildTagFilterSelector()

◆ canActivateTag()

◆ canAddTagsAccompanyingChange()

◆ canCreateTag()

◆ canDeactivateTag()

◆ canDeleteTag()

◆ canUpdateTags()

◆ createTagWithChecks()

◆ deactivateTagWithChecks()

◆ defineTag()

◆ deleteTagEverywhere()

◆ deleteTagWithChecks()

◆ formatSummaryRow()

◆ getSoftwareTags()

◆ getTags()

◆ isTagNameValid()

◆ listDefinedTags()

◆ listExplicitlyDefinedTags()

◆ listSoftwareActivatedTags()

◆ listSoftwareDefinedTags()

◆ logTagManagementAction()

◆ makeTagSummarySubquery()

◆ modifyDisplayQuery()

◆ purgeTagCacheAll()

◆ restrictedTagError()

◆ showTagEditingUI()

◆ tagDescription()

◆ tagLongDescriptionMessage()

◆ tagShortDescriptionMessage()

◆ tagUsageStatistics()

◆ truncateTagDescription()

◆ undefineTag()

◆ updateTags()

◆ updateTagsWithChecks()

Member Data Documentation

◆ $definedSoftwareTags

◆ MAX_DELETE_USES