php/html/ApiQueryWatchlist_8php_source.html

00001 <?php
00033 class ApiQueryWatchlist extends ApiQueryGeneratorBase {
00034
00035         public function __construct( $query, $moduleName ) {
00036                 parent::__construct( $query, $moduleName, 'wl' );
00037         }
00038
00039         public function execute() {
00040                 $this->run();
00041         }
00042
00043         public function executeGenerator( $resultPageSet ) {
00044                 $this->run( $resultPageSet );
00045         }
00046
00047         private $fld_ids = false, $fld_title = false, $fld_patrol = false, $fld_flags = false,
00048                         $fld_timestamp = false, $fld_user = false, $fld_comment = false, $fld_parsedcomment = false, $fld_sizes = false,
00049                         $fld_notificationtimestamp = false, $fld_userid = false, $fld_loginfo = false;
00050
00055         private function run( $resultPageSet = null ) {
00056                 $this->selectNamedDB( 'watchlist', DB_SLAVE, 'watchlist' );
00057
00058                 $params = $this->extractRequestParams();
00059
00060                 $user = $this->getWatchlistUser( $params );
00061
00062                 if ( !is_null( $params['prop'] ) && is_null( $resultPageSet ) ) {
00063                         $prop = array_flip( $params['prop'] );
00064
00065                         $this->fld_ids = isset( $prop['ids'] );
00066                         $this->fld_title = isset( $prop['title'] );
00067                         $this->fld_flags = isset( $prop['flags'] );
00068                         $this->fld_user = isset( $prop['user'] );
00069                         $this->fld_userid = isset( $prop['userid'] );
00070                         $this->fld_comment = isset( $prop['comment'] );
00071                         $this->fld_parsedcomment = isset ( $prop['parsedcomment'] );
00072                         $this->fld_timestamp = isset( $prop['timestamp'] );
00073                         $this->fld_sizes = isset( $prop['sizes'] );
00074                         $this->fld_patrol = isset( $prop['patrol'] );
00075                         $this->fld_notificationtimestamp = isset( $prop['notificationtimestamp'] );
00076                         $this->fld_loginfo = isset( $prop['loginfo'] );
00077
00078                         if ( $this->fld_patrol ) {
00079                                 if ( !$user->useRCPatrol() && !$user->useNPPatrol() ) {
00080                                         $this->dieUsage( 'patrol property is not available', 'patrol' );
00081                                 }
00082                         }
00083                 }
00084
00085                 $this->addFields( array(
00086                         'rc_namespace',
00087                         'rc_title',
00088                         'rc_timestamp',
00089                         'rc_type',
00090                 ) );
00091
00092                 if ( is_null( $resultPageSet ) ) {
00093                         $this->addFields( array(
00094                                 'rc_cur_id',
00095                                 'rc_this_oldid',
00096                                 'rc_last_oldid',
00097                         ) );
00098
00099                         $this->addFieldsIf( array( 'rc_type', 'rc_minor', 'rc_bot' ), $this->fld_flags );
00100                         $this->addFieldsIf( 'rc_user', $this->fld_user || $this->fld_userid );
00101                         $this->addFieldsIf( 'rc_user_text', $this->fld_user );
00102                         $this->addFieldsIf( 'rc_comment', $this->fld_comment || $this->fld_parsedcomment );
00103                         $this->addFieldsIf( 'rc_patrolled', $this->fld_patrol );
00104                         $this->addFieldsIf( array( 'rc_old_len', 'rc_new_len' ), $this->fld_sizes );
00105                         $this->addFieldsIf( 'wl_notificationtimestamp', $this->fld_notificationtimestamp );
00106                         $this->addFieldsIf( array( 'rc_logid', 'rc_log_type', 'rc_log_action', 'rc_params' ), $this->fld_loginfo );
00107                 } elseif ( $params['allrev'] ) {
00108                         $this->addFields( 'rc_this_oldid' );
00109                 } else {
00110                         $this->addFields( 'rc_cur_id' );
00111                 }
00112
00113                 $this->addTables( array(
00114                         'recentchanges',
00115                         'watchlist',
00116                 ) );
00117
00118                 $userId = $user->getId();
00119                 $this->addJoinConds( array( 'watchlist' => array( 'INNER JOIN',
00120                         array(
00121                                 'wl_user' => $userId,
00122                                 'wl_namespace=rc_namespace',
00123                                 'wl_title=rc_title'
00124                 ) ) ) );
00125
00126                 $this->addWhere( array(
00127                         'rc_deleted' => 0,
00128                 ) );
00129
00130                 $db = $this->getDB();
00131
00132                 $this->addTimestampWhereRange( 'rc_timestamp', $params['dir'],
00133                         $params['start'], $params['end'] );
00134                 $this->addWhereFld( 'wl_namespace', $params['namespace'] );
00135
00136                 if ( !$params['allrev'] ) {
00137                         $this->addTables( 'page' );
00138                         $this->addJoinConds( array( 'page' => array( 'LEFT JOIN','rc_cur_id=page_id' ) ) );
00139                         $this->addWhere( 'rc_this_oldid=page_latest OR rc_type=' . RC_LOG );
00140                 }
00141
00142                 if ( !is_null( $params['show'] ) ) {
00143                         $show = array_flip( $params['show'] );
00144
00145                         /* Check for conflicting parameters. */
00146                         if ( ( isset ( $show['minor'] ) && isset ( $show['!minor'] ) )
00147                                         || ( isset ( $show['bot'] ) && isset ( $show['!bot'] ) )
00148                                         || ( isset ( $show['anon'] ) && isset ( $show['!anon'] ) )
00149                                         || ( isset ( $show['patrolled'] ) && isset ( $show['!patrolled'] ) )
00150                         )
00151                         {
00152                                 $this->dieUsageMsg( 'show' );
00153                         }
00154
00155                         // Check permissions.
00156                         if ( isset( $show['patrolled'] ) || isset( $show['!patrolled'] ) ) {
00157                                 $user = $this->getUser();
00158                                 if ( !$user->useRCPatrol() && !$user->useNPPatrol() ) {
00159                                         $this->dieUsage( 'You need the patrol right to request the patrolled flag', 'permissiondenied' );
00160                                 }
00161                         }
00162
00163                         /* Add additional conditions to query depending upon parameters. */
00164                         $this->addWhereIf( 'rc_minor = 0', isset( $show['!minor'] ) );
00165                         $this->addWhereIf( 'rc_minor != 0', isset( $show['minor'] ) );
00166                         $this->addWhereIf( 'rc_bot = 0', isset( $show['!bot'] ) );
00167                         $this->addWhereIf( 'rc_bot != 0', isset( $show['bot'] ) );
00168                         $this->addWhereIf( 'rc_user = 0', isset( $show['anon'] ) );
00169                         $this->addWhereIf( 'rc_user != 0', isset( $show['!anon'] ) );
00170                         $this->addWhereIf( 'rc_patrolled = 0', isset( $show['!patrolled'] ) );
00171                         $this->addWhereIf( 'rc_patrolled != 0', isset( $show['patrolled'] ) );
00172                 }
00173
00174                 if ( !is_null( $params['user'] ) && !is_null( $params['excludeuser'] ) ) {
00175                         $this->dieUsage( 'user and excludeuser cannot be used together', 'user-excludeuser' );
00176                 }
00177                 if ( !is_null( $params['user'] ) ) {
00178                         $this->addWhereFld( 'rc_user_text', $params['user'] );
00179                 }
00180                 if ( !is_null( $params['excludeuser'] ) ) {
00181                         $this->addWhere( 'rc_user_text != ' . $db->addQuotes( $params['excludeuser'] ) );
00182                 }
00183
00184                 // This is an index optimization for mysql, as done in the Special:Watchlist page
00185                 $this->addWhereIf( "rc_timestamp > ''", !isset( $params['start'] ) && !isset( $params['end'] ) && $db->getType() == 'mysql' );
00186
00187                 $this->addOption( 'LIMIT', $params['limit'] + 1 );
00188
00189                 $ids = array();
00190                 $count = 0;
00191                 $res = $this->select( __METHOD__ );
00192
00193                 foreach ( $res as $row ) {
00194                         if ( ++ $count > $params['limit'] ) {
00195                                 // We've reached the one extra which shows that there are additional pages to be had. Stop here...
00196                                 $this->setContinueEnumParameter( 'start', wfTimestamp( TS_ISO_8601, $row->rc_timestamp ) );
00197                                 break;
00198                         }
00199
00200                         if ( is_null( $resultPageSet ) ) {
00201                                 $vals = $this->extractRowInfo( $row );
00202                                 $fit = $this->getResult()->addValue( array( 'query', $this->getModuleName() ), null, $vals );
00203                                 if ( !$fit ) {
00204                                         $this->setContinueEnumParameter( 'start',
00205                                                         wfTimestamp( TS_ISO_8601, $row->rc_timestamp ) );
00206                                         break;
00207                                 }
00208                         } else {
00209                                 if ( $params['allrev'] ) {
00210                                         $ids[] = intval( $row->rc_this_oldid );
00211                                 } else {
00212                                         $ids[] = intval( $row->rc_cur_id );
00213                                 }
00214                         }
00215                 }
00216
00217                 if ( is_null( $resultPageSet ) ) {
00218                         $this->getResult()->setIndexedTagName_internal( array( 'query', $this->getModuleName() ), 'item' );
00219                 } elseif ( $params['allrev'] ) {
00220                         $resultPageSet->populateFromRevisionIDs( $ids );
00221                 } else {
00222                         $resultPageSet->populateFromPageIDs( $ids );
00223                 }
00224         }
00225
00226         private function extractRowInfo( $row ) {
00227                 $vals = array();
00228
00229                 if ( $this->fld_ids ) {
00230                         $vals['pageid'] = intval( $row->rc_cur_id );
00231                         $vals['revid'] = intval( $row->rc_this_oldid );
00232                         $vals['old_revid'] = intval( $row->rc_last_oldid );
00233                 }
00234
00235                 $title = Title::makeTitle( $row->rc_namespace, $row->rc_title );
00236
00237                 if ( $this->fld_title ) {
00238                         ApiQueryBase::addTitleInfo( $vals, $title );
00239                 }
00240
00241                 if ( $this->fld_user || $this->fld_userid ) {
00242
00243                         if ( $this->fld_userid ) {
00244                                 $vals['userid'] = $row->rc_user;
00245                                 // for backwards compatibility
00246                                 $vals['user'] = $row->rc_user;
00247                         }
00248
00249                         if ( $this->fld_user ) {
00250                                 $vals['user'] = $row->rc_user_text;
00251                         }
00252
00253                         if ( !$row->rc_user ) {
00254                                 $vals['anon'] = '';
00255                         }
00256                 }
00257
00258                 if ( $this->fld_flags ) {
00259                         if ( $row->rc_type == RC_NEW ) {
00260                                 $vals['new'] = '';
00261                         }
00262                         if ( $row->rc_minor ) {
00263                                 $vals['minor'] = '';
00264                         }
00265                         if ( $row->rc_bot ) {
00266                                 $vals['bot'] = '';
00267                         }
00268                 }
00269
00270                 if ( $this->fld_patrol && isset( $row->rc_patrolled ) ) {
00271                         $vals['patrolled'] = '';
00272                 }
00273
00274                 if ( $this->fld_timestamp ) {
00275                         $vals['timestamp'] = wfTimestamp( TS_ISO_8601, $row->rc_timestamp );
00276                 }
00277
00278                 if ( $this->fld_sizes ) {
00279                         $vals['oldlen'] = intval( $row->rc_old_len );
00280                         $vals['newlen'] = intval( $row->rc_new_len );
00281                 }
00282
00283                 if ( $this->fld_notificationtimestamp ) {
00284                         $vals['notificationtimestamp'] = ( $row->wl_notificationtimestamp == null )
00285                                 ? ''
00286                                 : wfTimestamp( TS_ISO_8601, $row->wl_notificationtimestamp );
00287                 }
00288
00289                 if ( $this->fld_comment && isset( $row->rc_comment ) ) {
00290                         $vals['comment'] = $row->rc_comment;
00291                 }
00292
00293                 if ( $this->fld_parsedcomment && isset( $row->rc_comment ) ) {
00294                         $vals['parsedcomment'] = Linker::formatComment( $row->rc_comment, $title );
00295                 }
00296
00297                 if ( $this->fld_loginfo && $row->rc_type == RC_LOG ) {
00298                         $vals['logid'] = intval( $row->rc_logid );
00299                         $vals['logtype'] = $row->rc_log_type;
00300                         $vals['logaction'] = $row->rc_log_action;
00301                         $logEntry = DatabaseLogEntry::newFromRow( (array)$row );
00302                         ApiQueryLogEvents::addLogParams(
00303                                 $this->getResult(),
00304                                 $vals,
00305                                 $logEntry->getParameters(),
00306                                 $logEntry->getType(),
00307                                 $logEntry->getSubtype(),
00308                                 $logEntry->getTimestamp()
00309                         );
00310                 }
00311
00312                 return $vals;
00313         }
00314
00315         public function getAllowedParams() {
00316                 return array(
00317                         'allrev' => false,
00318                         'start' => array(
00319                                 ApiBase::PARAM_TYPE => 'timestamp'
00320                         ),
00321                         'end' => array(
00322                                 ApiBase::PARAM_TYPE => 'timestamp'
00323                         ),
00324                         'namespace' => array (
00325                                 ApiBase::PARAM_ISMULTI => true,
00326                                 ApiBase::PARAM_TYPE => 'namespace'
00327                         ),
00328                         'user' => array(
00329                                 ApiBase::PARAM_TYPE => 'user',
00330                         ),
00331                         'excludeuser' => array(
00332                                 ApiBase::PARAM_TYPE => 'user',
00333                         ),
00334                         'dir' => array(
00335                                 ApiBase::PARAM_DFLT => 'older',
00336                                 ApiBase::PARAM_TYPE => array(
00337                                         'newer',
00338                                         'older'
00339                                 )
00340                         ),
00341                         'limit' => array(
00342                                 ApiBase::PARAM_DFLT => 10,
00343                                 ApiBase::PARAM_TYPE => 'limit',
00344                                 ApiBase::PARAM_MIN => 1,
00345                                 ApiBase::PARAM_MAX => ApiBase::LIMIT_BIG1,
00346                                 ApiBase::PARAM_MAX2 => ApiBase::LIMIT_BIG2
00347                         ),
00348                         'prop' => array(
00349                                 ApiBase::PARAM_ISMULTI => true,
00350                                 ApiBase::PARAM_DFLT => 'ids|title|flags',
00351                                 ApiBase::PARAM_TYPE => array(
00352                                         'ids',
00353                                         'title',
00354                                         'flags',
00355                                         'user',
00356                                         'userid',
00357                                         'comment',
00358                                         'parsedcomment',
00359                                         'timestamp',
00360                                         'patrol',
00361                                         'sizes',
00362                                         'notificationtimestamp',
00363                                         'loginfo',
00364                                 )
00365                         ),
00366                         'show' => array(
00367                                 ApiBase::PARAM_ISMULTI => true,
00368                                 ApiBase::PARAM_TYPE => array(
00369                                         'minor',
00370                                         '!minor',
00371                                         'bot',
00372                                         '!bot',
00373                                         'anon',
00374                                         '!anon',
00375                                         'patrolled',
00376                                         '!patrolled',
00377                                 )
00378                         ),
00379                         'owner' => array(
00380                                 ApiBase::PARAM_TYPE => 'user'
00381                         ),
00382                         'token' => array(
00383                                 ApiBase::PARAM_TYPE => 'string'
00384                         )
00385                 );
00386         }
00387
00388         public function getParamDescription() {
00389                 $p = $this->getModulePrefix();
00390                 return array(
00391                         'allrev' => 'Include multiple revisions of the same page within given timeframe',
00392                         'start' => 'The timestamp to start enumerating from',
00393                         'end' => 'The timestamp to end enumerating',
00394                         'namespace' => 'Filter changes to only the given namespace(s)',
00395                         'user' => 'Only list changes by this user',
00396                         'excludeuser' => 'Don\'t list changes by this user',
00397                         'dir' => $this->getDirectionDescription( $p ),
00398                         'limit' => 'How many total results to return per request',
00399                         'prop' => array(
00400                                 'Which additional items to get (non-generator mode only).',
00401                                 ' ids                    - Adds revision ids and page ids',
00402                                 ' title                  - Adds title of the page',
00403                                 ' flags                  - Adds flags for the edit',
00404                                 ' user                   - Adds the user who made the edit',
00405                                 ' userid                 - Adds user id of whom made the edit',
00406                                 ' comment                - Adds comment of the edit',
00407                                 ' parsedcomment          - Adds parsed comment of the edit',
00408                                 ' timestamp              - Adds timestamp of the edit',
00409                                 ' patrol                 - Tags edits that are patrolled',
00410                                 ' sizes                  - Adds the old and new lengths of the page',
00411                                 ' notificationtimestamp  - Adds timestamp of when the user was last notified about the edit',
00412                                 ' loginfo                - Adds log information where appropriate',
00413                         ),
00414                         'show' => array(
00415                                 'Show only items that meet this criteria.',
00416                                 "For example, to see only minor edits done by logged-in users, set {$p}show=minor|!anon"
00417                         ),
00418                         'owner' => 'The name of the user whose watchlist you\'d like to access',
00419                         'token' => 'Give a security token (settable in preferences) to allow access to another user\'s watchlist'
00420                 );
00421         }
00422
00423         public function getResultProperties() {
00424                 global $wgLogTypes;
00425                 return array(
00426                         'ids' => array(
00427                                 'pageid' => 'integer',
00428                                 'revid' => 'integer',
00429                                 'old_revid' => 'integer'
00430                         ),
00431                         'title' => array(
00432                                 'ns' => 'namespace',
00433                                 'title' => 'string'
00434                         ),
00435                         'user' => array(
00436                                 'user' => 'string',
00437                                 'anon' => 'boolean'
00438                         ),
00439                         'userid' => array(
00440                                 'userid' => 'integer',
00441                                 'anon' => 'boolean'
00442                         ),
00443                         'flags' => array(
00444                                 'new' => 'boolean',
00445                                 'minor' => 'boolean',
00446                                 'bot' => 'boolean'
00447                         ),
00448                         'patrol' => array(
00449                                 'patrolled' => 'boolean'
00450                         ),
00451                         'timestamp' => array(
00452                                 'timestamp' => 'timestamp'
00453                         ),
00454                         'sizes' => array(
00455                                 'oldlen' => 'integer',
00456                                 'newlen' => 'integer'
00457                         ),
00458                         'notificationtimestamp' => array(
00459                                 'notificationtimestamp' => array(
00460                                         ApiBase::PROP_TYPE => 'timestamp',
00461                                         ApiBase::PROP_NULLABLE => true
00462                                 )
00463                         ),
00464                         'comment' => array(
00465                                 'comment' => array(
00466                                         ApiBase::PROP_TYPE => 'string',
00467                                         ApiBase::PROP_NULLABLE => true
00468                                 )
00469                         ),
00470                         'parsedcomment' => array(
00471                                 'parsedcomment' => array(
00472                                         ApiBase::PROP_TYPE => 'string',
00473                                         ApiBase::PROP_NULLABLE => true
00474                                 )
00475                         ),
00476                         'loginfo' => array(
00477                                 'logid' => array(
00478                                         ApiBase::PROP_TYPE => 'integer',
00479                                         ApiBase::PROP_NULLABLE => true
00480                                 ),
00481                                 'logtype' => array(
00482                                         ApiBase::PROP_TYPE => $wgLogTypes,
00483                                         ApiBase::PROP_NULLABLE => true
00484                                 ),
00485                                 'logaction' => array(
00486                                         ApiBase::PROP_TYPE => 'string',
00487                                         ApiBase::PROP_NULLABLE => true
00488                                 )
00489                         )
00490                 );
00491         }
00492
00493         public function getDescription() {
00494                 return "Get all recent changes to pages in the logged in user's watchlist";
00495         }
00496
00497         public function getPossibleErrors() {
00498                 return array_merge( parent::getPossibleErrors(), array(
00499                         array( 'code' => 'bad_wlowner', 'info' => 'Specified user does not exist' ),
00500                         array( 'code' => 'bad_wltoken', 'info' => 'Incorrect watchlist token provided -- please set a correct token in Special:Preferences' ),
00501                         array( 'code' => 'notloggedin', 'info' => 'You must be logged-in to have a watchlist' ),
00502                         array( 'code' => 'patrol', 'info' => 'patrol property is not available' ),
00503                         array( 'show' ),
00504                         array( 'code' => 'permissiondenied', 'info' => 'You need the patrol right to request the patrolled flag' ),
00505                         array( 'code' => 'user-excludeuser', 'info' => 'user and excludeuser cannot be used together' ),
00506                 ) );
00507         }
00508
00509         public function getExamples() {
00510                 return array(
00511                         'api.php?action=query&list=watchlist',
00512                         'api.php?action=query&list=watchlist&wlprop=ids|title|timestamp|user|comment',
00513                         'api.php?action=query&list=watchlist&wlallrev=&wlprop=ids|title|timestamp|user|comment',
00514                         'api.php?action=query&generator=watchlist&prop=info',
00515                         'api.php?action=query&generator=watchlist&gwlallrev=&prop=revisions&rvprop=timestamp|user',
00516                         'api.php?action=query&list=watchlist&wlowner=Bob_Smith&wltoken=123ABC'
00517                 );
00518         }
00519
00520         public function getHelpUrls() {
00521                 return 'https://www.mediawiki.org/wiki/API:Watchlist';
00522         }
00523 }