ApiWatchlistTrait.php

Go to the documentation of this file.

<?php
 
use Wikimedia\ParamValidator\ParamValidator;
use Wikimedia\ParamValidator\TypeDef\ExpiryDef;
 
trait ApiWatchlistTrait {
 
    private $watchlistExpiryEnabled;
 
    private $watchlistMaxDuration;
 
    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,
        Title $title,
        User $user,
        ?string $userOption = null,
        ?string $expiry = null
    ): void {
        $value = $this->getWatchlistValue( $watch, $title, $user, $userOption );
        WatchAction::doWatchOrUnwatch( $value, $title, $user, $expiry );
    }
 
    protected function getWatchlistValue(
        string $watchlist,
        Title $title,
        User $user,
        ?string $userOption = null
    ): bool {
        $userWatching = $user->isWatched( $title, User::IGNORE_USER_RIGHTS );
 
        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 $user->getBoolOption( 'watchdefault' ) ||
                        $user->getBoolOption( 'watchcreations' ) &&
                        !$title->exists();
                }
 
                // Watch the article based on the user preference
                return $user->getBoolOption( $userOption );
 
            case 'nochange':
                return $userWatching;
 
            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,
        Title $title,
        User $user
    ): ?string {
        $watchedItem = $store->getWatchedItem( $user, $title );
 
        if ( $watchedItem ) {
            $expiry = $watchedItem->getExpiry();
 
            if ( $expiry !== null ) {
                return ApiResult::formatExpiry( $expiry );
            }
        }
 
        return null;
    }
}