| Index: trunk/phase3/includes/api/ApiMain.php |
| — | — | @@ -546,6 +546,10 @@ |
| 547 | 547 | return $this->mIsSysop; |
| 548 | 548 | } |
| 549 | 549 | |
| | 550 | + /** |
| | 551 | + * Check whether the current user is allowed to use high limits |
| | 552 | + * @return bool |
| | 553 | + */ |
| 550 | 554 | public function canApiHighLimits() { |
| 551 | 555 | if (!isset($this->mCanApiHighLimits)) { |
| 552 | 556 | global $wgUser; |
| — | — | @@ -555,6 +559,10 @@ |
| 556 | 560 | return $this->mCanApiHighLimits; |
| 557 | 561 | } |
| 558 | 562 | |
| | 563 | + /** |
| | 564 | + * Check whether the user wants us to show version information in the API help |
| | 565 | + * @return bool |
| | 566 | + */ |
| 559 | 567 | public function getShowVersions() { |
| 560 | 568 | return $this->mShowVersions; |
| 561 | 569 | } |
| Index: trunk/phase3/includes/api/ApiQueryBase.php |
| — | — | @@ -48,6 +48,9 @@ |
| 49 | 49 | $this->resetQueryParams(); |
| 50 | 50 | } |
| 51 | 51 | |
| | 52 | + /** |
| | 53 | + * Blank the internal arrays with query parameters |
| | 54 | + */ |
| 52 | 55 | protected function resetQueryParams() { |
| 53 | 56 | $this->tables = array (); |
| 54 | 57 | $this->where = array (); |
| — | — | @@ -55,6 +58,11 @@ |
| 56 | 59 | $this->options = array (); |
| 57 | 60 | } |
| 58 | 61 | |
| | 62 | + /** |
| | 63 | + * Add a set of tables to the internal array |
| | 64 | + * @param mixed $tables Table name or array of table names |
| | 65 | + * @param mixed $alias Table alias, or null for no alias. Cannot be used with multiple tables |
| | 66 | + */ |
| 59 | 67 | protected function addTables($tables, $alias = null) { |
| 60 | 68 | if (is_array($tables)) { |
| 61 | 69 | if (!is_null($alias)) |
| — | — | @@ -67,6 +75,18 @@ |
| 68 | 76 | } |
| 69 | 77 | } |
| 70 | 78 | |
| | 79 | + /** |
| | 80 | + * Add a JOIN to the internal array. |
| | 81 | + * |
| | 82 | + * Example for: a LEFT JOIN page AS b ON foo=bar RIGHT JOIN c ON foo=baz AND bar=3 |
| | 83 | + * |
| | 84 | + * addJoin(array('a', 'page', 'c'), array(ApiQueryBase::LEFT_JOIN, ApiQueryBase::RIGHT_JOIN), |
| | 85 | + * array('foo=bar', array('foo=baz', 'bar' => 3), array(null, 'b', null)) |
| | 86 | + * @param array $tables Array of table names |
| | 87 | + * @param array $types Array of join types (either LEFT_JOIN or RIGHT_JOIN) |
| | 88 | + * @param array $onClauses Array of ON clauses. Each element is formed like addWhere()'s parameter |
| | 89 | + * @param array $aliases Array of table aliases, or null for no alias |
| | 90 | + */ |
| 71 | 91 | protected function addJoin($tables, $types, $onClauses, $aliases = null) { |
| 72 | 92 | if(is_null($aliases)) |
| 73 | 93 | foreach($tables as $unused) |
| — | — | @@ -93,9 +113,11 @@ |
| 94 | 114 | } |
| 95 | 115 | $this->addTables($sql); |
| 96 | 116 | } |
| 97 | | - |
| 98 | | - |
| 99 | 117 | |
| | 118 | + /** |
| | 119 | + * Add a set of fields to select to the internal array |
| | 120 | + * @param mixed $value Field name or array of field names |
| | 121 | + */ |
| 100 | 122 | protected function addFields($value) { |
| 101 | 123 | if (is_array($value)) |
| 102 | 124 | $this->fields = array_merge($this->fields, $value); |
| — | — | @@ -103,6 +125,12 @@ |
| 104 | 126 | $this->fields[] = $value; |
| 105 | 127 | } |
| 106 | 128 | |
| | 129 | + /** |
| | 130 | + * Same as addFields(), but add the fields only if a condition is met |
| | 131 | + * @param mixed $value See addFields() |
| | 132 | + * @param bool $condition If false, do nothing |
| | 133 | + * @return bool $condition |
| | 134 | + */ |
| 107 | 135 | protected function addFieldsIf($value, $condition) { |
| 108 | 136 | if ($condition) { |
| 109 | 137 | $this->addFields($value); |
| — | — | @@ -111,6 +139,15 @@ |
| 112 | 140 | return false; |
| 113 | 141 | } |
| 114 | 142 | |
| | 143 | + /** |
| | 144 | + * Add a set of WHERE clauses to the internal array. |
| | 145 | + * Clauses can be formatted as 'foo=bar' or array('foo' => 'bar'), |
| | 146 | + * the latter only works if the value is a constant (i.e. not another field) |
| | 147 | + * |
| | 148 | + * For example, array('foo=bar', 'baz' => 3, 'bla' => 'foo') translates |
| | 149 | + * to "foo=bar AND baz='3' AND bla='foo'" |
| | 150 | + * @param mixed $value String or array |
| | 151 | + */ |
| 115 | 152 | protected function addWhere($value) { |
| 116 | 153 | if (is_array($value)) |
| 117 | 154 | $this->where = array_merge($this->where, $value); |
| — | — | @@ -118,6 +155,12 @@ |
| 119 | 156 | $this->where[] = $value; |
| 120 | 157 | } |
| 121 | 158 | |
| | 159 | + /** |
| | 160 | + * Same as addWhere(), but add the WHERE clauses only if a condition is met |
| | 161 | + * @param mixed $value See addWhere() |
| | 162 | + * @param bool $condition If false, do nothing |
| | 163 | + * @return bool $condition |
| | 164 | + */ |
| 122 | 165 | protected function addWhereIf($value, $condition) { |
| 123 | 166 | if ($condition) { |
| 124 | 167 | $this->addWhere($value); |
| — | — | @@ -126,11 +169,24 @@ |
| 127 | 170 | return false; |
| 128 | 171 | } |
| 129 | 172 | |
| | 173 | + /** |
| | 174 | + * Equivalent to addWhere(array($field => $value)) |
| | 175 | + * @param string $field Field name |
| | 176 | + * @param string $value Value; ignored if nul; |
| | 177 | + */ |
| 130 | 178 | protected function addWhereFld($field, $value) { |
| 131 | 179 | if (!is_null($value)) |
| 132 | 180 | $this->where[$field] = $value; |
| 133 | 181 | } |
| 134 | 182 | |
| | 183 | + /** |
| | 184 | + * Add a WHERE clause corresponding to a range, and an ORDER BY |
| | 185 | + * clause to sort in the right direction |
| | 186 | + * @param string $field Field name |
| | 187 | + * @param string $dir If 'newer', sort in ascending order, otherwise sort in descending order |
| | 188 | + * @param string $start Value to start the list at. If $dir == 'newer' this is the lower boundary, otherwise it's the upper boundary |
| | 189 | + * @param string $end Value to end the list at. If $dir == 'newer' this is the upper boundary, otherwise it's the lower boundary |
| | 190 | + */ |
| 135 | 191 | protected function addWhereRange($field, $dir, $start, $end) { |
| 136 | 192 | $isDirNewer = ($dir === 'newer'); |
| 137 | 193 | $after = ($isDirNewer ? '>=' : '<='); |
| — | — | @@ -150,6 +206,11 @@ |
| 151 | 207 | $this->addOption('ORDER BY', $this->options['ORDER BY'] . ', ' . $order); |
| 152 | 208 | } |
| 153 | 209 | |
| | 210 | + /** |
| | 211 | + * Add an option such as LIMIT or USE INDEX |
| | 212 | + * @param string $name Option name |
| | 213 | + * @param string $value Option value |
| | 214 | + */ |
| 154 | 215 | protected function addOption($name, $value = null) { |
| 155 | 216 | if (is_null($value)) |
| 156 | 217 | $this->options[] = $name; |
| — | — | @@ -157,6 +218,11 @@ |
| 158 | 219 | $this->options[$name] = $value; |
| 159 | 220 | } |
| 160 | 221 | |
| | 222 | + /** |
| | 223 | + * Execute a SELECT query based on the values in the internal arrays |
| | 224 | + * @param string $method Function the query should be attributed to. You should usually use __METHOD__ here |
| | 225 | + * @return ResultWrapper |
| | 226 | + */ |
| 161 | 227 | protected function select($method) { |
| 162 | 228 | |
| 163 | 229 | // getDB has its own profileDBIn/Out calls |
| — | — | @@ -169,6 +235,11 @@ |
| 170 | 236 | return $res; |
| 171 | 237 | } |
| 172 | 238 | |
| | 239 | + /** |
| | 240 | + * Estimate the row count for the SELECT query that would be run if we |
| | 241 | + * called select() right now, and check if it's acceptable. |
| | 242 | + * @return bool true if acceptable, false otherwise |
| | 243 | + */ |
| 173 | 244 | protected function checkRowCount() { |
| 174 | 245 | $db = $this->getDB(); |
| 175 | 246 | $this->profileDBIn(); |
| — | — | @@ -181,6 +252,12 @@ |
| 182 | 253 | return true; |
| 183 | 254 | } |
| 184 | 255 | |
| | 256 | + /** |
| | 257 | + * Add information (title and namespace) about a Title object to a result array |
| | 258 | + * @param array $arr Result array � la ApiResult |
| | 259 | + * @param Title $title Title object |
| | 260 | + * @param string $prefix Module prefix |
| | 261 | + */ |
| 185 | 262 | public static function addTitleInfo(&$arr, $title, $prefix='') { |
| 186 | 263 | $arr[$prefix . 'ns'] = intval($title->getNamespace()); |
| 187 | 264 | $arr[$prefix . 'title'] = $title->getPrefixedText(); |
| — | — | @@ -189,19 +266,23 @@ |
| 190 | 267 | /** |
| 191 | 268 | * Override this method to request extra fields from the pageSet |
| 192 | 269 | * using $pageSet->requestField('fieldName') |
| | 270 | + * @param ApiPageSet $pageSet |
| 193 | 271 | */ |
| 194 | 272 | public function requestExtraData($pageSet) { |
| 195 | 273 | } |
| 196 | 274 | |
| 197 | 275 | /** |
| 198 | 276 | * Get the main Query module |
| | 277 | + * @return ApiQuery |
| 199 | 278 | */ |
| 200 | 279 | public function getQuery() { |
| 201 | 280 | return $this->mQueryModule; |
| 202 | 281 | } |
| 203 | 282 | |
| 204 | 283 | /** |
| 205 | | - * Add sub-element under the page element with the given pageId. |
| | 284 | + * Add a sub-element under the page element with the given page ID |
| | 285 | + * @param int $pageId Page ID |
| | 286 | + * @param array $data Data array � la ApiResult |
| 206 | 287 | */ |
| 207 | 288 | protected function addPageSubItems($pageId, $data) { |
| 208 | 289 | $result = $this->getResult(); |
| — | — | @@ -211,19 +292,21 @@ |
| 212 | 293 | $data); |
| 213 | 294 | } |
| 214 | 295 | |
| | 296 | + /** |
| | 297 | + * Set a query-continue value |
| | 298 | + * @param $paramName Parameter name |
| | 299 | + * @param $paramValue Parameter value |
| | 300 | + */ |
| 215 | 301 | protected function setContinueEnumParameter($paramName, $paramValue) { |
| 216 | 302 | |
| 217 | 303 | $paramName = $this->encodeParamName($paramName); |
| 218 | 304 | $msg = array( $paramName => $paramValue ); |
| 219 | | - |
| 220 | | -// This is an alternative continue format as a part of the URL string |
| 221 | | -// ApiResult :: setContent($msg, $paramName . '=' . urlencode($paramValue)); |
| 222 | | - |
| 223 | 305 | $this->getResult()->addValue('query-continue', $this->getModuleName(), $msg); |
| 224 | 306 | } |
| 225 | 307 | |
| 226 | 308 | /** |
| 227 | 309 | * Get the Query database connection (readonly) |
| | 310 | + * @return Database |
| 228 | 311 | */ |
| 229 | 312 | protected function getDB() { |
| 230 | 313 | if (is_null($this->mDb)) |
| — | — | @@ -236,6 +319,10 @@ |
| 237 | 320 | * If no such connection has been requested before, it will be created. |
| 238 | 321 | * Subsequent calls with the same $name will return the same connection |
| 239 | 322 | * as the first, regardless of $db or $groups new values. |
| | 323 | + * @param string $name Name to assign to the database connection |
| | 324 | + * @param int $db One of the DB_* constants |
| | 325 | + * @param array $groups Query groups |
| | 326 | + * @return Database |
| 240 | 327 | */ |
| 241 | 328 | public function selectNamedDB($name, $db, $groups) { |
| 242 | 329 | $this->mDb = $this->getQuery()->getNamedDB($name, $db, $groups); |
| — | — | @@ -243,7 +330,7 @@ |
| 244 | 331 | |
| 245 | 332 | /** |
| 246 | 333 | * Get the PageSet object to work on |
| 247 | | - * @return ApiPageSet data |
| | 334 | + * @return ApiPageSet |
| 248 | 335 | */ |
| 249 | 336 | protected function getPageSet() { |
| 250 | 337 | return $this->getQuery()->getPageSet(); |
| — | — | @@ -253,15 +340,29 @@ |
| 254 | 341 | * This is a very simplistic utility function |
| 255 | 342 | * to convert a non-namespaced title string to a db key. |
| 256 | 343 | * It will replace all ' ' with '_' |
| | 344 | + * @param string $title Page title with spaces |
| | 345 | + * @return string Page title with underscores |
| 257 | 346 | */ |
| 258 | 347 | public static function titleToKey($title) { |
| 259 | 348 | return str_replace(' ', '_', $title); |
| 260 | 349 | } |
| 261 | 350 | |
| | 351 | + /** |
| | 352 | + * The inverse of titleToKey() |
| | 353 | + * @param string $key Page title with underscores |
| | 354 | + * @return string Page title with spaces |
| | 355 | + */ |
| 262 | 356 | public static function keyToTitle($key) { |
| 263 | 357 | return str_replace('_', ' ', $key); |
| 264 | 358 | } |
| 265 | 359 | |
| | 360 | + /** |
| | 361 | + * Check whether the current user requested a certain token and |
| | 362 | + * is actually allowed to request it. |
| | 363 | + * @param array $tokenArr Array of tokens the user requested |
| | 364 | + * @param string $action Action to check for |
| | 365 | + * @return bool true if the user requested the token and is allowed to, false otherwise |
| | 366 | + */ |
| 266 | 367 | public function getTokenFlag($tokenArr, $action) { |
| 267 | 368 | if ($this->getMain()->getRequest()->getVal('callback') !== null) { |
| 268 | 369 | // Don't do any session-specific data. |
| — | — | @@ -277,6 +378,10 @@ |
| 278 | 379 | return false; |
| 279 | 380 | } |
| 280 | 381 | |
| | 382 | + /** |
| | 383 | + * Get version string for use in the API help output |
| | 384 | + * @return string |
| | 385 | + */ |
| 281 | 386 | public static function getBaseVersion() { |
| 282 | 387 | return __CLASS__ . ': $Id$'; |
| 283 | 388 | } |
| — | — | @@ -294,6 +399,10 @@ |
| 295 | 400 | $this->mIsGenerator = false; |
| 296 | 401 | } |
| 297 | 402 | |
| | 403 | + /** |
| | 404 | + * Switch this module to generator mode. By default, generator mode is |
| | 405 | + * switched off and the module acts like a normal query module. |
| | 406 | + */ |
| 298 | 407 | public function setGeneratorMode() { |
| 299 | 408 | $this->mIsGenerator = true; |
| 300 | 409 | } |