Read-write access to the change_tags table. More...

Public Member Functions
	__construct (IConnectionProvider $dbProvider, NameTableStore $changeTagDefStore, WANObjectCache $wanCache, HookContainer $hookContainer, LoggerInterface $logger, UserFactory $userFactory, ServiceOptions $options, string\|false $wiki=false)

	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.

	addTagsToDisplayQuery (SelectQueryBuilder $queryBuilder, string $table, Authority $performer, string\|array $filterTag='', bool $exclude=false)
	Applies all tags-related changes to a query builder object.

	canViewTag (string $tag, Authority $performer)
	Determine whether the given `Authority` may view the provided tag.

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

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

	filterViewableTags (array $tags, Authority $performer)
	Filter a list of tag names down to those the performer may view.

	filterViewableTagsForPerformer (array $tags, ?Authority $performer)

	getCoreDefinedTags ()
	Expose the codebase-level defined software tags.

	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.

	getTagIdsFromNames ( $tagNames)
	Get tag IDs given a list of tag names.

	getTags (IReadableDatabase $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.

	getTagsWithData (IReadableDatabase $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, along with any data stored with the tag.

	getViewableTags (IReadableDatabase $db, Authority $performer, ?int $recentChangeId=null, ?int $revisionId=null, ?int $logId=null)
	Return all the tags viewable by the provided `Authority` that are associated with the given recent change ID, revision ID, and/or log entry ID.

	isRestrictedTag (string $tag)
	Returns whether the given tag name is a restricted (private-prefixed) tag.

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

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

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

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

	logTagManagementAction (string $action, string $tag, string $reason, UserIdentity $user, $tagCount=null, array $logEntryTags=[])
	Writes a tag action into the tag management log.

	makeTagSummarySubquery ( $tables, ?Authority $performer=null)
	Make the tag summary subquery based on the given tables and return it.

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

	modifyDisplayQueryBuilder (SelectQueryBuilder $queryBuilder, $table, $filter_tag='', bool $exclude=false)
	Applies all tags-related changes to a query builder object.

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

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

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

	updateTags ( $tagsToAdd, $tagsToRemove, &$rc_id=null, &$rev_id=null, &$log_id=null, $params=null, ?RecentChange $rc=null, ?UserIdentity $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.

Public Attributes
const	CONSTRUCTOR_OPTIONS

const	DISPLAY_TABLE_ALIAS = 'changetagdisplay'

const string	PRIVATE_TAG_PREFIX = 'mw-private-'
	Reserved name prefix for rights-restricted change tags.

Detailed Description

Read-write access to the change_tags table.

This class also provides a limited functionality for querying tags on remote wikis.

Since: 1.41

Definition at line 43 of file ChangeTagsStore.php.

Constructor & Destructor Documentation

◆ __construct()

MediaWiki\ChangeTags\ChangeTagsStore::__construct	(	IConnectionProvider	$dbProvider,
		NameTableStore	$changeTagDefStore,
		WANObjectCache	$wanCache,
		HookContainer	$hookContainer,
		LoggerInterface	$logger,
		UserFactory	$userFactory,
		ServiceOptions	$options,
		string\|false	$wiki = false )

Definition at line 110 of file ChangeTagsStore.php.

References MediaWiki\Config\ServiceOptions\assertRequiredOptions().

Member Function Documentation

◆ addTags()

MediaWiki\ChangeTags\ChangeTagsStore::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.

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)

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

Definition at line 955 of file ChangeTagsStore.php.

◆ addTagsToDisplayQuery()

MediaWiki\ChangeTags\ChangeTagsStore::addTagsToDisplayQuery	(	SelectQueryBuilder	$queryBuilder,
		string	$table,
		Authority	$performer,
		string\|array	$filterTag = '',
		bool	$exclude = false )

Applies all tags-related changes to a query builder object.

Handles selecting tags, and filtering.

When querying table from a remote wiki, this function honors the local wiki's UseTagFilter configuration setting.

WARNING: If $filterTag contains more than one tag and $exclude is false, 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.

Since: 1.47

Parameters

SelectQueryBuilder	$queryBuilder	Query builder to add the join
string	$table	Table name. Must be either of 'recentchanges', 'logging', 'revision', or 'archive'
Authority	$performer	Viewer, for restricted-tag access checks
string \| array	$filterTag	Tag(s) to select on (OR)
bool	$exclude	If true, exclude tag(s) from $filterTag (NOR)

Definition at line 1116 of file ChangeTagsStore.php.

◆ canViewTag()

MediaWiki\ChangeTags\ChangeTagsStore::canViewTag	(	string	$tag,
		Authority	$performer )

Determine whether the given Authority may view the provided tag.

Since: 1.47

Definition at line 681 of file ChangeTagsStore.php.

◆ defineTag()

MediaWiki\ChangeTags\ChangeTagsStore::defineTag ( $tag )

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.

This operation is supported only for the local wiki.

Parameters

string $tag Tag to create

Since: 1.41

Definition at line 293 of file ChangeTagsStore.php.

◆ deleteTagEverywhere()

MediaWiki\ChangeTags\ChangeTagsStore::deleteTagEverywhere ( $tag )

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.

This operation is supported only for the local wiki.

Parameters

string $tag Tag to remove

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

Since: 1.41

Definition at line 405 of file ChangeTagsStore.php.

◆ filterViewableTags()

MediaWiki\ChangeTags\ChangeTagsStore::filterViewableTags	(	array	$tags,
		Authority	$performer )

Filter a list of tag names down to those the performer may view.

Does not query the database.

Since: 1.47

Parameters

string[]	$tags
Authority	$performer

Returns: string[]

Definition at line 703 of file ChangeTagsStore.php.

◆ filterViewableTagsForPerformer()

MediaWiki\ChangeTags\ChangeTagsStore::filterViewableTagsForPerformer	(	array	$tags,
		?Authority	$performer )

Access: internal: Transitional, until all callers pass a performer.

Like filterViewableTags(), but a null performer may view no restricted tags at all.

Parameters

string[]	$tags
Authority \| null	$performer

Returns: string[]

Definition at line 720 of file ChangeTagsStore.php.

◆ getCoreDefinedTags()

MediaWiki\ChangeTags\ChangeTagsStore::getCoreDefinedTags ( )

Expose the codebase-level defined software tags.

No filtering is available for this function.

Returns: array Array of all core-defined tags

Definition at line 169 of file ChangeTagsStore.php.

◆ getSoftwareTags()

MediaWiki\ChangeTags\ChangeTagsStore::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.

This operation is supported only for the local wiki.

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 141 of file ChangeTagsStore.php.

◆ getTagIdsFromNames()

MediaWiki\ChangeTags\ChangeTagsStore::getTagIdsFromNames ( $tagNames )

Get tag IDs given a list of tag names.

If any name is invalid, its ID will be omitted from the return value.

Since: 1.45

Parameters

string[] $tagNames

Returns: array<string,int>

Definition at line 625 of file ChangeTagsStore.php.

◆ getTags()

MediaWiki\ChangeTags\ChangeTagsStore::getTags	(	IReadableDatabase	$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.

Does not remove tags that the viewing user cannot see, use self::getViewableTags for that instead.

Parameters

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

Returns: string[]

Definition at line 576 of file ChangeTagsStore.php.

◆ getTagsWithData()

MediaWiki\ChangeTags\ChangeTagsStore::getTagsWithData	(	IReadableDatabase	$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, along with any data stored with the tag.

Does not remove tags that the viewing user cannot see, use self::filterViewableTags on the array keys to filter for tags that the user can see.

Parameters

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

Returns: string[] Tag name => data. Data format is tag-specific.

Since: 1.41

Definition at line 187 of file ChangeTagsStore.php.

◆ getViewableTags()

MediaWiki\ChangeTags\ChangeTagsStore::getViewableTags	(	IReadableDatabase	$db,
		Authority	$performer,
		?int	$recentChangeId = null,
		?int	$revisionId = null,
		?int	$logId = null )

Return all the tags viewable by the provided Authority that are associated with the given recent change ID, revision ID, and/or log entry ID.

To get all the tags use self::getTags instead.

Since: 1.47

Parameters

IReadableDatabase	$db
Authority	$performer
int \| null	$recentChangeId
int \| null	$revisionId
int \| null	$logId

Returns: string[]

Definition at line 594 of file ChangeTagsStore.php.

◆ isRestrictedTag()

MediaWiki\ChangeTags\ChangeTagsStore::isRestrictedTag ( string $tag )

Returns whether the given tag name is a restricted (private-prefixed) tag.

Since: 1.47

Definition at line 641 of file ChangeTagsStore.php.

◆ listDefinedTags()

MediaWiki\ChangeTags\ChangeTagsStore::listDefinedTags ( )

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

It returns a union of the results of listExplicitlyDefinedTags() and listSoftwareDefinedTags()

Returns: string[] Array of strings: tags

Definition at line 611 of file ChangeTagsStore.php.

◆ listExplicitlyDefinedTags()

MediaWiki\ChangeTags\ChangeTagsStore::listExplicitlyDefinedTags ( )

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 505 of file ChangeTagsStore.php.

References Wikimedia\Rdbms\IConnectionProvider\getReplicaDatabase().

◆ listSoftwareActivatedTags()

MediaWiki\ChangeTags\ChangeTagsStore::listSoftwareActivatedTags ( )

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

Returns: array

Since: 1.41

Definition at line 968 of file ChangeTagsStore.php.

References MediaWiki\HookContainer\HookRunner\onChangeTagsListActive().

◆ listSoftwareDefinedTags()

MediaWiki\ChangeTags\ChangeTagsStore::listSoftwareDefinedTags ( )

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 541 of file ChangeTagsStore.php.

References MediaWiki\HookContainer\HookRunner\onListDefinedTags().

◆ logTagManagementAction()

MediaWiki\ChangeTags\ChangeTagsStore::logTagManagementAction	(	string	$action,
		string	$tag,
		string	$reason,
		UserIdentity	$user,
			$tagCount = null,
		array	$logEntryTags = [] )

Writes a tag action into the tag management log.

This operation is supported only for the local wiki.

Parameters

string	$action
string	$tag
string	$reason
UserIdentity	$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.41

Definition at line 363 of file ChangeTagsStore.php.

◆ makeTagSummarySubquery()

MediaWiki\ChangeTags\ChangeTagsStore::makeTagSummarySubquery	(		$tables,
		?Authority	$performer = null )

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

Restricted tags (the mw-private- prefix) that the given performer may not view are excluded; a null performer excludes all of them.

Parameters

string \| array	$tables	Table names, see Database::select
Authority \| null	$performer	Viewer, for restricted-tag access checks. Null hides all restricted tags. (since 1.47); passing null is deprecated since 1.47

Returns: string tag summary subquery

Definition at line 231 of file ChangeTagsStore.php.

References wfDeprecatedMsg().

◆ modifyDisplayQuery()

MediaWiki\ChangeTags\ChangeTagsStore::modifyDisplayQuery	(	&	$tables,
		&	$fields,
		&	$conds,
		&	$join_conds,
		&	$options,
			$filter_tag = '',
		bool	$exclude = false )

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.

When querying table from a remote wiki, this function honors the local wiki's UseTagFilter configuration setting.

Restricted tags are always hidden from this method's output and cannot be filtered on; use addTagsToDisplayQuery() instead.

WARNING: If $filter_tag contains more than one tag and $exclude is false, 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.

Deprecated: since 1.41 use ChangeTagsStore::addTagsToDisplayQuery instead

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 \| false \| null	$filter_tag	Tag(s) to select on (OR)
bool	$exclude	If true, exclude tag(s) from $filter_tag (NOR)

Definition at line 1020 of file ChangeTagsStore.php.

References wfDeprecated().

◆ modifyDisplayQueryBuilder()

MediaWiki\ChangeTags\ChangeTagsStore::modifyDisplayQueryBuilder	(	SelectQueryBuilder	$queryBuilder,
			$table,
			$filter_tag = '',
		bool	$exclude = false )

Applies all tags-related changes to a query builder object.

Handles selecting tags, and filtering. Restricted tags are always hidden from this method's output; use addTagsToDisplayQuery() with an Authority instead.

Deprecated: since 1.47, use self::addTagsToDisplayQuery() instead

Parameters

SelectQueryBuilder	$queryBuilder	Query builder to add the join
string	$table	Table name. Must be either of 'recentchanges', 'logging', 'revision', or 'archive'
string \| array \| false \| null	$filter_tag	Tag(s) to select on (OR)
bool	$exclude	If true, exclude tag(s) from $filter_tag (NOR)

Definition at line 1196 of file ChangeTagsStore.php.

◆ purgeTagCacheAll()

MediaWiki\ChangeTags\ChangeTagsStore::purgeTagCacheAll ( )

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

Since: 1.41

Definition at line 450 of file ChangeTagsStore.php.

◆ tagUsageStatistics()

MediaWiki\ChangeTags\ChangeTagsStore::tagUsageStatistics ( )

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 465 of file ChangeTagsStore.php.

References Wikimedia\Rdbms\IConnectionProvider\getReplicaDatabase().

◆ undefineTag()

MediaWiki\ChangeTags\ChangeTagsStore::undefineTag ( $tag )

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.

This operation is supported only for the local wiki.

Parameters

string $tag Tag to remove

Since: 1.41

Definition at line 325 of file ChangeTagsStore.php.

◆ updateTags()

MediaWiki\ChangeTags\ChangeTagsStore::updateTags	(		$tagsToAdd,
			$tagsToRemove,
		&	$rc_id = null,
		&	$rev_id = null,
		&	$log_id = null,
			$params = null,
		?RecentChange	$rc = null,
		?UserIdentity	$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.

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.

This operation is supported only for the local wiki.

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
UserIdentity \| null	$user	Tagging user, in case the tagging is subsequent to the tagged action

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

Definition at line 758 of file ChangeTagsStore.php.

Member Data Documentation

◆ CONSTRUCTOR_OPTIONS

const MediaWiki\ChangeTags\ChangeTagsStore::CONSTRUCTOR_OPTIONS

Initial value:

= [
        MainConfigNames::SoftwareTags,
        MainConfigNames::UseTagFilter,
        MainConfigNames::RestrictedTagViewRights,
    ]

Access: internal: For use by ServiceWiring

Definition at line 60 of file ChangeTagsStore.php.

◆ DISPLAY_TABLE_ALIAS

const MediaWiki\ChangeTags\ChangeTagsStore::DISPLAY_TABLE_ALIAS = 'changetagdisplay'

Definition at line 55 of file ChangeTagsStore.php.

◆ PRIVATE_TAG_PREFIX

const string MediaWiki\ChangeTags\ChangeTagsStore::PRIVATE_TAG_PREFIX = 'mw-private-'

Reserved name prefix for rights-restricted change tags.

A tag whose name starts with this prefix cannot be defined by users and are only visible to users with the required right.

Access: internal: Use ChangeTagsStore::isRestrictedTag() to check if a tag is restricted. Only public for use by ChangeTags.

Definition at line 95 of file ChangeTagsStore.php.

Referenced by MediaWiki\ChangeTags\ChangeTags\isTagNameValid().

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

includes/ChangeTags/ChangeTagsStore.php

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ addTags()

◆ addTagsToDisplayQuery()

◆ canViewTag()

◆ defineTag()

◆ deleteTagEverywhere()

◆ filterViewableTags()

◆ filterViewableTagsForPerformer()

◆ getCoreDefinedTags()

◆ getSoftwareTags()

◆ getTagIdsFromNames()

◆ getTags()

◆ getTagsWithData()

◆ getViewableTags()

◆ isRestrictedTag()

◆ listDefinedTags()

◆ listExplicitlyDefinedTags()

◆ listSoftwareActivatedTags()

◆ listSoftwareDefinedTags()

◆ logTagManagementAction()

◆ makeTagSummarySubquery()

◆ modifyDisplayQuery()

◆ modifyDisplayQueryBuilder()

◆ purgeTagCacheAll()

◆ tagUsageStatistics()

◆ undefineTag()

◆ updateTags()

Member Data Documentation

◆ CONSTRUCTOR_OPTIONS

◆ DISPLAY_TABLE_ALIAS

◆ PRIVATE_TAG_PREFIX