includes/api/ApiQueryWatchlist.php

   1 <?php
   2
   3
   4 /*
   5  * Created on Sep 25, 2006
   6  *
   7  * API for MediaWiki 1.8+
   8  *
   9  * Copyright (C) 2006 Yuri Astrakhan <FirstnameLastname@gmail.com>
  10  *
  11  * This program is free software; you can redistribute it and/or modify
  12  * it under the terms of the GNU General Public License as published by
  13  * the Free Software Foundation; either version 2 of the License, or
  14  * (at your option) any later version.
  15  *
  16  * This program is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  19  * GNU General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU General Public License along
  22  * with this program; if not, write to the Free Software Foundation, Inc.,
  23  * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  24  * http://www.gnu.org/copyleft/gpl.html
  25  */
  26
  27 if (!defined('MEDIAWIKI')) {
  28         // Eclipse helper - will be ignored in production
  29         require_once ('ApiQueryBase.php');
  30 }
  31
  32 class ApiQueryWatchlist extends ApiQueryGeneratorBase {
  33
  34         public function __construct($query, $moduleName) {
  35                 parent :: __construct($query, $moduleName, 'wl');
  36         }
  37
  38         public function execute() {
  39                 $this->run();
  40         }
  41
  42         public function executeGenerator($resultPageSet) {
  43                 $this->run($resultPageSet);
  44         }
  45
  46         private function run($resultPageSet = null) {
  47                 global $wgUser;
  48
  49                 if (!$wgUser->isLoggedIn())
  50                         $this->dieUsage('You must be logged-in to have a watchlist', 'notloggedin');
  51
  52                 $allrev = $start = $end = $namespace = $dir = $limit = $prop = null;
  53                 extract($this->extractRequestParams());
  54
  55                 $db = $this->getDB();
  56
  57                 $dirNewer = ($dir === 'newer');
  58                 $before = ($dirNewer ? '<=' : '>=');
  59                 $after = ($dirNewer ? '>=' : '<=');
  60
  61                 $tables = array (
  62                         'watchlist',
  63                         'page',
  64                         'recentchanges'
  65                 );
  66
  67                 $options = array (
  68                         'LIMIT' => $limit +1,
  69                         'ORDER BY' => 'rc_timestamp' . ($dirNewer ? '' : ' DESC'
  70                 ));
  71
  72                 $patrol = $timestamp = $user = $comment = false;
  73                 if (!is_null($prop)) {
  74                         if (!is_null($resultPageSet))
  75                                 $this->dieUsage('prop parameter may not be used in a generator', 'params');
  76
  77                         $user = (false !== array_search('user', $prop));
  78                         $comment = (false !== array_search('comment', $prop));
  79                         $timestamp = (false !== array_search('timestamp', $prop));
  80                         $patrol = (false !== array_search('patrol', $prop));
  81
  82                         if ($patrol) {
  83                                 global $wgUseRCPatrol, $wgUser;
  84                                 if (!$wgUseRCPatrol || !$wgUser->isAllowed('patrol'))
  85                                         $this->dieUsage('patrol property is not available', 'patrol');
  86                         }
  87                 }
  88
  89                 if (is_null($resultPageSet)) {
  90                         $fields = array (
  91                                 'rc_cur_id AS page_id',
  92                                 'rc_this_oldid AS rev_id',
  93                                 'rc_namespace AS page_namespace',
  94                                 'rc_title AS page_title',
  95                                 'rc_new AS page_is_new',
  96                                 'rc_minor AS rev_minor_edit'
  97                         );
  98                         if ($user) {
  99                                 $fields[] = 'rc_user AS rev_user';
 100                                 $fields[] = 'rc_user_text AS rev_user_text';
 101                         }
 102                         if ($comment)
 103                                 $fields[] = 'rc_comment AS rev_comment';
 104                         if ($timestamp)
 105                                 $fields[] = 'rc_timestamp AS rev_timestamp';
 106                         if ($patrol)
 107                                 $fields[] = 'rc_patrolled';
 108                 }
 109                 elseif ($allrev) {
 110                         $fields = array (
 111                                 'rc_this_oldid AS rev_id',
 112                                 'rc_namespace AS page_namespace',
 113                                 'rc_title AS page_title',
 114                                 'rc_timestamp AS rev_timestamp'
 115                         );
 116                 } else {
 117                         $fields = array (
 118                                 'rc_cur_id AS page_id',
 119                                 'rc_namespace AS page_namespace',
 120                                 'rc_title AS page_title',
 121                                 'rc_timestamp AS rev_timestamp'
 122                         );
 123                 }
 124
 125                 $where = array (
 126                         'wl_namespace = rc_namespace',
 127                         'wl_title = rc_title',
 128                         'rc_cur_id = page_id',
 129                 'wl_user' => $wgUser->getID());
 130
 131                 if (!$allrev)
 132                         $where[] = 'rc_this_oldid=page_latest';
 133                 if (isset ($namespace))
 134                         $where['wl_namespace'] = $namespace;
 135
 136                 if (isset ($start))
 137                         $where[] = 'rc_timestamp' . $after . $db->addQuotes($start);
 138
 139                 if (isset ($end))
 140                         $where[] = 'rc_timestamp' . $before . $db->addQuotes($end);
 141
 142                 if (!isset ($start) && !isset ($end))
 143                         $where[] = "rc_timestamp > ''";
 144
 145                 $this->profileDBIn();
 146                 $res = $db->select($tables, $fields, $where, __METHOD__, $options);
 147                 $this->profileDBOut();
 148
 149                 $data = array ();
 150                 $count = 0;
 151                 while ($row = $db->fetchObject($res)) {
 152                         if (++ $count > $limit) {
 153                                 // We've reached the one extra which shows that there are additional pages to be had. Stop here...
 154                                 $this->setContinueEnumParameter('from', $row->rev_timestamp);
 155                                 break;
 156                         }
 157
 158                         $title = Title :: makeTitle($row->page_namespace, $row->page_title);
 159                         // skip any pages that user has no rights to read
 160                         if ($title->userCanRead()) {
 161
 162                                 if (is_null($resultPageSet)) {
 163                                         $id = intval($row->page_id);
 164
 165                                         $vals = array ();
 166                                         $vals['pageid'] = intval($row->page_id);
 167                                         $vals['revid'] = intval($row->rev_id);
 168                                         $vals['ns'] = $title->getNamespace();
 169                                         $vals['title'] = $title->getPrefixedText();
 170
 171                                         if ($row->page_is_new)
 172                                                 $vals['new'] = '';
 173                                         if ($row->rev_minor_edit)
 174                                                 $vals['minor'] = '';
 175
 176                                         if ($user) {
 177                                                 if (!$row->rev_user)
 178                                                         $vals['anon'] = '';
 179                                                 $vals['user'] = $row->rev_user_text;
 180                                         }
 181                                         if ($comment)
 182                                                 $vals['comment'] = $row->rev_comment;
 183                                         if ($timestamp)
 184                                                 $vals['timestamp'] = $row->rev_timestamp;
 185                                         if ($patrol && $row->rc_patrolled)
 186                                                 $vals['patrolled'] = '';
 187
 188                                         $data[] = $vals;
 189                                 }
 190                                 elseif ($allrev) {
 191                                         $data[] = intval($row->rev_id);
 192                                 } else {
 193                                         $data[] = intval($row->page_id);
 194                                 }
 195                         }
 196                 }
 197                 $db->freeResult($res);
 198
 199                 if (is_null($resultPageSet)) {
 200                         ApiResult :: setIndexedTagName($data, 'item');
 201                         $this->getResult()->addValue('query', $this->getModuleName(), $data);
 202                 }
 203                 elseif ($allrev) {
 204                         $resultPageSet->populateFromRevisionIDs($data);
 205                 } else {
 206                         $resultPageSet->populateFromPageIDs($data);
 207                 }
 208         }
 209
 210         protected function getAllowedParams() {
 211                 $namespaces = $this->getQuery()->getValidNamespaces();
 212                 return array (
 213                         'allrev' => false,
 214                         'start' => array (
 215                                 ApiBase :: PARAM_TYPE => 'timestamp'
 216                         ),
 217                         'end' => array (
 218                                 ApiBase :: PARAM_TYPE => 'timestamp'
 219                         ),
 220                         'namespace' => array (
 221                                 ApiBase :: PARAM_ISMULTI => true,
 222                                 ApiBase :: PARAM_TYPE => $namespaces
 223                         ),
 224                         'dir' => array (
 225                                 ApiBase :: PARAM_DFLT => 'older',
 226                                 ApiBase :: PARAM_TYPE => array (
 227                                         'newer',
 228                                         'older'
 229                                 )
 230                         ),
 231                         'limit' => array (
 232                                 ApiBase :: PARAM_DFLT => 10,
 233                                 ApiBase :: PARAM_TYPE => 'limit',
 234                                 ApiBase :: PARAM_MIN => 1,
 235                                 ApiBase :: PARAM_MAX1 => ApiBase :: LIMIT_BIG1,
 236                                 ApiBase :: PARAM_MAX2 => ApiBase :: LIMIT_BIG2
 237                         ),
 238                         'prop' => array (
 239                                 APIBase :: PARAM_ISMULTI => true,
 240                                 APIBase :: PARAM_TYPE => array (
 241                                         'user',
 242                                         'comment',
 243                                         'timestamp',
 244                                         'patrol'
 245                                 )
 246                         )
 247                 );
 248         }
 249
 250         protected function getParamDescription() {
 251                 return array (
 252                         'allrev' => 'Include multiple revisions of the same page within given timeframe.',
 253                         'start' => 'The timestamp to start enumerating from.',
 254                         'end' => 'The timestamp to end enumerating.',
 255                         'namespace' => 'Filter changes to only the given namespace(s).',
 256                         'dir' => 'In which direction to enumerate pages.',
 257                         'limit' => 'How many total pages to return per request.',
 258                         'prop' => 'Which additional items to get (non-generator mode only).'
 259                 );
 260         }
 261
 262         protected function getDescription() {
 263                 return '';
 264         }
 265
 266         protected function getExamples() {
 267                 return array (
 268                         'api.php?action=query&list=watchlist',
 269                         'api.php?action=query&list=watchlist&wlallrev',
 270                         'api.php?action=query&generator=watchlist&prop=info',
 271                         'api.php?action=query&generator=watchlist&gwlallrev&prop=revisions&rvprop=timestamp|user'
 272                 );
 273         }
 274
 275         public function getVersion() {
 276                 return __CLASS__ . ': $Id$';
 277         }
 278 }
 279 ?>