ApiWatchlistTrait.php

Go to the documentation of this file.

<?php
 
namespace MediaWiki\Api;
 
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 = null;
    private WatchedItemStoreInterface $watchedItemStore;
    private ?UserOptionsLookup $userOptionsLookup = null;
 
    private function initServices() {
        // This trait is used outside of core and therefor fallback to global state - T263904
        $this->watchlistManager ??= MediaWikiServices::getInstance()->getWatchlistManager();
        $this->watchedItemStore ??= MediaWikiServices::getInstance()->getWatchedItemStore();
        $this->userOptionsLookup ??= MediaWikiServices::getInstance()->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,
        ?PageIdentity $page = null,
        ?UserIdentity $user = null,
        string $userOption = 'watchdefault-expiry'
    ): ?string {
        $watchlistExpiry = null;
        if ( $this->watchlistExpiryEnabled ) {
            // At this point, the ParamValidator has already normalized $params['watchlistexpiry'].
            // Use the value provided in the API call, if any.
            $watchlistExpiry = $params['watchlistexpiry'] ?? null;
            // If expiry was not provided, and the user is already watching the page, keep the expiry value.
            if ( $user && $page && $watchlistExpiry === null && $this->watchedItemStore->isWatched( $user, $page ) ) {
                return $this->getWatchlistExpiry( $this->watchedItemStore, $page, $user );
            }
            // If the user is not watching the page, and expiry was not provided, use the default.
            if ( $user && $watchlistExpiry === null ) {
                $watchlistExpiry = ExpiryDef::normalizeExpiry(
                    $this->userOptionsLookup->getOption( $user, $userOption )
                );
            }
        }
 
        return ApiResult::formatExpiry( $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;
    }
}
 
class_alias( ApiWatchlistTrait::class, 'ApiWatchlistTrait' );