includes/api/ApiQueryBase.php

   1 <?php
   2
   3 /*
   4  * Created on Sep 7, 2006
   5  *
   6  * API for MediaWiki 1.8+
   7  *
   8  * Copyright (C) 2006 Yuri Astrakhan <Firstname><Lastname>@gmail.com
   9  *
  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.
  14  *
  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.
  19  *
  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  * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  23  * http://www.gnu.org/copyleft/gpl.html
  24  */
  25
  26 if (!defined('MEDIAWIKI')) {
  27         // Eclipse helper - will be ignored in production
  28         require_once ('ApiBase.php');
  29 }
  30
  31 /**
  32  * This is a base class for all Query modules.
  33  * It provides some common functionality such as constructing various SQL queries.
  34  *
  35  * @addtogroup API
  36  */
  37 abstract class ApiQueryBase extends ApiBase {
  38
  39         private $mQueryModule, $mDb, $tables, $where, $fields, $options;
  40
  41         public function __construct($query, $moduleName, $paramPrefix = '') {
  42                 parent :: __construct($query->getMain(), $moduleName, $paramPrefix);
  43                 $this->mQueryModule = $query;
  44                 $this->mDb = null;
  45                 $this->resetQueryParams();
  46         }
  47
  48         protected function resetQueryParams() {
  49                 $this->tables = array ();
  50                 $this->where = array ();
  51                 $this->fields = array ();
  52                 $this->options = array ();
  53         }
  54
  55         protected function addTables($value) {
  56                 if (is_array($value))
  57                         $this->tables = array_merge($this->tables, $value);
  58                 else
  59                         $this->tables[] = $value;
  60         }
  61
  62         protected function addFields($value) {
  63                 if (is_array($value))
  64                         $this->fields = array_merge($this->fields, $value);
  65                 else
  66                         $this->fields[] = $value;
  67         }
  68
  69         protected function addFieldsIf($value, $condition) {
  70                 if ($condition) {
  71                         $this->addFields($value);
  72                         return true;
  73                 }
  74                 return false;
  75         }
  76
  77         protected function addWhere($value) {
  78                 if (is_array($value))
  79                         $this->where = array_merge($this->where, $value);
  80                 else
  81                         $this->where[] = $value;
  82         }
  83
  84         protected function addWhereIf($value, $condition) {
  85                 if ($condition) {
  86                         $this->addWhere($value);
  87                         return true;
  88                 }
  89                 return false;
  90         }
  91
  92         protected function addWhereFld($field, $value) {
  93                 if (!is_null($value))
  94                         $this->where[$field] = $value;
  95         }
  96
  97         protected function addWhereRange($field, $dir, $start, $end) {
  98                 $isDirNewer = ($dir === 'newer');
  99                 $after = ($isDirNewer ? '>=' : '<=');
 100                 $before = ($isDirNewer ? '<=' : '>=');
 101                 $db = $this->getDB();
 102
 103                 if (!is_null($start))
 104                         $this->addWhere($field . $after . $db->addQuotes($start));
 105
 106                 if (!is_null($end))
 107                         $this->addWhere($field . $before . $db->addQuotes($end));
 108
 109                 $this->addOption('ORDER BY', $field . ($isDirNewer ? '' : ' DESC'));
 110         }
 111
 112         protected function addOption($name, $value = null) {
 113                 if (is_null($value))
 114                         $this->options[] = $name;
 115                 else
 116                         $this->options[$name] = $value;
 117         }
 118
 119         protected function select($method) {
 120
 121                 // getDB has its own profileDBIn/Out calls
 122                 $db = $this->getDB();
 123
 124                 $this->profileDBIn();
 125                 $res = $db->select($this->tables, $this->fields, $this->where, $method, $this->options);
 126                 $this->profileDBOut();
 127
 128                 return $res;
 129         }
 130
 131         protected function addRowInfo($prefix, $row) {
 132
 133                 $vals = array ();
 134
 135                 // ID
 136                 if ( isset( $row-> { $prefix . '_id' } ) )
 137                         $vals[$prefix . 'id'] = intval( $row-> { $prefix . '_id' } );
 138
 139                 // Title
 140                 $title = ApiQueryBase :: addRowInfo_title($row, $prefix . '_namespace', $prefix . '_title');
 141                 if ($title)
 142                         ApiQueryBase :: addTitleInfo($vals, $title);
 143
 144                 switch ($prefix) {
 145
 146                         case 'page' :
 147                                 // page_is_redirect
 148                                 @ $tmp = $row->page_is_redirect;
 149                                 if ($tmp)
 150                                         $vals['redirect'] = '';
 151
 152                                 break;
 153
 154                         case 'rc' :
 155                                 // PageId
 156                                 @ $tmp = $row->rc_cur_id;
 157                                 if (!is_null($tmp))
 158                                         $vals['pageid'] = intval($tmp);
 159
 160                                 @ $tmp = $row->rc_this_oldid;
 161                                 if (!is_null($tmp))
 162                                         $vals['revid'] = intval($tmp);
 163
 164                                 if ( isset( $row->rc_last_oldid ) )
 165                                         $vals['old_revid'] = intval( $row->rc_last_oldid );
 166
 167                                 $title = ApiQueryBase :: addRowInfo_title($row, 'rc_moved_to_ns', 'rc_moved_to_title');
 168                                 if ($title) {
 169                                         if (!$title->userCanRead())
 170                                                 return false;
 171                                         ApiQueryBase :: addTitleInfo($vals, $title, 'new_');
 172                                 }
 173
 174                                 if ( isset( $row->rc_patrolled ) )
 175                                         $vals['patrolled'] = '';
 176
 177                                 break;
 178
 179                         case 'log' :
 180                                 // PageId
 181                                 @ $tmp = $row->page_id;
 182                                 if (!is_null($tmp))
 183                                         $vals['pageid'] = intval($tmp);
 184
 185                                 if ($row->log_params !== '') {
 186                                         $params = explode("\n", $row->log_params);
 187                                         if ($row->log_type == 'move' && isset ($params[0])) {
 188                                                 $newTitle = Title :: newFromText($params[0]);
 189                                                 if ($newTitle) {
 190                                                         ApiQueryBase :: addTitleInfo($vals, $newTitle, 'new_');
 191                                                         $params = null;
 192                                                 }
 193                                         }
 194
 195                                         if (!empty ($params)) {
 196                                                 $this->getResult()->setIndexedTagName($params, 'param');
 197                                                 $vals = array_merge($vals, $params);
 198                                         }
 199                                 }
 200
 201                                 break;
 202
 203                         case 'rev' :
 204                                 // PageID
 205                                 @ $tmp = $row->rev_page;
 206                                 if (!is_null($tmp))
 207                                         $vals['pageid'] = intval($tmp);
 208                 }
 209
 210                 // Type
 211                 @ $tmp = $row-> { $prefix . '_type' };
 212                 if (!is_null($tmp))
 213                         $vals['type'] = $tmp;
 214
 215                 // Action
 216                 @ $tmp = $row-> { $prefix . '_action' };
 217                 if (!is_null($tmp))
 218                         $vals['action'] = $tmp;
 219
 220                 // Old ID
 221                 @ $tmp = $row-> { $prefix . '_text_id' };
 222                 if (!is_null($tmp))
 223                         $vals['oldid'] = intval($tmp);
 224
 225                 // User Name / Anon IP
 226                 @ $tmp = $row-> { $prefix . '_user_text' };
 227                 if (is_null($tmp))
 228                         @ $tmp = $row->user_name;
 229                 if (!is_null($tmp)) {
 230                         $vals['user'] = $tmp;
 231                         @ $tmp = !$row-> { $prefix . '_user' };
 232                         if (!is_null($tmp) && $tmp)
 233                                 $vals['anon'] = '';
 234                 }
 235
 236                 // Bot Edit
 237                 @ $tmp = $row-> { $prefix . '_bot' };
 238                 if (!is_null($tmp) && $tmp)
 239                         $vals['bot'] = '';
 240
 241                 // New Edit
 242                 @ $tmp = $row-> { $prefix . '_new' };
 243                 if (is_null($tmp))
 244                         @ $tmp = $row-> { $prefix . '_is_new' };
 245                 if (!is_null($tmp) && $tmp)
 246                         $vals['new'] = '';
 247
 248                 // Minor Edit
 249                 @ $tmp = $row-> { $prefix . '_minor_edit' };
 250                 if (is_null($tmp))
 251                         @ $tmp = $row-> { $prefix . '_minor' };
 252                 if (!is_null($tmp) && $tmp)
 253                         $vals['minor'] = '';
 254
 255                 // Timestamp
 256                 @ $tmp = $row-> { $prefix . '_timestamp' };
 257                 if (!is_null($tmp))
 258                         $vals['timestamp'] = wfTimestamp(TS_ISO_8601, $tmp);
 259
 260                 // Comment
 261                 @ $tmp = $row-> { $prefix . '_comment' };
 262                 if (!empty ($tmp)) // optimize bandwidth
 263                         $vals['comment'] = $tmp;
 264
 265                 return $vals;
 266         }
 267
 268         protected static function addTitleInfo(&$arr, $title, $prefix='') {
 269                 $arr[$prefix . 'ns'] = $title->getNamespace();
 270                 $arr[$prefix . 'title'] = $title->getPrefixedText();
 271                 if (!$title->userCanRead())
 272                         $arr[$prefix . 'inaccessible'] = "";
 273         }
 274
 275         private static function addRowInfo_title($row, $nsfld, $titlefld) {
 276                 if ( isset( $row-> $nsfld ) ) {
 277                         $ns = $row-> $nsfld;
 278                         @ $title = $row-> $titlefld;
 279                         if (!empty ($title))
 280                                 return Title :: makeTitle($ns, $title);
 281                 }
 282                 return false;
 283         }
 284
 285         /**
 286          * Override this method to request extra fields from the pageSet
 287          * using $this->getPageSet()->requestField('fieldName')
 288          */
 289         public function requestExtraData() {
 290         }
 291
 292         /**
 293          * Get the main Query module
 294          */
 295         public function getQuery() {
 296                 return $this->mQueryModule;
 297         }
 298
 299         protected function setContinueEnumParameter($paramName, $paramValue) {
 300                 $msg = array (
 301                         $this->encodeParamName($paramName
 302                 ) => $paramValue);
 303                 $this->getResult()->addValue('query-continue', $this->getModuleName(), $msg);
 304         }
 305
 306         /**
 307          * Get the Query database connection (readonly)
 308          */
 309         protected function getDB() {
 310                 if (is_null($this->mDb))
 311                         $this->mDb = $this->getQuery()->getDB();
 312                 return $this->mDb;
 313         }
 314
 315         /**
 316          * Selects the query database connection with the given name.
 317          * If no such connection has been requested before, it will be created.
 318          * Subsequent calls with the same $name will return the same connection
 319          * as the first, regardless of $db or $groups new values.
 320          */
 321         public function selectNamedDB($name, $db, $groups) {
 322                 $this->mDb = $this->getQuery()->getNamedDB($name, $db, $groups);
 323         }
 324
 325         /**
 326          * Get the PageSet object to work on
 327          * @return ApiPageSet data
 328          */
 329         protected function getPageSet() {
 330                 return $this->getQuery()->getPageSet();
 331         }
 332
 333         /**
 334          * This is a very simplistic utility function
 335          * to convert a non-namespaced title string to a db key.
 336          * It will replace all ' ' with '_'
 337          */
 338         public static function titleToKey($title) {
 339                 return str_replace(' ', '_', $title);
 340         }
 341
 342         public static function keyToTitle($key) {
 343                 return str_replace('_', ' ', $key);
 344         }
 345
 346         public static function getBaseVersion() {
 347                 return __CLASS__ . ': $Id$';
 348         }
 349 }
 350
 351 /**
 352  * @addtogroup API
 353  */
 354 abstract class ApiQueryGeneratorBase extends ApiQueryBase {
 355
 356         private $mIsGenerator;
 357
 358         public function __construct($query, $moduleName, $paramPrefix = '') {
 359                 parent :: __construct($query, $moduleName, $paramPrefix);
 360                 $this->mIsGenerator = false;
 361         }
 362
 363         public function setGeneratorMode() {
 364                 $this->mIsGenerator = true;
 365         }
 366
 367         /**
 368          * Overrides base class to prepend 'g' to every generator parameter
 369          */
 370         public function encodeParamName($paramName) {
 371                 if ($this->mIsGenerator)
 372                         return 'g' . parent :: encodeParamName($paramName);
 373                 else
 374                         return parent :: encodeParamName($paramName);
 375         }
 376
 377         /**
 378          * Execute this module as a generator
 379          * @param $resultPageSet PageSet: All output should be appended to this object
 380          */
 381         public abstract function executeGenerator($resultPageSet);
 382 }
 383 ?>