wikimedia /
mediawiki
Duplicate code is one of the most pungent code smells. A rule that is often used is to re-structure code once it is duplicated in three or more places.
Common duplication problems, and corresponding solutions are:
Complex classes like ApiQueryBase often do a lot of different things. To break such a class down, we need to identify a cohesive component within that class. A common approach to find such a component is to look for fields/methods that share the same prefixes, or suffixes. You can also have a look at the cohesion graph to spot any un-connected, or weakly-connected components.
Once you have determined the fields that belong together, you can apply the Extract Class refactoring. If the component makes sense as a sub-class, Extract Subclass is also a candidate, and is often faster.
While breaking up the class, it is a good idea to analyze how other classes use ApiQueryBase, and based on these observations, apply Extract Interface, too.
| 1 | <?php |
||
| 34 | abstract class ApiQueryBase extends ApiBase { |
||
| 35 | |||
| 36 | private $mQueryModule, $mDb, $tables, $where, $fields, $options, $join_conds; |
||
|
|
|||
| 37 | |||
| 38 | /** |
||
| 39 | * @param ApiQuery $queryModule |
||
| 40 | * @param string $moduleName |
||
| 41 | * @param string $paramPrefix |
||
| 42 | */ |
||
| 43 | public function __construct( ApiQuery $queryModule, $moduleName, $paramPrefix = '' ) { |
||
| 49 | |||
| 50 | /************************************************************************//** |
||
| 51 | * @name Methods to implement |
||
| 52 | * @{ |
||
| 53 | */ |
||
| 54 | |||
| 55 | /** |
||
| 56 | * Get the cache mode for the data generated by this module. Override |
||
| 57 | * this in the module subclass. For possible return values and other |
||
| 58 | * details about cache modes, see ApiMain::setCacheMode() |
||
| 59 | * |
||
| 60 | * Public caching will only be allowed if *all* the modules that supply |
||
| 61 | * data for a given request return a cache mode of public. |
||
| 62 | * |
||
| 63 | * @param array $params |
||
| 64 | * @return string |
||
| 65 | */ |
||
| 66 | public function getCacheMode( $params ) { |
||
| 69 | |||
| 70 | /** |
||
| 71 | * Override this method to request extra fields from the pageSet |
||
| 72 | * using $pageSet->requestField('fieldName') |
||
| 73 | * |
||
| 74 | * Note this only makes sense for 'prop' modules, as 'list' and 'meta' |
||
| 75 | * modules should not be using the pageset. |
||
| 76 | * |
||
| 77 | * @param ApiPageSet $pageSet |
||
| 78 | */ |
||
| 79 | public function requestExtraData( $pageSet ) { |
||
| 81 | |||
| 82 | /**@}*/ |
||
| 83 | |||
| 84 | /************************************************************************//** |
||
| 85 | * @name Data access |
||
| 86 | * @{ |
||
| 87 | */ |
||
| 88 | |||
| 89 | /** |
||
| 90 | * Get the main Query module |
||
| 91 | * @return ApiQuery |
||
| 92 | */ |
||
| 93 | public function getQuery() { |
||
| 96 | |||
| 97 | /** |
||
| 98 | * @see ApiBase::getParent() |
||
| 99 | */ |
||
| 100 | public function getParent() { |
||
| 103 | |||
| 104 | /** |
||
| 105 | * Get the Query database connection (read-only) |
||
| 106 | * @return Database |
||
| 107 | */ |
||
| 108 | protected function getDB() { |
||
| 115 | |||
| 116 | /** |
||
| 117 | * Selects the query database connection with the given name. |
||
| 118 | * See ApiQuery::getNamedDB() for more information |
||
| 119 | * @param string $name Name to assign to the database connection |
||
| 120 | * @param int $db One of the DB_* constants |
||
| 121 | * @param array $groups Query groups |
||
| 122 | * @return Database |
||
| 123 | */ |
||
| 124 | public function selectNamedDB( $name, $db, $groups ) { |
||
| 128 | |||
| 129 | /** |
||
| 130 | * Get the PageSet object to work on |
||
| 131 | * @return ApiPageSet |
||
| 132 | */ |
||
| 133 | protected function getPageSet() { |
||
| 136 | |||
| 137 | /**@}*/ |
||
| 138 | |||
| 139 | /************************************************************************//** |
||
| 140 | * @name Querying |
||
| 141 | * @{ |
||
| 142 | */ |
||
| 143 | |||
| 144 | /** |
||
| 145 | * Blank the internal arrays with query parameters |
||
| 146 | */ |
||
| 147 | protected function resetQueryParams() { |
||
| 154 | |||
| 155 | /** |
||
| 156 | * Add a set of tables to the internal array |
||
| 157 | * @param string|string[] $tables Table name or array of table names |
||
| 158 | * @param string|null $alias Table alias, or null for no alias. Cannot be |
||
| 159 | * used with multiple tables |
||
| 160 | */ |
||
| 161 | protected function addTables( $tables, $alias = null ) { |
||
| 175 | |||
| 176 | /** |
||
| 177 | * Add a set of JOIN conditions to the internal array |
||
| 178 | * |
||
| 179 | * JOIN conditions are formatted as [ tablename => [ jointype, conditions ] ] |
||
| 180 | * e.g. [ 'page' => [ 'LEFT JOIN', 'page_id=rev_page' ] ]. |
||
| 181 | * Conditions may be a string or an addWhere()-style array. |
||
| 182 | * @param array $join_conds JOIN conditions |
||
| 183 | */ |
||
| 184 | protected function addJoinConds( $join_conds ) { |
||
| 190 | |||
| 191 | /** |
||
| 192 | * Add a set of fields to select to the internal array |
||
| 193 | * @param array|string $value Field name or array of field names |
||
| 194 | */ |
||
| 195 | View Code Duplication | protected function addFields( $value ) { |
|
| 202 | |||
| 203 | /** |
||
| 204 | * Same as addFields(), but add the fields only if a condition is met |
||
| 205 | * @param array|string $value See addFields() |
||
| 206 | * @param bool $condition If false, do nothing |
||
| 207 | * @return bool $condition |
||
| 208 | */ |
||
| 209 | protected function addFieldsIf( $value, $condition ) { |
||
| 218 | |||
| 219 | /** |
||
| 220 | * Add a set of WHERE clauses to the internal array. |
||
| 221 | * Clauses can be formatted as 'foo=bar' or [ 'foo' => 'bar' ], |
||
| 222 | * the latter only works if the value is a constant (i.e. not another field) |
||
| 223 | * |
||
| 224 | * If $value is an empty array, this function does nothing. |
||
| 225 | * |
||
| 226 | * For example, [ 'foo=bar', 'baz' => 3, 'bla' => 'foo' ] translates |
||
| 227 | * to "foo=bar AND baz='3' AND bla='foo'" |
||
| 228 | * @param string|array $value |
||
| 229 | */ |
||
| 230 | View Code Duplication | protected function addWhere( $value ) { |
|
| 241 | |||
| 242 | /** |
||
| 243 | * Same as addWhere(), but add the WHERE clauses only if a condition is met |
||
| 244 | * @param string|array $value |
||
| 245 | * @param bool $condition If false, do nothing |
||
| 246 | * @return bool $condition |
||
| 247 | */ |
||
| 248 | protected function addWhereIf( $value, $condition ) { |
||
| 257 | |||
| 258 | /** |
||
| 259 | * Equivalent to addWhere(array($field => $value)) |
||
| 260 | * @param string $field Field name |
||
| 261 | * @param string $value Value; ignored if null or empty array; |
||
| 262 | */ |
||
| 263 | protected function addWhereFld( $field, $value ) { |
||
| 270 | |||
| 271 | /** |
||
| 272 | * Add a WHERE clause corresponding to a range, and an ORDER BY |
||
| 273 | * clause to sort in the right direction |
||
| 274 | * @param string $field Field name |
||
| 275 | * @param string $dir If 'newer', sort in ascending order, otherwise |
||
| 276 | * sort in descending order |
||
| 277 | * @param string $start Value to start the list at. If $dir == 'newer' |
||
| 278 | * this is the lower boundary, otherwise it's the upper boundary |
||
| 279 | * @param string $end Value to end the list at. If $dir == 'newer' this |
||
| 280 | * is the upper boundary, otherwise it's the lower boundary |
||
| 281 | * @param bool $sort If false, don't add an ORDER BY clause |
||
| 282 | */ |
||
| 283 | protected function addWhereRange( $field, $dir, $start, $end, $sort = true ) { |
||
| 307 | |||
| 308 | /** |
||
| 309 | * Add a WHERE clause corresponding to a range, similar to addWhereRange, |
||
| 310 | * but converts $start and $end to database timestamps. |
||
| 311 | * @see addWhereRange |
||
| 312 | * @param string $field |
||
| 313 | * @param string $dir |
||
| 314 | * @param string $start |
||
| 315 | * @param string $end |
||
| 316 | * @param bool $sort |
||
| 317 | */ |
||
| 318 | protected function addTimestampWhereRange( $field, $dir, $start, $end, $sort = true ) { |
||
| 323 | |||
| 324 | /** |
||
| 325 | * Add an option such as LIMIT or USE INDEX. If an option was set |
||
| 326 | * before, the old value will be overwritten |
||
| 327 | * @param string $name Option name |
||
| 328 | * @param string $value Option value |
||
| 329 | */ |
||
| 330 | protected function addOption( $name, $value = null ) { |
||
| 337 | |||
| 338 | /** |
||
| 339 | * Execute a SELECT query based on the values in the internal arrays |
||
| 340 | * @param string $method Function the query should be attributed to. |
||
| 341 | * You should usually use __METHOD__ here |
||
| 342 | * @param array $extraQuery Query data to add but not store in the object |
||
| 343 | * Format is [ |
||
| 344 | * 'tables' => ..., |
||
| 345 | * 'fields' => ..., |
||
| 346 | * 'where' => ..., |
||
| 347 | * 'options' => ..., |
||
| 348 | * 'join_conds' => ... |
||
| 349 | * ] |
||
| 350 | * @param array|null &$hookData If set, the ApiQueryBaseBeforeQuery and |
||
| 351 | * ApiQueryBaseAfterQuery hooks will be called, and the |
||
| 352 | * ApiQueryBaseProcessRow hook will be expected. |
||
| 353 | * @return ResultWrapper |
||
| 354 | */ |
||
| 355 | protected function select( $method, $extraQuery = [], array &$hookData = null ) { |
||
| 392 | |||
| 393 | /** |
||
| 394 | * Call the ApiQueryBaseProcessRow hook |
||
| 395 | * |
||
| 396 | * Generally, a module that passed $hookData to self::select() will call |
||
| 397 | * this just before calling ApiResult::addValue(), and treat a false return |
||
| 398 | * here in the same way it treats a false return from addValue(). |
||
| 399 | * |
||
| 400 | * @since 1.28 |
||
| 401 | * @param object $row Database row |
||
| 402 | * @param array &$data Data to be added to the result |
||
| 403 | * @param array &$hookData Hook data from ApiQueryBase::select() |
||
| 404 | * @return bool Return false if row processing should end with continuation |
||
| 405 | */ |
||
| 406 | protected function processRow( $row, array &$data, array &$hookData ) { |
||
| 409 | |||
| 410 | /** |
||
| 411 | * @param string $query |
||
| 412 | * @param string $protocol |
||
| 413 | * @return null|string |
||
| 414 | */ |
||
| 415 | public function prepareUrlQuerySearchString( $query = null, $protocol = null ) { |
||
| 436 | |||
| 437 | /** |
||
| 438 | * Filters hidden users (where the user doesn't have the right to view them) |
||
| 439 | * Also adds relevant block information |
||
| 440 | * |
||
| 441 | * @param bool $showBlockInfo |
||
| 442 | * @return void |
||
| 443 | */ |
||
| 444 | public function showHiddenUsersAddBlockInfo( $showBlockInfo ) { |
||
| 468 | |||
| 469 | /**@}*/ |
||
| 470 | |||
| 471 | /************************************************************************//** |
||
| 472 | * @name Utility methods |
||
| 473 | * @{ |
||
| 474 | */ |
||
| 475 | |||
| 476 | /** |
||
| 477 | * Add information (title and namespace) about a Title object to a |
||
| 478 | * result array |
||
| 479 | * @param array $arr Result array à la ApiResult |
||
| 480 | * @param Title $title |
||
| 481 | * @param string $prefix Module prefix |
||
| 482 | */ |
||
| 483 | public static function addTitleInfo( &$arr, $title, $prefix = '' ) { |
||
| 487 | |||
| 488 | /** |
||
| 489 | * Add a sub-element under the page element with the given page ID |
||
| 490 | * @param int $pageId Page ID |
||
| 491 | * @param array $data Data array à la ApiResult |
||
| 492 | * @return bool Whether the element fit in the result |
||
| 493 | */ |
||
| 494 | protected function addPageSubItems( $pageId, $data ) { |
||
| 502 | |||
| 503 | /** |
||
| 504 | * Same as addPageSubItems(), but one element of $data at a time |
||
| 505 | * @param int $pageId Page ID |
||
| 506 | * @param array $item Data array à la ApiResult |
||
| 507 | * @param string $elemname XML element name. If null, getModuleName() |
||
| 508 | * is used |
||
| 509 | * @return bool Whether the element fit in the result |
||
| 510 | */ |
||
| 511 | protected function addPageSubItem( $pageId, $item, $elemname = null ) { |
||
| 526 | |||
| 527 | /** |
||
| 528 | * Set a query-continue value |
||
| 529 | * @param string $paramName Parameter name |
||
| 530 | * @param string|array $paramValue Parameter value |
||
| 531 | */ |
||
| 532 | protected function setContinueEnumParameter( $paramName, $paramValue ) { |
||
| 535 | |||
| 536 | /** |
||
| 537 | * Convert an input title or title prefix into a dbkey. |
||
| 538 | * |
||
| 539 | * $namespace should always be specified in order to handle per-namespace |
||
| 540 | * capitalization settings. |
||
| 541 | * |
||
| 542 | * @param string $titlePart Title part |
||
| 543 | * @param int $namespace Namespace of the title |
||
| 544 | * @return string DBkey (no namespace prefix) |
||
| 545 | */ |
||
| 546 | View Code Duplication | public function titlePartToKey( $titlePart, $namespace = NS_MAIN ) { |
|
| 563 | |||
| 564 | /** |
||
| 565 | * Convert an input title or title prefix into a namespace constant and dbkey. |
||
| 566 | * |
||
| 567 | * @since 1.26 |
||
| 568 | * @param string $titlePart Title part |
||
| 569 | * @param int $defaultNamespace Default namespace if none is given |
||
| 570 | * @return array (int, string) Namespace number and DBkey |
||
| 571 | */ |
||
| 572 | View Code Duplication | public function prefixedTitlePartToKey( $titlePart, $defaultNamespace = NS_MAIN ) { |
|
| 581 | |||
| 582 | /** |
||
| 583 | * @param string $hash |
||
| 584 | * @return bool |
||
| 585 | */ |
||
| 586 | public function validateSha1Hash( $hash ) { |
||
| 589 | |||
| 590 | /** |
||
| 591 | * @param string $hash |
||
| 592 | * @return bool |
||
| 593 | */ |
||
| 594 | public function validateSha1Base36Hash( $hash ) { |
||
| 597 | |||
| 598 | /** |
||
| 599 | * Check whether the current user has permission to view revision-deleted |
||
| 600 | * fields. |
||
| 601 | * @return bool |
||
| 602 | */ |
||
| 603 | public function userCanSeeRevDel() { |
||
| 611 | |||
| 612 | /**@}*/ |
||
| 613 | } |
||
| 614 |
Loading history...
Only declaring a single property per statement allows you to later on add doc comments more easily.
It is also recommended by PSR2, so it is a common style that many people expect.