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