ApiWatchlistTrait.php

Go to the documentation of this file.

<?php
 
use MediaWiki\MediaWikiServices;
use MediaWiki\Page\PageIdentity;
use MediaWiki\User\Options\UserOptionsLookup;
use MediaWiki\User\User;
use MediaWiki\User\UserIdentity;
use MediaWiki\Watchlist\WatchedItemStoreInterface;
use MediaWiki\Watchlist\WatchlistManager;
use Wikimedia\ParamValidator\ParamValidator;
use Wikimedia\ParamValidator\TypeDef\ExpiryDef;
 
trait ApiWatchlistTrait {
 
    private $watchlistExpiryEnabled;
 
    private $watchlistMaxDuration;
 
    private WatchlistManager $watchlistManager;
    private UserOptionsLookup $userOptionsLookup;
 
    private function initServices() {
        // @phan-suppress-next-line PhanRedundantCondition Phan trusts the type hints too much
        if ( isset( $this->watchlistManager ) && isset( $this->userOptionsLookup ) ) {
            return;
        }
        // This trait is used outside of core and therefor fallback to global state - T263904
        $services = MediaWikiServices::getInstance();
        $this->watchlistManager ??= $services->getWatchlistManager();
        $this->userOptionsLookup ??= $services->getUserOptionsLookup();
    }
 
    protected function getWatchlistParams( array $watchOptions = [] ): array {
        if ( !$watchOptions ) {
            $watchOptions = [
                'watch',
                'unwatch',
                'preferences',
                'nochange',
            ];
        }
 
        $result = [
            'watchlist' => [
                ParamValidator::PARAM_DEFAULT => 'preferences',
                ParamValidator::PARAM_TYPE => $watchOptions,
            ],
        ];
 
        if ( $this->watchlistExpiryEnabled ) {
            $result['watchlistexpiry'] = [
                ParamValidator::PARAM_TYPE => 'expiry',
                ExpiryDef::PARAM_MAX => $this->watchlistMaxDuration,
                ExpiryDef::PARAM_USE_MAX => true,
            ];
        }
 
        return $result;
    }
 
    protected function setWatch(
        string $watch,
        PageIdentity $page,
        User $user,
        ?string $userOption = null,
        ?string $expiry = null
    ): void {
        $value = $this->getWatchlistValue( $watch, $page, $user, $userOption );
        $this->watchlistManager->setWatch( $value, $user, $page, $expiry );
    }
 
    protected function getWatchlistValue(
        string $watchlist,
        PageIdentity $page,
        User $user,
        ?string $userOption = null
    ): bool {
        $this->initServices();
        $userWatching = $this->watchlistManager->isWatchedIgnoringRights( $user, $page );
 
        switch ( $watchlist ) {
            case 'watch':
                return true;
 
            case 'unwatch':
                return false;
 
            case 'preferences':
                // If the user is already watching, don't bother checking
                if ( $userWatching ) {
                    return true;
                }
                // If the user is a bot, act as 'nochange' to avoid big watchlists on single users
                if ( $user->isBot() ) {
                    return $userWatching;
                }
                // If no user option was passed, use watchdefault and watchcreations
                if ( $userOption === null ) {
                    return $this->userOptionsLookup->getBoolOption( $user, 'watchdefault' ) ||
                        ( $this->userOptionsLookup->getBoolOption( $user, 'watchcreations' ) && !$page->exists() );
                }
 
                // Watch the article based on the user preference
                return $this->userOptionsLookup->getBoolOption( $user, $userOption );
 
            // case 'nochange':
            default:
                return $userWatching;
        }
    }
 
    protected function getExpiryFromParams( array $params ): ?string {
        $watchlistExpiry = null;
        if ( $this->watchlistExpiryEnabled && isset( $params['watchlistexpiry'] ) ) {
            $watchlistExpiry = ApiResult::formatExpiry( $params['watchlistexpiry'] );
        }
 
        return $watchlistExpiry;
    }
 
    protected function getWatchlistExpiry(
        WatchedItemStoreInterface $store,
        PageIdentity $page,
        UserIdentity $user
    ): ?string {
        $watchedItem = $store->getWatchedItem( $user, $page );
 
        if ( $watchedItem ) {
            $expiry = $watchedItem->getExpiry();
 
            if ( $expiry !== null ) {
                return ApiResult::formatExpiry( $expiry );
            }
        }
 
        return null;
    }
}