ChangeTagsFormatter.php

Go to the documentation of this file.

<?php
namespace MediaWiki\ChangeTags;
 
use MediaWiki\Config\ServiceOptions;
use MediaWiki\Context\IContextSource;
use MediaWiki\Html\Html;
use MediaWiki\Language\LanguageFactory;
use MediaWiki\Language\LocalizationContext;
use MediaWiki\Language\MessageLocalizer;
use MediaWiki\Language\RawMessage;
use MediaWiki\MainConfigNames;
use MediaWiki\Message\Message;
use MediaWiki\Parser\Sanitizer;
use MediaWiki\Permissions\Authority;
use MediaWiki\Skin\Skin;
use OOUI\ComboBoxInputWidget;
use Wikimedia\ObjectCache\WANObjectCache;
 
class ChangeTagsFormatter {
 
    public const array CONSTRUCTOR_OPTIONS = [
        MainConfigNames::UseTagFilter,
    ];
 
    private const int TAG_DESC_CHARACTER_LIMIT = 120;
 
    public function __construct(
        private readonly ServiceOptions $options,
        private readonly ChangeTagsStore $changeTagsStore,
        private readonly WANObjectCache $cache,
        private readonly LanguageFactory $languageFactory,
    ) {
        $this->options->assertRequiredOptions( self::CONSTRUCTOR_OPTIONS );
    }
 
    public function formatTagsAsSummaryList(
        ?string $tags,
        MessageLocalizer $localizer,
        Authority $authority
    ): array {
        if ( $tags === '' || $tags === null ) {
            return [ '', [] ];
        }
 
        $classes = [];
 
        $tags = explode( ',', $tags );
        $tags = $this->changeTagsStore->filterViewableTags( $tags, $authority );
        $order = array_flip( $this->changeTagsStore->listDefinedTags() );
        usort( $tags, static function ( $a, $b ) use ( $order ) {
            return ( $order[ $a ] ?? INF ) <=> ( $order[ $b ] ?? INF );
        } );
 
        $displayTags = [];
        foreach ( $tags as $tag ) {
            if ( $tag === '' ) {
                continue;
            }
            $classes[] = Sanitizer::escapeClass( "mw-tag-$tag" );
            $description = $this->getTagDescription( $tag, $localizer );
            if ( $description === '' ) {
                continue;
            }
            $displayTags[] = Html::rawElement(
                'span',
                [ 'class' => 'mw-tag-marker ' . Sanitizer::escapeClass( "mw-tag-marker-$tag" ) ],
                $description
            );
        }
 
        if ( !$displayTags ) {
            return [ '', $classes ];
        }
 
        $markers = $localizer->msg( 'tag-list-wrapper' )
            ->numParams( count( $displayTags ) )
            ->rawParams( implode( ' ', $displayTags ) )
            ->parse();
        $markers = Html::rawElement( 'span', [ 'class' => 'mw-tag-markers' ], $markers );
 
        return [ $markers, $classes ];
    }
 
    public function getTagDescription( string $tag, MessageLocalizer $localizer ): string {
        $msg = $this->tagShortDescriptionMessage( $tag, $localizer );
        $link = $this->tagHelpLink( $tag, $localizer );
        if ( !$msg->isDisabled() && $link ) {
            $label = $msg->parse();
            // Avoid invalid HTML caused by link wrapping if the label already contains a link
            if ( !str_contains( $label, '<a ' ) ) {
                return Html::rawElement( 'a', [ 'href' => $link ], $label );
            }
        }
        return !$msg->isDisabled() ? $msg->parse() : '';
    }
 
    private function tagShortDescriptionMessage( string $tag, MessageLocalizer $messageLocalizer ): Message {
        $msg = $messageLocalizer->msg( "tag-$tag" );
        if ( !$msg->exists() ) {
            // No such message
            // Pass through ->msg(), even though it seems redundant, to avoid requesting
            // the user's language from session-less entry points (T227233)
            return $messageLocalizer->msg( new RawMessage( '$1', [ Message::plaintextParam( $tag ) ] ) );
        }
 
        return $msg;
    }
 
