4 * API for MediaWiki 1.14+
6 * Created on Jun 18, 2012
8 * Copyright © 2012 Brad Jorsch
10 * This program is free software; you can redistribute it and/or modify
11 * it under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; either version 2 of the License, or
13 * (at your option) any later version.
15 * This program is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 * GNU General Public License for more details.
20 * You should have received a copy of the GNU General Public License along
21 * with this program; if not, write to the Free Software Foundation, Inc.,
22 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
23 * http://www.gnu.org/copyleft/gpl.html
29 * API interface for setting the wl_notificationtimestamp field
32 class ApiSetNotificationTimestamp
extends ApiBase
{
36 public function execute() {
37 $user = $this->getUser();
39 if ( $user->isAnon() ) {
40 $this->dieUsage( 'Anonymous users cannot use watchlist change notifications', 'notloggedin' );
43 $params = $this->extractRequestParams();
44 $this->requireMaxOneParameter( $params, 'timestamp', 'torevid', 'newerthanrevid' );
46 $pageSet = $this->getPageSet();
47 $args = array_merge( array( $params, 'entirewatchlist' ), array_keys( $pageSet->getAllowedParams() ) );
48 call_user_func_array( array( $this, 'requireOnlyOneParameter' ), $args );
50 $dbw = wfGetDB( DB_MASTER
, 'api' );
53 if ( isset( $params['timestamp'] ) ) {
54 $timestamp = $dbw->timestamp( $params['timestamp'] );
57 if ( !$params['entirewatchlist'] ) {
61 if ( isset( $params['torevid'] ) ) {
62 if ( $params['entirewatchlist'] ||
$pageSet->getGoodTitleCount() > 1 ) {
63 $this->dieUsage( 'torevid may only be used with a single page', 'multpages' );
65 $title = reset( $pageSet->getGoodTitles() );
66 $timestamp = Revision
::getTimestampFromId( $title, $params['torevid'] );
68 $timestamp = $dbw->timestamp( $timestamp );
72 } elseif ( isset( $params['newerthanrevid'] ) ) {
73 if ( $params['entirewatchlist'] ||
$pageSet->getGoodTitleCount() > 1 ) {
74 $this->dieUsage( 'newerthanrevid may only be used with a single page', 'multpages' );
76 $title = reset( $pageSet->getGoodTitles() );
77 $revid = $title->getNextRevisionID( $params['newerthanrevid'] );
79 $timestamp = $dbw->timestamp( Revision
::getTimestampFromId( $title, $revid ) );
85 $apiResult = $this->getResult();
87 if ( $params['entirewatchlist'] ) {
88 // Entire watchlist mode: Just update the thing and return a success indicator
89 $dbw->update( 'watchlist', array( 'wl_notificationtimestamp' => $timestamp ),
90 array( 'wl_user' => $user->getID() ),
94 $result['notificationtimestamp'] = ( is_null( $timestamp ) ?
'' : wfTimestamp( TS_ISO_8601
, $timestamp ) );
96 // First, log the invalid titles
97 foreach ( $pageSet->getInvalidTitles() as $title ) {
103 foreach ( $pageSet->getMissingPageIDs() as $p ) {
105 $page['pageid'] = $p;
106 $page['missing'] = '';
107 $page['notwatched'] = '';
110 foreach ( $pageSet->getMissingRevisionIDs() as $r ) {
113 $rev['missing'] = '';
114 $rev['notwatched'] = '';
118 // Now process the valid titles
119 $lb = new LinkBatch( $pageSet->getTitles() );
120 $dbw->update( 'watchlist', array( 'wl_notificationtimestamp' => $timestamp ),
121 array( 'wl_user' => $user->getID(), $lb->constructSet( 'wl', $dbw ) ),
125 // Query the results of our update
126 $timestamps = array();
127 $res = $dbw->select( 'watchlist', array( 'wl_namespace', 'wl_title', 'wl_notificationtimestamp' ),
128 array( 'wl_user' => $user->getID(), $lb->constructSet( 'wl', $dbw ) ),
131 foreach ( $res as $row ) {
132 $timestamps[$row->wl_namespace
][$row->wl_title
] = $row->wl_notificationtimestamp
;
135 // Now, put the valid titles into the result
136 /** @var $title Title */
137 foreach ( $pageSet->getTitles() as $title ) {
138 $ns = $title->getNamespace();
139 $dbkey = $title->getDBkey();
141 'ns' => intval( $ns ),
142 'title' => $title->getPrefixedText(),
144 if ( !$title->exists() ) {
147 if ( isset( $timestamps[$ns] ) && array_key_exists( $dbkey, $timestamps[$ns] ) ) {
148 $r['notificationtimestamp'] = '';
149 if ( $timestamps[$ns][$dbkey] !== null ) {
150 $r['notificationtimestamp'] = wfTimestamp( TS_ISO_8601
, $timestamps[$ns][$dbkey] );
153 $r['notwatched'] = '';
158 $apiResult->setIndexedTagName( $result, 'page' );
160 $apiResult->addValue( null, $this->getModuleName(), $result );
164 * Get a cached instance of an ApiPageSet object
167 private function getPageSet() {
168 if ( !isset( $this->mPageSet
) ) {
169 $this->mPageSet
= new ApiPageSet( $this );
171 return $this->mPageSet
;
174 public function mustBePosted() {
178 public function isWriteMode() {
182 public function needsToken() {
186 public function getTokenSalt() {
190 public function getAllowedParams( $flags = 0 ) {
192 'entirewatchlist' => array(
193 ApiBase
::PARAM_TYPE
=> 'boolean'
196 'timestamp' => array(
197 ApiBase
::PARAM_TYPE
=> 'timestamp'
200 ApiBase
::PARAM_TYPE
=> 'integer'
202 'newerthanrevid' => array(
203 ApiBase
::PARAM_TYPE
=> 'integer'
207 $result +
= $this->getPageSet()->getFinalParams( $flags );
213 public function getParamDescription() {
214 return $this->getPageSet()->getParamDescription() +
array(
215 'entirewatchlist' => 'Work on all watched pages',
216 'timestamp' => 'Timestamp to which to set the notification timestamp',
217 'torevid' => 'Revision to set the notification timestamp to (one page only)',
218 'newerthanrevid' => 'Revision to set the notification timestamp newer than (one page only)',
219 'token' => 'A token previously acquired via prop=info',
223 public function getResultProperties() {
225 ApiBase
::PROP_LIST
=> true,
226 ApiBase
::PROP_ROOT
=> array(
227 'notificationtimestamp' => array(
228 ApiBase
::PROP_TYPE
=> 'timestamp',
229 ApiBase
::PROP_NULLABLE
=> true
234 ApiBase
::PROP_TYPE
=> 'namespace',
235 ApiBase
::PROP_NULLABLE
=> true
238 ApiBase
::PROP_TYPE
=> 'string',
239 ApiBase
::PROP_NULLABLE
=> true
242 ApiBase
::PROP_TYPE
=> 'integer',
243 ApiBase
::PROP_NULLABLE
=> true
246 ApiBase
::PROP_TYPE
=> 'integer',
247 ApiBase
::PROP_NULLABLE
=> true
249 'invalid' => 'boolean',
250 'missing' => 'boolean',
251 'notwatched' => 'boolean',
252 'notificationtimestamp' => array(
253 ApiBase
::PROP_TYPE
=> 'timestamp',
254 ApiBase
::PROP_NULLABLE
=> true
260 public function getDescription() {
261 return array( 'Update the notification timestamp for watched pages.',
262 'This affects the highlighting of changed pages in the watchlist and history,',
263 'and the sending of email when the "Email me when a page on my watchlist is',
264 'changed" preference is enabled.'
268 public function getPossibleErrors() {
269 $ps = $this->getPageSet();
271 parent
::getPossibleErrors(),
272 $ps->getPossibleErrors(),
273 $this->getRequireMaxOneParameterErrorMessages(
274 array( 'timestamp', 'torevid', 'newerthanrevid' ) ),
275 $this->getRequireOnlyOneParameterErrorMessages(
276 array_merge( array( 'entirewatchlist' ), array_keys( $ps->getFinalParams() ) ) ),
278 array( 'code' => 'notloggedin', 'info' => 'Anonymous users cannot use watchlist change notifications' ),
279 array( 'code' => 'multpages', 'info' => 'torevid may only be used with a single page' ),
280 array( 'code' => 'multpages', 'info' => 'newerthanrevid may only be used with a single page' ),
285 public function getExamples() {
287 'api.php?action=setnotificationtimestamp&entirewatchlist=&token=123ABC' => 'Reset the notification status for the entire watchlist',
288 'api.php?action=setnotificationtimestamp&titles=Main_page&token=123ABC' => 'Reset the notification status for "Main page"',
289 'api.php?action=setnotificationtimestamp&titles=Main_page×tamp=2012-01-01T00:00:00Z&token=123ABC' => 'Set the notification timestamp for "Main page" so all edits since 1 January 2012 are unviewed',
293 public function getHelpUrls() {
294 return 'https://www.mediawiki.org/wiki/API:SetNotificationTimestamp';