MediaWiki  master
ApiWatchlistTrait.php
Go to the documentation of this file.
1 <?php
2 
9 
22 
24  private $watchlistExpiryEnabled;
25 
28 
31 
34 
35  private function initServices() {
36  if ( $this->watchlistManager !== null && $this->userOptionsLookup !== null ) {
37  return;
38  }
39  // This trait is used outside of core and therefor fallback to global state - T263904
40  $services = MediaWikiServices::getInstance();
41  if ( $this->watchlistManager === null ) {
42  $this->watchlistManager = $services->getWatchlistManager();
43  }
44  if ( $this->userOptionsLookup === null ) {
45  $this->userOptionsLookup = $services->getUserOptionsLookup();
46  }
47  }
48 
59  protected function getWatchlistParams( array $watchOptions = [] ): array {
60  if ( !$watchOptions ) {
61  $watchOptions = [
62  'watch',
63  'unwatch',
64  'preferences',
65  'nochange',
66  ];
67  }
68 
69  $result = [
70  'watchlist' => [
71  ParamValidator::PARAM_DEFAULT => 'preferences',
72  ParamValidator::PARAM_TYPE => $watchOptions,
73  ],
74  ];
75 
76  if ( $this->watchlistExpiryEnabled ) {
77  $result['watchlistexpiry'] = [
78  ParamValidator::PARAM_TYPE => 'expiry',
79  ExpiryDef::PARAM_MAX => $this->watchlistMaxDuration,
80  ExpiryDef::PARAM_USE_MAX => true,
81  ];
82  }
83 
84  return $result;
85  }
86 
96  protected function setWatch(
97  string $watch,
98  Title $title,
99  User $user,
100  ?string $userOption = null,
101  ?string $expiry = null
102  ): void {
103  $value = $this->getWatchlistValue( $watch, $title, $user, $userOption );
104  $this->watchlistManager->setWatch( $value, $user, $title, $expiry );
105  }
106 
116  protected function getWatchlistValue(
117  string $watchlist,
118  Title $title,
119  User $user,
120  ?string $userOption = null
121  ): bool {
122  $this->initServices();
123  $userWatching = $this->watchlistManager->isWatchedIgnoringRights( $user, $title );
124 
125  switch ( $watchlist ) {
126  case 'watch':
127  return true;
128 
129  case 'unwatch':
130  return false;
131 
132  case 'preferences':
133  // If the user is already watching, don't bother checking
134  if ( $userWatching ) {
135  return true;
136  }
137  // If the user is a bot, act as 'nochange' to avoid big watchlists on single users
138  if ( $user->isBot() ) {
139  return $userWatching;
140  }
141  // If no user option was passed, use watchdefault and watchcreations
142  if ( $userOption === null ) {
143  return $this->userOptionsLookup->getBoolOption( $user, 'watchdefault' ) ||
144  $this->userOptionsLookup->getBoolOption( $user, 'watchcreations' ) &&
145  !$title->exists();
146  }
147 
148  // Watch the article based on the user preference
149  return $this->userOptionsLookup->getBoolOption( $user, $userOption );
150 
151  case 'nochange':
152  return $userWatching;
153 
154  default:
155  return $userWatching;
156  }
157  }
158 
164  protected function getExpiryFromParams( array $params ): ?string {
165  $watchlistExpiry = null;
166  if ( $this->watchlistExpiryEnabled && isset( $params['watchlistexpiry'] ) ) {
167  $watchlistExpiry = ApiResult::formatExpiry( $params['watchlistexpiry'] );
168  }
169 
170  return $watchlistExpiry;
171  }
172 
181  protected function getWatchlistExpiry(
183  Title $title,
184  UserIdentity $user
185  ): ?string {
186  $watchedItem = $store->getWatchedItem( $user, $title );
187 
188  if ( $watchedItem ) {
189  $expiry = $watchedItem->getExpiry();
190 
191  if ( $expiry !== null ) {
192  return ApiResult::formatExpiry( $expiry );
193  }
194  }
195 
196  return null;
197  }
198 }
$watchlistMaxDuration
string $watchlistMaxDuration
Relative maximum expiry.
Definition: ApiWatchlistTrait.php:27
getExpiryFromParams
getExpiryFromParams(array $params)
Get formatted expiry from the given parameters, or null if no expiry was provided.
Definition: ApiWatchlistTrait.php:164
MediaWiki\MediaWikiServices
MediaWikiServices is the service locator for the application scope of MediaWiki.
Definition: MediaWikiServices.php:193
User\isBot
isBot()
Definition: User.php:2993
WatchedItemStoreInterface\getWatchedItem
getWatchedItem(UserIdentity $user, $target)
Get an item (may be cached)
MediaWiki\User\UserIdentity
Interface for objects representing user identity.
Definition: UserIdentity.php:39
Wikimedia\ParamValidator\TypeDef\ExpiryDef
Type definition for expiry timestamps.
Definition: ExpiryDef.php:17
MediaWiki\Watchlist\WatchlistManager
WatchlistManager service.
Definition: WatchlistManager.php:52
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:96
$title
$title
Definition: testCompression.php:38
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:116
MediaWiki\User\UserOptionsLookup
Provides access to user options.
Definition: UserOptionsLookup.php:29
ApiWatchlistTrait
trait ApiWatchlistTrait
An ApiWatchlistTrait adds class properties and convenience methods for APIs that allow you to watch a...
Definition: ApiWatchlistTrait.php:21
$watchlistManager
WatchlistManager $watchlistManager
Definition: ApiWatchlistTrait.php:30
$userOptionsLookup
UserOptionsLookup $userOptionsLookup
Definition: ApiWatchlistTrait.php:33
getWatchlistExpiry
getWatchlistExpiry(WatchedItemStoreInterface $store, Title $title, UserIdentity $user)
Get existing expiry from the database.
Definition: ApiWatchlistTrait.php:181
Title
Represents a title within MediaWiki.
Definition: Title.php:48
getWatchlistParams
getWatchlistParams(array $watchOptions=[])
Get additional allow params specific to watchlisting.
Definition: ApiWatchlistTrait.php:59
ApiResult\formatExpiry
static formatExpiry( $expiry, $infinity='infinity')
Format an expiry timestamp for API output.
Definition: ApiResult.php:1194
WatchedItemStoreInterface
Definition: WatchedItemStoreInterface.php:31
User
The User object encapsulates all of the user-specific settings (user_id, name, rights,...
Definition: User.php:68
initServices
initServices()
Definition: ApiWatchlistTrait.php:35
Wikimedia\ParamValidator\ParamValidator
Service for formatting and validating API parameters.
Definition: ParamValidator.php:42