    private function tagHelpLink( string $tag, MessageLocalizer $context ): ?string {
        $msg = $context->msg( "tag-$tag-helppage" )->inContentLanguage();
        if ( !$msg->isDisabled() ) {
            return Skin::makeInternalOrExternalUrl( $msg->text() ) ?: null;
        }
        return null;
    }
 
    public function buildTagFilter(
        string $selected,
        string $format,
        IContextSource $context,
        bool $activeOnly = true,
        bool $useAllTags = true
    ): ?array {
        if (
            !$this->options->get( MainConfigNames::UseTagFilter ) ||
            !count( $this->changeTagsStore->listDefinedTags() )
        ) {
            return null;
        }
 
        $tags = $this->getChangeTagList(
            $context,
            $context->getAuthority(),
            $activeOnly,
            $useAllTags,
            true
        );
 
        $autocomplete = [];
        foreach ( $tags as $tagInfo ) {
            $autocomplete[ $tagInfo['label'] ] = $tagInfo['name'];
        }
 
        $data = [];
        $data[0] = Html::rawElement(
            'label',
            [ 'for' => 'tagfilter' ],
            $context->msg( 'tag-filter' )->parse()
        );
 
        if ( $format === 'ooui' ) {
            $options = Html::listDropdownOptionsOoui( $autocomplete );
 
            $data[1] = new ComboBoxInputWidget( [
                'id' => 'tagfilter',
                'name' => 'tagfilter',
                'value' => $selected,
                'classes' => 'mw-tagfilter-input',
                'options' => $options,
            ] );
        } else {
            $optionsHtml = '';
            foreach ( $autocomplete as $label => $name ) {
                $optionsHtml .= Html::element( 'option', [ 'value' => $name ], $label );
            }
            $datalistHtml = Html::rawElement( 'datalist', [ 'id' => 'tagfilter-datalist' ], $optionsHtml );
 
            $data[1] = Html::input(
                'tagfilter',
                $selected,
                'text',
                [
                    'class' => [ 'mw-tagfilter-input', 'cdx-text-input__input' => $format === 'codex' ],
                    'size' => 20,
                    'id' => 'tagfilter',
                    'list' => 'tagfilter-datalist',
                ]
            );
            if ( $format === 'codex' ) {
                $data[1] = Html::rawElement( 'div', [ 'class' => 'cdx-text-input' ], $data[1] );
            }
            $data[1] .= $datalistHtml;
        }
 
        return $data;
    }
 
