ChangeTags.php

Go to the documentation of this file.

<?php
use MediaWiki\MediaWikiServices;
use MediaWiki\Storage\NameTableAccessException;
use Wikimedia\Rdbms\Database;
use Wikimedia\Rdbms\IDatabase;

class ChangeTags {
    const MAX_DELETE_USES = 5000;

    private static $definedSoftwareTags = [
        'mw-contentmodelchange',
        'mw-new-redirect',
        'mw-removed-redirect',
        'mw-changed-redirect-target',
        'mw-blank',
        'mw-replace',
        'mw-rollback',
        'mw-undo',
    ];

    public static function getSoftwareTags( $all = false ) {
        global $wgSoftwareTags;
        $softwareTags = [];

        if ( !is_array( $wgSoftwareTags ) ) {
            wfWarn( 'wgSoftwareTags should be associative array of enabled tags.
            Please refer to documentation for the list of tags you can enable' );
            return $softwareTags;
        }

        $availableSoftwareTags = !$all ?
            array_keys( array_filter( $wgSoftwareTags ) ) :
            array_keys( $wgSoftwareTags );

        $softwareTags = array_intersect(
            $availableSoftwareTags,
            self::$definedSoftwareTags
        );

        return $softwareTags;
    }

    public static function formatSummaryRow( $tags, $page, IContextSource $context = null ) {
        if ( !$tags ) {
            return [ '', [] ];
        }
        if ( !$context ) {
            $context = RequestContext::getMain();
        }

        $classes = [];

        $tags = explode( ',', $tags );
        $displayTags = [];
        foreach ( $tags as $tag ) {
            if ( !$tag ) {
                continue;
            }
            $description = self::tagDescription( $tag, $context );
            if ( $description === false ) {
                continue;
            }
            $displayTags[] = Xml::tags(
                'span',
                [ 'class' => 'mw-tag-marker ' .
                                Sanitizer::escapeClass( "mw-tag-marker-$tag" ) ],
                $description
            );
            $classes[] = Sanitizer::escapeClass( "mw-tag-$tag" );
        }

        if ( !$displayTags ) {
            return [ '', [] ];
        }

        $markers = $context->msg( 'tag-list-wrapper' )
            ->numParams( count( $displayTags ) )
            ->rawParams( implode( ' ',  $displayTags ) )
            ->parse();
        $markers = Xml::tags( 'span', [ 'class' => 'mw-tag-markers' ], $markers );

        return [ $markers, $classes ];
    }

    public static function tagShortDescriptionMessage( $tag, MessageLocalizer $context ) {
        $msg = $context->msg( "tag-$tag" );
        if ( !$msg->exists() ) {
            // No such message
            return ( new RawMessage( '$1', [ Message::plaintextParam( $tag ) ] ) )
                // HACK MessageLocalizer doesn't have a way to set the right language on a RawMessage,
                // so extract the language from $msg and use that.
                // The language doesn't really matter, but we need to set it to avoid requesting
                // the user's language from session-less entry points (T227233)
                ->inLanguage( $msg->getLanguage() );

        }
        if ( $msg->isDisabled() ) {
            // The message exists but is disabled, hide the tag.
            return false;
        }

        // Message exists and isn't disabled, use it.
        return $msg;
    }

    public static function tagDescription( $tag, MessageLocalizer $context ) {
        $msg = self::tagShortDescriptionMessage( $tag, $context );
        return $msg ? $msg->parse() : false;
    }

    public static function tagLongDescriptionMessage( $tag, MessageLocalizer $context ) {
        $msg = $context->msg( "tag-$tag-description" );
        if ( !$msg->exists() ) {
            return false;
        }
        if ( $msg->isDisabled() ) {
            // The message exists but is disabled, hide the description.
            return false;
        }

        // Message exists and isn't disabled, use it.
        return $msg;
    }

    public static function truncateTagDescription( $tag, $length, IContextSource $context ) {
        // FIXME: Make this accept MessageLocalizer and Language instead of IContextSource

        $originalDesc = self::tagLongDescriptionMessage( $tag, $context );
        // If there is no tag description, return empty string
        if ( !$originalDesc ) {
            return '';
        }

        $taglessDesc = Sanitizer::stripAllTags( $originalDesc->parse() );

        return $context->getLanguage()->truncateForVisual( $taglessDesc, $length );
    }

    public static function addTags( $tags, $rc_id = null, $rev_id = null,
        $log_id = null, $params = null, RecentChange $rc = null
    ) {
        $result = self::updateTags( $tags, null, $rc_id, $rev_id, $log_id, $params, $rc );
        return (bool)$result[0];
    }

    public static function updateTags( $tagsToAdd, $tagsToRemove, &$rc_id = null,
        &$rev_id = null, &$log_id = null, $params = null, RecentChange $rc = null,
        User $user = null
    ) {
        $tagsToAdd = array_filter( (array)$tagsToAdd ); // Make sure we're submitting all tags...
        $tagsToRemove = array_filter( (array)$tagsToRemove );

        if ( !$rc_id && !$rev_id && !$log_id ) {
            throw new MWException( 'At least one of: RCID, revision ID, and log ID MUST be ' .
                'specified when adding or removing a tag from a change!' );
        }

        $dbw = wfGetDB( DB_MASTER );

        // Might as well look for rcids and so on.
        if ( !$rc_id ) {
            // Info might be out of date, somewhat fractionally, on replica DB.
            // LogEntry/LogPage and WikiPage match rev/log/rc timestamps,
            // so use that relation to avoid full table scans.
            if ( $log_id ) {
                $rc_id = $dbw->selectField(
                    [ 'logging', 'recentchanges' ],
                    'rc_id',
                    [
                        'log_id' => $log_id,
                        'rc_timestamp = log_timestamp',
                        'rc_logid = log_id'
                    ],
                    __METHOD__
                );
            } elseif ( $rev_id ) {
                $rc_id = $dbw->selectField(
                    [ 'revision', 'recentchanges' ],
                    'rc_id',
                    [
                        'rev_id' => $rev_id,
                        'rc_timestamp = rev_timestamp',
                        'rc_this_oldid = rev_id'
                    ],
                    __METHOD__
                );
            }
        } elseif ( !$log_id && !$rev_id ) {
            // Info might be out of date, somewhat fractionally, on replica DB.
            $log_id = $dbw->selectField(
                'recentchanges',
                'rc_logid',
                [ 'rc_id' => $rc_id ],
                __METHOD__
            );
            $rev_id = $dbw->selectField(
                'recentchanges',
                'rc_this_oldid',
                [ 'rc_id' => $rc_id ],
                __METHOD__
            );
        }

        if ( $log_id && !$rev_id ) {
            $rev_id = $dbw->selectField(
                'log_search',
                'ls_value',
                [ 'ls_field' => 'associated_rev_id', 'ls_log_id' => $log_id ],
                __METHOD__
            );
        } elseif ( !$log_id && $rev_id ) {
            $log_id = $dbw->selectField(
                'log_search',
                'ls_log_id',
                [ 'ls_field' => 'associated_rev_id', 'ls_value' => $rev_id ],
                __METHOD__
            );
        }

        $prevTags = self::getTags( $dbw, $rc_id, $rev_id, $log_id );

        // add tags
        $tagsToAdd = array_values( array_diff( $tagsToAdd, $prevTags ) );
        $newTags = array_unique( array_merge( $prevTags, $tagsToAdd ) );

        // remove tags
        $tagsToRemove = array_values( array_intersect( $tagsToRemove, $newTags ) );
        $newTags = array_values( array_diff( $newTags, $tagsToRemove ) );

        sort( $prevTags );
        sort( $newTags );
        if ( $prevTags == $newTags ) {
            return [ [], [], $prevTags ];
        }

        // insert a row into change_tag for each new tag
        $changeTagDefStore = MediaWikiServices::getInstance()->getChangeTagDefStore();
        if ( count( $tagsToAdd ) ) {
            $changeTagMapping = [];
            foreach ( $tagsToAdd as $tag ) {
                $changeTagMapping[$tag] = $changeTagDefStore->acquireId( $tag );
            }
            $fname = __METHOD__;
            // T207881: update the counts at the end of the transaction
            $dbw->onTransactionPreCommitOrIdle( function () use ( $dbw, $tagsToAdd, $fname ) {
                $dbw->update(
                    'change_tag_def',
                    [ 'ctd_count = ctd_count + 1' ],
                    [ 'ctd_name' => $tagsToAdd ],
                    $fname
                );
            } );

            $tagsRows = [];
            foreach ( $tagsToAdd as $tag ) {
                // Filter so we don't insert NULLs as zero accidentally.
                // Keep in mind that $rc_id === null means "I don't care/know about the
                // rc_id, just delete $tag on this revision/log entry". It doesn't
                // mean "only delete tags on this revision/log WHERE rc_id IS NULL".
                $tagsRows[] = array_filter(
                    [
                        'ct_rc_id' => $rc_id,
                        'ct_log_id' => $log_id,
                        'ct_rev_id' => $rev_id,
                        'ct_params' => $params,
                        'ct_tag_id' => $changeTagMapping[$tag] ?? null,
                    ]
                );

            }

            $dbw->insert( 'change_tag', $tagsRows, __METHOD__, [ 'IGNORE' ] );
        }

        // delete from change_tag
        if ( count( $tagsToRemove ) ) {
            $fname = __METHOD__;
            foreach ( $tagsToRemove as $tag ) {
                $conds = array_filter(
                    [
                        'ct_rc_id' => $rc_id,
                        'ct_log_id' => $log_id,
                        'ct_rev_id' => $rev_id,
                        'ct_tag_id' => $changeTagDefStore->getId( $tag ),
                    ]
                );
                $dbw->delete( 'change_tag', $conds, __METHOD__ );
                if ( $dbw->affectedRows() ) {
                    // T207881: update the counts at the end of the transaction
                    $dbw->onTransactionPreCommitOrIdle( function () use ( $dbw, $tag, $fname ) {
                        $dbw->update(
                            'change_tag_def',
                            [ 'ctd_count = ctd_count - 1' ],
                            [ 'ctd_name' => $tag ],
                            $fname
                        );

                        $dbw->delete(
                            'change_tag_def',
                            [ 'ctd_name' => $tag, 'ctd_count' => 0, 'ctd_user_defined' => 0 ],
                            $fname
                        );
                    } );
                }
            }
        }

        Hooks::run( 'ChangeTagsAfterUpdateTags', [ $tagsToAdd, $tagsToRemove, $prevTags,
            $rc_id, $rev_id, $log_id, $params, $rc, $user ] );

        return [ $tagsToAdd, $tagsToRemove, $prevTags ];
    }

    public static function getTags( IDatabase $db, $rc_id = null, $rev_id = null, $log_id = null ) {
        $conds = array_filter(
            [
                'ct_rc_id' => $rc_id,
                'ct_rev_id' => $rev_id,
                'ct_log_id' => $log_id,
            ]
        );

        $tagIds = $db->selectFieldValues(
            'change_tag',
            'ct_tag_id',
            $conds,
            __METHOD__
        );

        $tags = [];
        $changeTagDefStore = MediaWikiServices::getInstance()->getChangeTagDefStore();
        foreach ( $tagIds as $tagId ) {
            $tags[] = $changeTagDefStore->getName( (int)$tagId );
        }

        return $tags;
    }

    protected static function restrictedTagError( $msgOne, $msgMulti, $tags ) {
        $lang = RequestContext::getMain()->getLanguage();
        $count = count( $tags );
        return Status::newFatal( ( $count > 1 ) ? $msgMulti : $msgOne,
            $lang->commaList( $tags ), $count );
    }

    public static function canAddTagsAccompanyingChange( array $tags, User $user = null ) {
        if ( !is_null( $user ) ) {
            if ( !$user->isAllowed( 'applychangetags' ) ) {
                return Status::newFatal( 'tags-apply-no-permission' );
            } elseif ( $user->getBlock() ) {
                // @TODO Ensure that the block does not apply to the `applychangetags`
                //       right.
                return Status::newFatal( 'tags-apply-blocked', $user->getName() );
            }
        }

        // to be applied, a tag has to be explicitly defined
        $allowedTags = self::listExplicitlyDefinedTags();
        Hooks::run( 'ChangeTagsAllowedAdd', [ &$allowedTags, $tags, $user ] );
        $disallowedTags = array_diff( $tags, $allowedTags );
        if ( $disallowedTags ) {
            return self::restrictedTagError( 'tags-apply-not-allowed-one',
                'tags-apply-not-allowed-multi', $disallowedTags );
        }

        return Status::newGood();
    }

    public static function addTagsAccompanyingChangeWithChecks(
        array $tags, $rc_id, $rev_id, $log_id, $params, User $user
    ) {
        // are we allowed to do this?
        $result = self::canAddTagsAccompanyingChange( $tags, $user );
        if ( !$result->isOK() ) {
            $result->value = null;
            return $result;
        }

        // do it!
        self::addTags( $tags, $rc_id, $rev_id, $log_id, $params );

        return Status::newGood( true );
    }

    public static function canUpdateTags( array $tagsToAdd, array $tagsToRemove,
        User $user = null
    ) {
        if ( !is_null( $user ) ) {
            if ( !$user->isAllowed( 'changetags' ) ) {
                return Status::newFatal( 'tags-update-no-permission' );
            } elseif ( $user->getBlock() ) {
                // @TODO Ensure that the block does not apply to the `changetags`
                //       right.
                return Status::newFatal( 'tags-update-blocked', $user->getName() );
            }
        }

        if ( $tagsToAdd ) {
            // to be added, a tag has to be explicitly defined
            // @todo Allow extensions to define tags that can be applied by users...
            $explicitlyDefinedTags = self::listExplicitlyDefinedTags();
            $diff = array_diff( $tagsToAdd, $explicitlyDefinedTags );
            if ( $diff ) {
                return self::restrictedTagError( 'tags-update-add-not-allowed-one',
                    'tags-update-add-not-allowed-multi', $diff );
            }
        }

        if ( $tagsToRemove ) {
            // to be removed, a tag must not be defined by an extension, or equivalently it
            // has to be either explicitly defined or not defined at all
            // (assuming no edge case of a tag both explicitly-defined and extension-defined)
            $softwareDefinedTags = self::listSoftwareDefinedTags();
            $intersect = array_intersect( $tagsToRemove, $softwareDefinedTags );
            if ( $intersect ) {
                return self::restrictedTagError( 'tags-update-remove-not-allowed-one',
                    'tags-update-remove-not-allowed-multi', $intersect );
            }
        }

        return Status::newGood();
    }

    public static function updateTagsWithChecks( $tagsToAdd, $tagsToRemove,
        $rc_id, $rev_id, $log_id, $params, $reason, User $user
    ) {
        if ( is_null( $tagsToAdd ) ) {
            $tagsToAdd = [];
        }
        if ( is_null( $tagsToRemove ) ) {
            $tagsToRemove = [];
        }
        if ( !$tagsToAdd && !$tagsToRemove ) {
            // no-op, don't bother
            return Status::newGood( (object)[
                'logId' => null,
                'addedTags' => [],
                'removedTags' => [],
            ] );
        }

        // are we allowed to do this?
        $result = self::canUpdateTags( $tagsToAdd, $tagsToRemove, $user );
        if ( !$result->isOK() ) {
            $result->value = null;
            return $result;
        }

        // basic rate limiting
        if ( $user->pingLimiter( 'changetag' ) ) {
            return Status::newFatal( 'actionthrottledtext' );
        }

        // do it!
        list( $tagsAdded, $tagsRemoved, $initialTags ) = self::updateTags( $tagsToAdd,
            $tagsToRemove, $rc_id, $rev_id, $log_id, $params, null, $user );
        if ( !$tagsAdded && !$tagsRemoved ) {
            // no-op, don't log it
            return Status::newGood( (object)[
                'logId' => null,
                'addedTags' => [],
                'removedTags' => [],
            ] );
        }

        // log it
        $logEntry = new ManualLogEntry( 'tag', 'update' );
        $logEntry->setPerformer( $user );
        $logEntry->setComment( $reason );

        // find the appropriate target page
        if ( $rev_id ) {
            $rev = Revision::newFromId( $rev_id );
            if ( $rev ) {
                $logEntry->setTarget( $rev->getTitle() );
            }
        } elseif ( $log_id ) {
            // This function is from revision deletion logic and has nothing to do with
            // change tags, but it appears to be the only other place in core where we
            // perform logged actions on log items.
            $logEntry->setTarget( RevDelLogList::suggestTarget( null, [ $log_id ] ) );
        }

        if ( !$logEntry->getTarget() ) {
            // target is required, so we have to set something
            $logEntry->setTarget( SpecialPage::getTitleFor( 'Tags' ) );
        }

        $logParams = [
            '4::revid' => $rev_id,
            '5::logid' => $log_id,
            '6:list:tagsAdded' => $tagsAdded,
            '7:number:tagsAddedCount' => count( $tagsAdded ),
            '8:list:tagsRemoved' => $tagsRemoved,
            '9:number:tagsRemovedCount' => count( $tagsRemoved ),
            'initialTags' => $initialTags,
        ];
        $logEntry->setParameters( $logParams );
        $logEntry->setRelations( [ 'Tag' => array_merge( $tagsAdded, $tagsRemoved ) ] );

        $dbw = wfGetDB( DB_MASTER );
        $logId = $logEntry->insert( $dbw );
        // Only send this to UDP, not RC, similar to patrol events
        $logEntry->publish( $logId, 'udp' );

        return Status::newGood( (object)[
            'logId' => $logId,
            'addedTags' => $tagsAdded,
            'removedTags' => $tagsRemoved,
        ] );
    }

    public static function modifyDisplayQuery( &$tables, &$fields, &$conds,
        &$join_conds, &$options, $filter_tag = ''
    ) {
        global $wgUseTagFilter;

        // Normalize to arrays
        $tables = (array)$tables;
        $fields = (array)$fields;
        $conds = (array)$conds;
        $options = (array)$options;

        $fields['ts_tags'] = self::makeTagSummarySubquery( $tables );

        // Figure out which ID field to use
        if ( in_array( 'recentchanges', $tables ) ) {
            $join_cond = 'ct_rc_id=rc_id';
        } elseif ( in_array( 'logging', $tables ) ) {
            $join_cond = 'ct_log_id=log_id';
        } elseif ( in_array( 'revision', $tables ) ) {
            $join_cond = 'ct_rev_id=rev_id';
        } elseif ( in_array( 'archive', $tables ) ) {
            $join_cond = 'ct_rev_id=ar_rev_id';
        } else {
            throw new MWException( 'Unable to determine appropriate JOIN condition for tagging.' );
        }

        if ( $wgUseTagFilter && $filter_tag ) {
            // Somebody wants to filter on a tag.
            // Add an INNER JOIN on change_tag

            $tables[] = 'change_tag';
            $join_conds['change_tag'] = [ 'JOIN', $join_cond ];
            $filterTagIds = [];
            $changeTagDefStore = MediaWikiServices::getInstance()->getChangeTagDefStore();
            foreach ( (array)$filter_tag as $filterTagName ) {
                try {
                    $filterTagIds[] = $changeTagDefStore->getId( $filterTagName );
                } catch ( NameTableAccessException $exception ) {
                    // Return nothing.
                    $conds[] = '0';
                    break;
                }
            }

            if ( $filterTagIds !== [] ) {
                $conds['ct_tag_id'] = $filterTagIds;
            }

            if (
                is_array( $filter_tag ) && count( $filter_tag ) > 1 &&
                !in_array( 'DISTINCT', $options )
            ) {
                $options[] = 'DISTINCT';
            }
        }
    }

    public static function makeTagSummarySubquery( $tables ) {
        // Normalize to arrays
        $tables = (array)$tables;

        // Figure out which ID field to use
        if ( in_array( 'recentchanges', $tables ) ) {
            $join_cond = 'ct_rc_id=rc_id';
        } elseif ( in_array( 'logging', $tables ) ) {
            $join_cond = 'ct_log_id=log_id';
        } elseif ( in_array( 'revision', $tables ) ) {
            $join_cond = 'ct_rev_id=rev_id';
        } elseif ( in_array( 'archive', $tables ) ) {
            $join_cond = 'ct_rev_id=ar_rev_id';
        } else {
            throw new MWException( 'Unable to determine appropriate JOIN condition for tagging.' );
        }

        $tagTables = [ 'change_tag', 'change_tag_def' ];
        $join_cond_ts_tags = [ 'change_tag_def' => [ 'JOIN', 'ct_tag_id=ctd_id' ] ];
        $field = 'ctd_name';

        return wfGetDB( DB_REPLICA )->buildGroupConcatField(
            ',', $tagTables, $field, $join_cond, $join_cond_ts_tags
        );
    }

    public static function buildTagFilterSelector(
        $selected = '', $ooui = false, IContextSource $context = null
    ) {
        if ( !$context ) {
            $context = RequestContext::getMain();
        }

        $config = $context->getConfig();
        if ( !$config->get( 'UseTagFilter' ) || !count( self::listDefinedTags() ) ) {
            return [];
        }

        $data = [
            Html::rawElement(
                'label',
                [ 'for' => 'tagfilter' ],
                $context->msg( 'tag-filter' )->parse()
            )
        ];

        if ( $ooui ) {
            $data[] = new OOUI\TextInputWidget( [
                'id' => 'tagfilter',
                'name' => 'tagfilter',
                'value' => $selected,
                'classes' => 'mw-tagfilter-input',
            ] );
        } else {
            $data[] = Xml::input(
                'tagfilter',
                20,
                $selected,
                [ 'class' => 'mw-tagfilter-input mw-ui-input mw-ui-input-inline', 'id' => 'tagfilter' ]
            );
        }

        return $data;
    }

    public static function defineTag( $tag ) {
        $dbw = wfGetDB( DB_MASTER );
        $tagDef = [
            'ctd_name' => $tag,
            'ctd_user_defined' => 1,
            'ctd_count' => 0
        ];
        $dbw->upsert(
            'change_tag_def',
            $tagDef,
            [ 'ctd_name' ],
            [ 'ctd_user_defined' => 1 ],
            __METHOD__
        );

        // clear the memcache of defined tags
        self::purgeTagCacheAll();
    }

    public static function undefineTag( $tag ) {
        $dbw = wfGetDB( DB_MASTER );

        $dbw->update(
            'change_tag_def',
            [ 'ctd_user_defined' => 0 ],
            [ 'ctd_name' => $tag ],
            __METHOD__
        );

        $dbw->delete(
            'change_tag_def',
            [ 'ctd_name' => $tag, 'ctd_count' => 0 ],
            __METHOD__
        );

        // clear the memcache of defined tags
        self::purgeTagCacheAll();
    }

    protected static function logTagManagementAction( $action, $tag, $reason,
        User $user, $tagCount = null, array $logEntryTags = []
    ) {
        $dbw = wfGetDB( DB_MASTER );

        $logEntry = new ManualLogEntry( 'managetags', $action );
        $logEntry->setPerformer( $user );
        // target page is not relevant, but it has to be set, so we just put in
        // the title of Special:Tags
        $logEntry->setTarget( Title::newFromText( 'Special:Tags' ) );
        $logEntry->setComment( $reason );

        $params = [ '4::tag' => $tag ];
        if ( !is_null( $tagCount ) ) {
            $params['5:number:count'] = $tagCount;
        }
        $logEntry->setParameters( $params );
        $logEntry->setRelations( [ 'Tag' => $tag ] );
        $logEntry->setTags( $logEntryTags );

        $logId = $logEntry->insert( $dbw );
        $logEntry->publish( $logId );
        return $logId;
    }

    public static function canActivateTag( $tag, User $user = null ) {
        if ( !is_null( $user ) ) {
            if ( !$user->isAllowed( 'managechangetags' ) ) {
                return Status::newFatal( 'tags-manage-no-permission' );
            } elseif ( $user->getBlock() ) {
                // @TODO Ensure that the block does not apply to the `managechangetags`
                //       right.
                return Status::newFatal( 'tags-manage-blocked', $user->getName() );
            }
        }

        // defined tags cannot be activated (a defined tag is either extension-
        // defined, in which case the extension chooses whether or not to active it;
        // or user-defined, in which case it is considered active)
        $definedTags = self::listDefinedTags();
        if ( in_array( $tag, $definedTags ) ) {
            return Status::newFatal( 'tags-activate-not-allowed', $tag );
        }

        // non-existing tags cannot be activated
        $tagUsage = self::tagUsageStatistics();
        if ( !isset( $tagUsage[$tag] ) ) { // we already know the tag is undefined
            return Status::newFatal( 'tags-activate-not-found', $tag );
        }

        return Status::newGood();
    }

    public static function activateTagWithChecks( $tag, $reason, User $user,
        $ignoreWarnings = false, array $logEntryTags = []
    ) {
        // are we allowed to do this?
        $result = self::canActivateTag( $tag, $user );
        if ( $ignoreWarnings ? !$result->isOK() : !$result->isGood() ) {
            $result->value = null;
            return $result;
        }

        // do it!
        self::defineTag( $tag );

        // log it
        $logId = self::logTagManagementAction( 'activate', $tag, $reason, $user,
            null, $logEntryTags );

        return Status::newGood( $logId );
    }

    public static function canDeactivateTag( $tag, User $user = null ) {
        if ( !is_null( $user ) ) {
            if ( !$user->isAllowed( 'managechangetags' ) ) {
                return Status::newFatal( 'tags-manage-no-permission' );
            } elseif ( $user->getBlock() ) {
                // @TODO Ensure that the block does not apply to the `managechangetags`
                //       right.
                return Status::newFatal( 'tags-manage-blocked', $user->getName() );
            }
        }

        // only explicitly-defined tags can be deactivated
        $explicitlyDefinedTags = self::listExplicitlyDefinedTags();
        if ( !in_array( $tag, $explicitlyDefinedTags ) ) {
            return Status::newFatal( 'tags-deactivate-not-allowed', $tag );
        }
        return Status::newGood();
    }

    public static function deactivateTagWithChecks( $tag, $reason, User $user,
        $ignoreWarnings = false, array $logEntryTags = []
    ) {
        // are we allowed to do this?
        $result = self::canDeactivateTag( $tag, $user );
        if ( $ignoreWarnings ? !$result->isOK() : !$result->isGood() ) {
            $result->value = null;
            return $result;
        }

        // do it!
        self::undefineTag( $tag );

        // log it
        $logId = self::logTagManagementAction( 'deactivate', $tag, $reason, $user,
            null, $logEntryTags );

        return Status::newGood( $logId );
    }

    public static function isTagNameValid( $tag ) {
        // no empty tags
        if ( $tag === '' ) {
            return Status::newFatal( 'tags-create-no-name' );
        }

        // tags cannot contain commas (used to be used as a delimiter in tag_summary table),
        // pipe (used as a delimiter between multiple tags in
        // SpecialRecentchanges and friends), or slashes (would break tag description messages in
        // MediaWiki namespace)
        if ( strpos( $tag, ',' ) !== false || strpos( $tag, '|' ) !== false
            || strpos( $tag, '/' ) !== false ) {
            return Status::newFatal( 'tags-create-invalid-chars' );
        }

        // could the MediaWiki namespace description messages be created?
        $title = Title::makeTitleSafe( NS_MEDIAWIKI, "Tag-$tag-description" );
        if ( is_null( $title ) ) {
            return Status::newFatal( 'tags-create-invalid-title-chars' );
        }

        return Status::newGood();
    }

    public static function canCreateTag( $tag, User $user = null ) {
        if ( !is_null( $user ) ) {
            if ( !$user->isAllowed( 'managechangetags' ) ) {
                return Status::newFatal( 'tags-manage-no-permission' );
            } elseif ( $user->getBlock() ) {
                // @TODO Ensure that the block does not apply to the `managechangetags`
                //       right.
                return Status::newFatal( 'tags-manage-blocked', $user->getName() );
            }
        }

        $status = self::isTagNameValid( $tag );
        if ( !$status->isGood() ) {
            return $status;
        }

        // does the tag already exist?
        $tagUsage = self::tagUsageStatistics();
        if ( isset( $tagUsage[$tag] ) || in_array( $tag, self::listDefinedTags() ) ) {
            return Status::newFatal( 'tags-create-already-exists', $tag );
        }

        // check with hooks
        $canCreateResult = Status::newGood();
        Hooks::run( 'ChangeTagCanCreate', [ $tag, $user, &$canCreateResult ] );
        return $canCreateResult;
    }

    public static function createTagWithChecks( $tag, $reason, User $user,
        $ignoreWarnings = false, array $logEntryTags = []
    ) {
        // are we allowed to do this?
        $result = self::canCreateTag( $tag, $user );
        if ( $ignoreWarnings ? !$result->isOK() : !$result->isGood() ) {
            $result->value = null;
            return $result;
        }

        // do it!
        self::defineTag( $tag );

        // log it
        $logId = self::logTagManagementAction( 'create', $tag, $reason, $user,
            null, $logEntryTags );

        return Status::newGood( $logId );
    }

    public static function deleteTagEverywhere( $tag ) {
        $dbw = wfGetDB( DB_MASTER );
        $dbw->startAtomic( __METHOD__ );

        // fetch tag id, this must be done before calling undefineTag(), see T225564
        $tagId = MediaWikiServices::getInstance()->getChangeTagDefStore()->getId( $tag );

        // set ctd_user_defined = 0
        self::undefineTag( $tag );

        // delete from change_tag
        $dbw->delete( 'change_tag', [ 'ct_tag_id' => $tagId ], __METHOD__ );
        $dbw->delete( 'change_tag_def', [ 'ctd_name' => $tag ], __METHOD__ );
        $dbw->endAtomic( __METHOD__ );

        // give extensions a chance
        $status = Status::newGood();
        Hooks::run( 'ChangeTagAfterDelete', [ $tag, &$status ] );
        // let's not allow error results, as the actual tag deletion succeeded
        if ( !$status->isOK() ) {
            wfDebug( 'ChangeTagAfterDelete error condition downgraded to warning' );
            $status->setOK( true );
        }

        // clear the memcache of defined tags
        self::purgeTagCacheAll();

        return $status;
    }

    public static function canDeleteTag( $tag, User $user = null ) {
        $tagUsage = self::tagUsageStatistics();

        if ( !is_null( $user ) ) {
            if ( !$user->isAllowed( 'deletechangetags' ) ) {
                return Status::newFatal( 'tags-delete-no-permission' );
            } elseif ( $user->getBlock() ) {
                // @TODO Ensure that the block does not apply to the `deletechangetags`
                //       right.
                return Status::newFatal( 'tags-manage-blocked', $user->getName() );
            }
        }

        if ( !isset( $tagUsage[$tag] ) && !in_array( $tag, self::listDefinedTags() ) ) {
            return Status::newFatal( 'tags-delete-not-found', $tag );
        }

        if ( isset( $tagUsage[$tag] ) && $tagUsage[$tag] > self::MAX_DELETE_USES ) {
            return Status::newFatal( 'tags-delete-too-many-uses', $tag, self::MAX_DELETE_USES );
        }

        $softwareDefined = self::listSoftwareDefinedTags();
        if ( in_array( $tag, $softwareDefined ) ) {
            // extension-defined tags can't be deleted unless the extension
            // specifically allows it
            $status = Status::newFatal( 'tags-delete-not-allowed' );
        } else {
            // user-defined tags are deletable unless otherwise specified
            $status = Status::newGood();
        }

        Hooks::run( 'ChangeTagCanDelete', [ $tag, $user, &$status ] );
        return $status;
    }

    public static function deleteTagWithChecks( $tag, $reason, User $user,
        $ignoreWarnings = false, array $logEntryTags = []
    ) {
        // are we allowed to do this?
        $result = self::canDeleteTag( $tag, $user );
        if ( $ignoreWarnings ? !$result->isOK() : !$result->isGood() ) {
            $result->value = null;
            return $result;
        }

        // store the tag usage statistics
        $tagUsage = self::tagUsageStatistics();
        $hitcount = $tagUsage[$tag] ?? 0;

        // do it!
        $deleteResult = self::deleteTagEverywhere( $tag );
        if ( !$deleteResult->isOK() ) {
            return $deleteResult;
        }

        // log it
        $logId = self::logTagManagementAction( 'delete', $tag, $reason, $user,
            $hitcount, $logEntryTags );

        $deleteResult->value = $logId;
        return $deleteResult;
    }

    public static function listSoftwareActivatedTags() {
        // core active tags
        $tags = self::getSoftwareTags();
        if ( !Hooks::isRegistered( 'ChangeTagsListActive' ) ) {
            return $tags;
        }
        $cache = MediaWikiServices::getInstance()->getMainWANObjectCache();
        return $cache->getWithSetCallback(
            $cache->makeKey( 'active-tags' ),
            WANObjectCache::TTL_MINUTE * 5,
            function ( $oldValue, &$ttl, array &$setOpts ) use ( $tags ) {
                $setOpts += Database::getCacheSetOptions( wfGetDB( DB_REPLICA ) );

                // Ask extensions which tags they consider active
                Hooks::run( 'ChangeTagsListActive', [ &$tags ] );
                return $tags;
            },
            [
                'checkKeys' => [ $cache->makeKey( 'active-tags' ) ],
                'lockTSE' => WANObjectCache::TTL_MINUTE * 5,
                'pcTTL' => WANObjectCache::TTL_PROC_LONG
            ]
        );
    }

    public static function listDefinedTags() {
        $tags1 = self::listExplicitlyDefinedTags();
        $tags2 = self::listSoftwareDefinedTags();
        return array_values( array_unique( array_merge( $tags1, $tags2 ) ) );
    }

    public static function listExplicitlyDefinedTags() {
        $fname = __METHOD__;

        $cache = MediaWikiServices::getInstance()->getMainWANObjectCache();
        return $cache->getWithSetCallback(
            $cache->makeKey( 'valid-tags-db' ),
            WANObjectCache::TTL_MINUTE * 5,
            function ( $oldValue, &$ttl, array &$setOpts ) use ( $fname ) {
                $dbr = wfGetDB( DB_REPLICA );

                $setOpts += Database::getCacheSetOptions( $dbr );

                $tags = $dbr->selectFieldValues(
                    'change_tag_def',
                    'ctd_name',
                    [ 'ctd_user_defined' => 1 ],
                    $fname
                );

                return array_filter( array_unique( $tags ) );
            },
            [
                'checkKeys' => [ $cache->makeKey( 'valid-tags-db' ) ],
                'lockTSE' => WANObjectCache::TTL_MINUTE * 5,
                'pcTTL' => WANObjectCache::TTL_PROC_LONG
            ]
        );
    }

    public static function listSoftwareDefinedTags() {
        // core defined tags
        $tags = self::getSoftwareTags( true );
        if ( !Hooks::isRegistered( 'ListDefinedTags' ) ) {
            return $tags;
        }
        $cache = MediaWikiServices::getInstance()->getMainWANObjectCache();
        return $cache->getWithSetCallback(
            $cache->makeKey( 'valid-tags-hook' ),
            WANObjectCache::TTL_MINUTE * 5,
            function ( $oldValue, &$ttl, array &$setOpts ) use ( $tags ) {
                $setOpts += Database::getCacheSetOptions( wfGetDB( DB_REPLICA ) );

                Hooks::run( 'ListDefinedTags', [ &$tags ] );
                return array_filter( array_unique( $tags ) );
            },
            [
                'checkKeys' => [ $cache->makeKey( 'valid-tags-hook' ) ],
                'lockTSE' => WANObjectCache::TTL_MINUTE * 5,
                'pcTTL' => WANObjectCache::TTL_PROC_LONG
            ]
        );
    }

    public static function purgeTagCacheAll() {
        $cache = MediaWikiServices::getInstance()->getMainWANObjectCache();

        $cache->touchCheckKey( $cache->makeKey( 'active-tags' ) );
        $cache->touchCheckKey( $cache->makeKey( 'valid-tags-db' ) );
        $cache->touchCheckKey( $cache->makeKey( 'valid-tags-hook' ) );
        $cache->touchCheckKey( $cache->makeKey( 'tags-usage-statistics' ) );

        MediaWikiServices::getInstance()->getChangeTagDefStore()->reloadMap();
    }

    public static function tagUsageStatistics() {
        $fname = __METHOD__;

        $cache = MediaWikiServices::getInstance()->getMainWANObjectCache();
        return $cache->getWithSetCallback(
            $cache->makeKey( 'tags-usage-statistics' ),
            WANObjectCache::TTL_MINUTE * 5,
            function ( $oldValue, &$ttl, array &$setOpts ) use ( $fname ) {
                $dbr = wfGetDB( DB_REPLICA );
                $res = $dbr->select(
                    'change_tag_def',
                    [ 'ctd_name', 'ctd_count' ],
                    [],
                    $fname,
                    [ 'ORDER BY' => 'ctd_count DESC' ]
                );

                $out = [];
                foreach ( $res as $row ) {
                    $out[$row->ctd_name] = $row->ctd_count;
                }

                return $out;
            },
            [
                'checkKeys' => [ $cache->makeKey( 'tags-usage-statistics' ) ],
                'lockTSE' => WANObjectCache::TTL_MINUTE * 5,
                'pcTTL' => WANObjectCache::TTL_PROC_LONG
            ]
        );
    }

    public static function showTagEditingUI( User $user ) {
        return $user->isAllowed( 'changetags' ) && (bool)self::listExplicitlyDefinedTags();
    }
}