MediaWiki  master
ApiWatchlistTrait.php
Go to the documentation of this file.
1 <?php
2 
5 
18 
20  private $watchlistExpiryEnabled;
21 
24 
35  protected function getWatchlistParams( array $watchOptions = [] ): array {
36  if ( !$watchOptions ) {
37  $watchOptions = [
38  'watch',
39  'unwatch',
40  'preferences',
41  'nochange',
42  ];
43  }
44 
45  $result = [
46  'watchlist' => [
47  ParamValidator::PARAM_DEFAULT => 'preferences',
48  ParamValidator::PARAM_TYPE => $watchOptions,
49  ],
50  ];
51 
52  if ( $this->watchlistExpiryEnabled ) {
53  $result['watchlistexpiry'] = [
54  ParamValidator::PARAM_TYPE => 'expiry',
55  ExpiryDef::PARAM_MAX => $this->watchlistMaxDuration,
56  ExpiryDef::PARAM_USE_MAX => true,
57  ];
58  }
59 
60  return $result;
61  }
62 
72  protected function setWatch(
73  string $watch,
74  Title $title,
75  User $user,
76  ?string $userOption = null,
77  ?string $expiry = null
78  ): void {
79  $value = $this->getWatchlistValue( $watch, $title, $user, $userOption );
80  WatchAction::doWatchOrUnwatch( $value, $title, $user, $expiry );
81  }
82 
92  protected function getWatchlistValue(
93  string $watchlist,
94  Title $title,
95  User $user,
96  ?string $userOption = null
97  ): bool {
98  $userWatching = $user->isWatched( $title, User::IGNORE_USER_RIGHTS );
99 
100  switch ( $watchlist ) {
101  case 'watch':
102  return true;
103 
104  case 'unwatch':
105  return false;
106 
107  case 'preferences':
108  // If the user is already watching, don't bother checking
109  if ( $userWatching ) {
110  return true;
111  }
112  // If the user is a bot, act as 'nochange' to avoid big watchlists on single users
113  if ( $user->isBot() ) {
114  return $userWatching;
115  }
116  // If no user option was passed, use watchdefault and watchcreations
117  if ( $userOption === null ) {
118  return $user->getBoolOption( 'watchdefault' ) ||
119  $user->getBoolOption( 'watchcreations' ) &&
120  !$title->exists();
121  }
122 
123  // Watch the article based on the user preference
124  return $user->getBoolOption( $userOption );
125 
126  case 'nochange':
127  return $userWatching;
128 
129  default:
130  return $userWatching;
131  }
132  }
133 
139  protected function getExpiryFromParams( array $params ): ?string {
140  $watchlistExpiry = null;
141  if ( $this->watchlistExpiryEnabled && isset( $params['watchlistexpiry'] ) ) {
142  $watchlistExpiry = ApiResult::formatExpiry( $params['watchlistexpiry'] );
143  }
144 
145  return $watchlistExpiry;
146  }
147 
156  protected function getWatchlistExpiry(
158  Title $title,
159  User $user
160  ): ?string {
161  $watchedItem = $store->getWatchedItem( $user, $title );
162 
163  if ( $watchedItem ) {
164  $expiry = $watchedItem->getExpiry();
165 
166  if ( $expiry !== null ) {
167  return ApiResult::formatExpiry( $expiry );
168  }
169  }
170 
171  return null;
172  }
173 }
$watchlistMaxDuration
string $watchlistMaxDuration
Relative maximum expiry.
Definition: ApiWatchlistTrait.php:23
getExpiryFromParams
getExpiryFromParams(array $params)
Get formatted expiry from the given parameters, or null if no expiry was provided.
Definition: ApiWatchlistTrait.php:139
User\isBot
isBot()
Definition: User.php:3001
Wikimedia\ParamValidator\TypeDef\ExpiryDef
Type definition for expiry timestamps.
Definition: ExpiryDef.php:17
setWatch
setWatch(string $watch, Title $title, User $user, ?string $userOption=null, ?string $expiry=null)
Set a watch (or unwatch) based the based on a watchlist parameter.
Definition: ApiWatchlistTrait.php:72
$title
$title
Definition: testCompression.php:38
WatchedItemStoreInterface\getWatchedItem
getWatchedItem(UserIdentity $user, LinkTarget $target)
Get an item (may be cached)
getWatchlistValue
getWatchlistValue(string $watchlist, Title $title, User $user, ?string $userOption=null)
Return true if we're to watch the page, false if not.
Definition: ApiWatchlistTrait.php:92
WatchAction\doWatchOrUnwatch
static doWatchOrUnwatch( $watch, Title $title, User $user, string $expiry=null)
Watch or unwatch a page.
Definition: WatchAction.php:241
getWatchlistExpiry
getWatchlistExpiry(WatchedItemStoreInterface $store, Title $title, User $user)
Get existing expiry from the database.
Definition: ApiWatchlistTrait.php:156
ApiWatchlistTrait
trait ApiWatchlistTrait
An ApiWatchlistTrait adds class properties and convenience methods for APIs that allow you to watch a...
Definition: ApiWatchlistTrait.php:17
Title
Represents a title within MediaWiki.
Definition: Title.php:46
getWatchlistParams
getWatchlistParams(array $watchOptions=[])
Get additional allow params specific to watchlisting.
Definition: ApiWatchlistTrait.php:35
ApiResult\formatExpiry
static formatExpiry( $expiry, $infinity='infinity')
Format an expiry timestamp for API output.
Definition: ApiResult.php:1189
User\IGNORE_USER_RIGHTS
const IGNORE_USER_RIGHTS
Definition: User.php:97
User\isWatched
isWatched( $title, $checkRights=self::CHECK_USER_RIGHTS)
Check the watched status of an article.
Definition: User.php:3096
User\getBoolOption
getBoolOption( $oname)
Get the user's current setting for a given option, as a boolean value.
Definition: User.php:2604
WatchedItemStoreInterface
Definition: WatchedItemStoreInterface.php:30
User
The User object encapsulates all of the user-specific settings (user_id, name, rights,...
Definition: User.php:63
Wikimedia\ParamValidator\ParamValidator
Service for formatting and validating API parameters.
Definition: ParamValidator.php:42