    public function getChangeTagListSummary(
        LocalizationContext $localizationContext,
        Authority $authority,
        bool $activeOnly = true,
        bool $useAllTags = true
    ): array {
        if ( $useAllTags ) {
            $tagKeys = $this->changeTagsStore->listDefinedTags();
            $cacheKey = 'tags-list-summary';
        } else {
            $tagKeys = $this->changeTagsStore->getCoreDefinedTags();
            $cacheKey = 'core-software-tags-summary';
        }
 
        // if $tagHitCounts exists, check against it later to determine whether or not to omit tags
        $tagHitCounts = null;
        if ( $activeOnly ) {
            $tagHitCounts = $this->changeTagsStore->tagUsageStatistics();
        } else {
            // The full set of tags should use a different cache key than the subset
            $cacheKey .= '-all';
        }
 
        $summary = $this->cache->getWithSetCallback(
            $this->cache->makeKey( $cacheKey, strtolower( $localizationContext->getLanguageCode()->toBcp47Code() ) ),
            WANObjectCache::TTL_DAY,
            function () use ( $localizationContext, $tagKeys, $tagHitCounts ) {
                $result = [];
                foreach ( $tagKeys as $tagName ) {
                    // Only list tags that are still actively defined
                    if ( $tagHitCounts !== null ) {
                        // Only list tags with more than 0 hits
                        $hits = $tagHitCounts[$tagName] ?? 0;
                        if ( $hits <= 0 ) {
                            continue;
                        }
                    }
 
                    $labelMsg = $this->tagShortDescriptionMessage( $tagName, $localizationContext );
                    $helpLink = $this->tagHelpLink( $tagName, $localizationContext );
                    $descriptionMsg = $localizationContext->msg( "tag-$tagName-description" );
                    // Don't cache the message object, use the correct MessageLocalizer to parse later.
                    $result[] = [
                        'name' => $tagName,
                        'labelMsg' => !$labelMsg->isDisabled(),
                        'label' => !$labelMsg->isDisabled() ? $labelMsg->plain() : $tagName,
                        'descriptionMsg' => !$descriptionMsg->isDisabled(),
                        'description' => !$descriptionMsg->isDisabled() ? $descriptionMsg->plain() : '',
                        'helpLink' => $helpLink,
                        'cssClass' => Sanitizer::escapeClass( 'mw-tag-' . $tagName ),
                    ];
                }
                return $result;
            }
        );
 
        // Filter out tags that the user cannot see before returning this (the cache assumes the user can see all tags
        // to avoid splitting it by user)
        $viewable = array_fill_keys(
            $this->changeTagsStore->filterViewableTags( array_column( $summary, 'name' ), $authority ),
            true
        );
        return array_values( array_filter(
            $summary,
            static fn ( array $tagInfo ) => isset( $viewable[ $tagInfo['name'] ] )
        ) );
    }
 
    public function getChangeTagList(
        LocalizationContext $localizationContext,
        Authority $authority,
        bool $activeOnly = true,
        bool $useAllTags = true,
        bool $labelsOnly = false
    ): array {
        $tags = $this->getChangeTagListSummary( $localizationContext, $authority, $activeOnly, $useAllTags );
 
        $language = $this->languageFactory->getLanguage( $localizationContext->getLanguageCode() );
        foreach ( $tags as &$tagInfo ) {
            if ( $tagInfo['labelMsg'] ) {
                // Optimization: Skip the parsing if the label contains only plain text (T344352)
                if ( wfEscapeWikiText( $tagInfo['label'] ) !== $tagInfo['label'] ) {
                    // Use localizer with the correct page title to parse plain message from the cache.
                    $labelMsg = new RawMessage( $tagInfo['label'] );
                    $tagInfo['label'] = Sanitizer::stripAllTags( $localizationContext->msg( $labelMsg )->parse() );
                }
            } else {
                $tagInfo['label'] = $localizationContext->msg( 'tag-hidden', $tagInfo['name'] )->text();
            }
            // Optimization: Skip parsing the descriptions if not needed by the caller (T344352)
            if ( $labelsOnly ) {
                unset( $tagInfo['description'] );
            } elseif ( $tagInfo['descriptionMsg'] ) {
                // Optimization: Skip the parsing if the description contains only plain text (T344352)
                if ( wfEscapeWikiText( $tagInfo['description'] ) !== $tagInfo['description'] ) {
                    $descriptionMsg = new RawMessage( $tagInfo['description'] );
                    $tagInfo['description'] = Sanitizer::stripAllTags(
                        $localizationContext->msg( $descriptionMsg )->parse()
                    );
                }
                $tagInfo['description'] = $language->truncateForVisual( $tagInfo['description'],
                    self::TAG_DESC_CHARACTER_LIMIT );
            }
            unset( $tagInfo['labelMsg'] );
            unset( $tagInfo['descriptionMsg'] );
        }
 
        // Instead of sorting by hit count (disabled for now), sort by display name
        usort( $tags, static function ( $a, $b ) {
            return strcasecmp( $a['label'], $b['label'] );
        } );
        return $tags;
    }
}