MediaWiki  master
ApiWatchlistTrait.php
Go to the documentation of this file.
1 <?php
2 
10 
23 
25  private $watchlistExpiryEnabled;
26 
28  private $watchlistMaxDuration;
29 
31  private $watchlistManager;
32 
34  private $userOptionsLookup;
35 
36  private function initServices() {
37  if ( $this->watchlistManager !== null && $this->userOptionsLookup !== null ) {
38  return;
39  }
40  // This trait is used outside of core and therefor fallback to global state - T263904
41  $services = MediaWikiServices::getInstance();
42  $this->watchlistManager ??= $services->getWatchlistManager();
43  $this->userOptionsLookup ??= $services->getUserOptionsLookup();
44  }
45 
56  protected function getWatchlistParams( array $watchOptions = [] ): array {
57  if ( !$watchOptions ) {
58  $watchOptions = [
59  'watch',
60  'unwatch',
61  'preferences',
62  'nochange',
63  ];
64  }
65 
66  $result = [
67  'watchlist' => [
68  ParamValidator::PARAM_DEFAULT => 'preferences',
69  ParamValidator::PARAM_TYPE => $watchOptions,
70  ],
71  ];
72 
73  if ( $this->watchlistExpiryEnabled ) {
74  $result['watchlistexpiry'] = [
75  ParamValidator::PARAM_TYPE => 'expiry',
76  ExpiryDef::PARAM_MAX => $this->watchlistMaxDuration,
77  ExpiryDef::PARAM_USE_MAX => true,
78  ];
79  }
80 
81  return $result;
82  }
83 
93  protected function setWatch(
94  string $watch,
95  Title $title,
96  User $user,
97  ?string $userOption = null,
98  ?string $expiry = null
99  ): void {
100  $value = $this->getWatchlistValue( $watch, $title, $user, $userOption );
101  $this->watchlistManager->setWatch( $value, $user, $title, $expiry );
102  }
103 
113  protected function getWatchlistValue(
114  string $watchlist,
115  Title $title,
116  User $user,
117  ?string $userOption = null
118  ): bool {
119  $this->initServices();
120  $userWatching = $this->watchlistManager->isWatchedIgnoringRights( $user, $title );
121 
122  switch ( $watchlist ) {
123  case 'watch':
124  return true;
125 
126  case 'unwatch':
127  return false;
128 
129  case 'preferences':
130  // If the user is already watching, don't bother checking
131  if ( $userWatching ) {
132  return true;
133  }
134  // If the user is a bot, act as 'nochange' to avoid big watchlists on single users
135  if ( $user->isBot() ) {
136  return $userWatching;
137  }
138  // If no user option was passed, use watchdefault and watchcreations
139  if ( $userOption === null ) {
140  return $this->userOptionsLookup->getBoolOption( $user, 'watchdefault' ) ||
141  $this->userOptionsLookup->getBoolOption( $user, 'watchcreations' ) &&
142  !$title->exists();
143  }
144 
145  // Watch the article based on the user preference
146  return $this->userOptionsLookup->getBoolOption( $user, $userOption );
147 
148  // case 'nochange':
149  default:
150  return $userWatching;
151  }
152  }
153 
159  protected function getExpiryFromParams( array $params ): ?string {
160  $watchlistExpiry = null;
161  if ( $this->watchlistExpiryEnabled && isset( $params['watchlistexpiry'] ) ) {
162  $watchlistExpiry = ApiResult::formatExpiry( $params['watchlistexpiry'] );
163  }
164 
165  return $watchlistExpiry;
166  }
167 
176  protected function getWatchlistExpiry(
178  Title $title,
179  UserIdentity $user
180  ): ?string {
181  $watchedItem = $store->getWatchedItem( $user, $title );
182 
183  if ( $watchedItem ) {
184  $expiry = $watchedItem->getExpiry();
185 
186  if ( $expiry !== null ) {
187  return ApiResult::formatExpiry( $expiry );
188  }
189  }
190 
191  return null;
192  }
193 }
getWatchlistValue(string $watchlist, Title $title, User $user, ?string $userOption=null)
Return true if we're to watch the page, false if not.
getExpiryFromParams(array $params)
Get formatted expiry from the given parameters, or null if no expiry was provided.
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.
getWatchlistExpiry(WatchedItemStoreInterface $store, Title $title, UserIdentity $user)
Get existing expiry from the database.
getWatchlistParams(array $watchOptions=[])
Get additional allow params specific to watchlisting.
if(!defined('MW_SETUP_CALLBACK'))
Definition: WebStart.php:88
static formatExpiry( $expiry, $infinity='infinity')
Format an expiry timestamp for API output.
Definition: ApiResult.php:1199
Service locator for MediaWiki core services.
Represents a title within MediaWiki.
Definition: Title.php:82
Provides access to user options.
The User object encapsulates all of the user-specific settings (user_id, name, rights,...
Definition: User.php:71
isBot()
Definition: User.php:2332
Service for formatting and validating API parameters.
Type definition for expiry timestamps.
Definition: ExpiryDef.php:17
trait ApiWatchlistTrait
An ApiWatchlistTrait adds class properties and convenience methods for APIs that allow you to watch a...
Interface for objects representing user identity.