summaryrefslogtreecommitdiff
path: root/includes/api/ApiQueryBase.php
diff options
context:
space:
mode:
Diffstat (limited to 'includes/api/ApiQueryBase.php')
-rw-r--r--includes/api/ApiQueryBase.php138
1 files changed, 77 insertions, 61 deletions
diff --git a/includes/api/ApiQueryBase.php b/includes/api/ApiQueryBase.php
index 2c48aca0..7819ead4 100644
--- a/includes/api/ApiQueryBase.php
+++ b/includes/api/ApiQueryBase.php
@@ -112,7 +112,7 @@ abstract class ApiQueryBase extends ApiBase {
/**
* Add a set of fields to select to the internal array
- * @param $value array|string Field name or array of field names
+ * @param array|string $value Field name or array of field names
*/
protected function addFields( $value ) {
if ( is_array( $value ) ) {
@@ -124,8 +124,8 @@ abstract class ApiQueryBase extends ApiBase {
/**
* Same as addFields(), but add the fields only if a condition is met
- * @param $value array|string See addFields()
- * @param $condition bool If false, do nothing
+ * @param array|string $value See addFields()
+ * @param bool $condition If false, do nothing
* @return bool $condition
*/
protected function addFieldsIf( $value, $condition ) {
@@ -162,7 +162,7 @@ abstract class ApiQueryBase extends ApiBase {
/**
* Same as addWhere(), but add the WHERE clauses only if a condition is met
* @param $value mixed See addWhere()
- * @param $condition bool If false, do nothing
+ * @param bool $condition If false, do nothing
* @return bool $condition
*/
protected function addWhereIf( $value, $condition ) {
@@ -175,8 +175,8 @@ abstract class ApiQueryBase extends ApiBase {
/**
* Equivalent to addWhere(array($field => $value))
- * @param $field string Field name
- * @param $value string Value; ignored if null or empty array;
+ * @param string $field Field name
+ * @param string $value Value; ignored if null or empty array;
*/
protected function addWhereFld( $field, $value ) {
// Use count() to its full documented capabilities to simultaneously
@@ -189,14 +189,14 @@ abstract class ApiQueryBase extends ApiBase {
/**
* Add a WHERE clause corresponding to a range, and an ORDER BY
* clause to sort in the right direction
- * @param $field string Field name
- * @param $dir string If 'newer', sort in ascending order, otherwise
+ * @param string $field Field name
+ * @param string $dir If 'newer', sort in ascending order, otherwise
* sort in descending order
- * @param $start string Value to start the list at. If $dir == 'newer'
+ * @param string $start Value to start the list at. If $dir == 'newer'
* this is the lower boundary, otherwise it's the upper boundary
- * @param $end string Value to end the list at. If $dir == 'newer' this
+ * @param string $end Value to end the list at. If $dir == 'newer' this
* is the upper boundary, otherwise it's the lower boundary
- * @param $sort bool If false, don't add an ORDER BY clause
+ * @param bool $sort If false, don't add an ORDER BY clause
*/
protected function addWhereRange( $field, $dir, $start, $end, $sort = true ) {
$isDirNewer = ( $dir === 'newer' );
@@ -240,8 +240,8 @@ abstract class ApiQueryBase extends ApiBase {
/**
* Add an option such as LIMIT or USE INDEX. If an option was set
* before, the old value will be overwritten
- * @param $name string Option name
- * @param $value string Option value
+ * @param string $name Option name
+ * @param string $value Option value
*/
protected function addOption( $name, $value = null ) {
if ( is_null( $value ) ) {
@@ -253,9 +253,9 @@ abstract class ApiQueryBase extends ApiBase {
/**
* Execute a SELECT query based on the values in the internal arrays
- * @param $method string Function the query should be attributed to.
+ * @param string $method Function the query should be attributed to.
* You should usually use __METHOD__ here
- * @param $extraQuery array Query data to add but not store in the object
+ * @param array $extraQuery Query data to add but not store in the object
* Format is array( 'tables' => ..., 'fields' => ..., 'where' => ..., 'options' => ..., 'join_conds' => ... )
* @return ResultWrapper
*/
@@ -298,9 +298,9 @@ abstract class ApiQueryBase extends ApiBase {
/**
* Add information (title and namespace) about a Title object to a
* result array
- * @param $arr array Result array à la ApiResult
+ * @param array $arr Result array à la ApiResult
* @param $title Title
- * @param $prefix string Module prefix
+ * @param string $prefix Module prefix
*/
public static function addTitleInfo( &$arr, $title, $prefix = '' ) {
$arr[$prefix . 'ns'] = intval( $title->getNamespace() );
@@ -325,8 +325,8 @@ abstract class ApiQueryBase extends ApiBase {
/**
* Add a sub-element under the page element with the given page ID
- * @param $pageId int Page ID
- * @param $data array Data array à la ApiResult
+ * @param int $pageId Page ID
+ * @param array $data Data array à la ApiResult
* @return bool Whether the element fit in the result
*/
protected function addPageSubItems( $pageId, $data ) {
@@ -339,9 +339,9 @@ abstract class ApiQueryBase extends ApiBase {
/**
* Same as addPageSubItems(), but one element of $data at a time
- * @param $pageId int Page ID
- * @param $item array Data array à la ApiResult
- * @param $elemname string XML element name. If null, getModuleName()
+ * @param int $pageId Page ID
+ * @param array $item Data array à la ApiResult
+ * @param string $elemname XML element name. If null, getModuleName()
* is used
* @return bool Whether the element fit in the result
*/
@@ -351,7 +351,7 @@ abstract class ApiQueryBase extends ApiBase {
}
$result = $this->getResult();
$fit = $result->addValue( array( 'query', 'pages', $pageId,
- $this->getModuleName() ), null, $item );
+ $this->getModuleName() ), null, $item );
if ( !$fit ) {
return false;
}
@@ -362,15 +362,15 @@ abstract class ApiQueryBase extends ApiBase {
/**
* Set a query-continue value
- * @param $paramName string Parameter name
- * @param $paramValue string Parameter value
+ * @param string $paramName Parameter name
+ * @param string $paramValue Parameter value
*/
protected function setContinueEnumParameter( $paramName, $paramValue ) {
$paramName = $this->encodeParamName( $paramName );
$msg = array( $paramName => $paramValue );
$result = $this->getResult();
$result->disableSizeCheck();
- $result->addValue( 'query-continue', $this->getModuleName(), $msg );
+ $result->addValue( 'query-continue', $this->getModuleName(), $msg, ApiResult::ADD_ON_TOP );
$result->enableSizeCheck();
}
@@ -380,8 +380,7 @@ abstract class ApiQueryBase extends ApiBase {
*/
protected function getDB() {
if ( is_null( $this->mDb ) ) {
- $apiQuery = $this->getQuery();
- $this->mDb = $apiQuery->getDB();
+ $this->mDb = $this->getQuery()->getDB();
}
return $this->mDb;
}
@@ -389,9 +388,9 @@ abstract class ApiQueryBase extends ApiBase {
/**
* Selects the query database connection with the given name.
* See ApiQuery::getNamedDB() for more information
- * @param $name string Name to assign to the database connection
- * @param $db int One of the DB_* constants
- * @param $groups array Query groups
+ * @param string $name Name to assign to the database connection
+ * @param int $db One of the DB_* constants
+ * @param array $groups Query groups
* @return DatabaseBase
*/
public function selectNamedDB( $name, $db, $groups ) {
@@ -408,7 +407,7 @@ abstract class ApiQueryBase extends ApiBase {
/**
* Convert a title to a DB key
- * @param $title string Page title with spaces
+ * @param string $title Page title with spaces
* @return string Page title with underscores
*/
public function titleToKey( $title ) {
@@ -420,12 +419,12 @@ abstract class ApiQueryBase extends ApiBase {
if ( !$t ) {
$this->dieUsageMsg( array( 'invalidtitle', $title ) );
}
- return $t->getPrefixedDbKey();
+ return $t->getPrefixedDBkey();
}
/**
* The inverse of titleToKey()
- * @param $key string Page title with underscores
+ * @param string $key Page title with underscores
* @return string Page title with spaces
*/
public function keyToTitle( $key ) {
@@ -443,7 +442,7 @@ abstract class ApiQueryBase extends ApiBase {
/**
* An alternative to titleToKey() that doesn't trim trailing spaces
- * @param $titlePart string Title part with spaces
+ * @param string $titlePart Title part with spaces
* @return string Title part with underscores
*/
public function titlePartToKey( $titlePart ) {
@@ -452,7 +451,7 @@ abstract class ApiQueryBase extends ApiBase {
/**
* An alternative to keyToTitle() that doesn't trim trailing spaces
- * @param $keyPart string Key part with spaces
+ * @param string $keyPart Key part with spaces
* @return string Key part with underscores
*/
public function keyPartToTitle( $keyPart ) {
@@ -534,7 +533,7 @@ abstract class ApiQueryBase extends ApiBase {
* @return bool
*/
public function validateSha1Hash( $hash ) {
- return preg_match( '/[a-fA-F0-9]{40}/', $hash );
+ return preg_match( '/^[a-f0-9]{40}$/', $hash );
}
/**
@@ -542,25 +541,19 @@ abstract class ApiQueryBase extends ApiBase {
* @return bool
*/
public function validateSha1Base36Hash( $hash ) {
- return preg_match( '/[a-zA-Z0-9]{31}/', $hash );
+ return preg_match( '/^[a-z0-9]{31}$/', $hash );
}
/**
* @return array
*/
public function getPossibleErrors() {
- return array_merge( parent::getPossibleErrors(), array(
+ $errors = parent::getPossibleErrors();
+ $errors = array_merge( $errors, array(
array( 'invalidtitle', 'title' ),
array( 'invalidtitle', 'key' ),
) );
- }
-
- /**
- * Get version string for use in the API help output
- * @return string
- */
- public static function getBaseVersion() {
- return __CLASS__ . ': $Id$';
+ return $errors;
}
}
@@ -569,33 +562,41 @@ abstract class ApiQueryBase extends ApiBase {
*/
abstract class ApiQueryGeneratorBase extends ApiQueryBase {
- private $mIsGenerator;
+ private $mGeneratorPageSet = null;
/**
- * @param $query ApiBase
- * @param $moduleName string
- * @param $paramPrefix string
+ * Switch this module to generator mode. By default, generator mode is
+ * switched off and the module acts like a normal query module.
+ * @since 1.21 requires pageset parameter
+ * @param $generatorPageSet ApiPageSet object that the module will get
+ * by calling getPageSet() when in generator mode.
*/
- public function __construct( $query, $moduleName, $paramPrefix = '' ) {
- parent::__construct( $query, $moduleName, $paramPrefix );
- $this->mIsGenerator = false;
+ public function setGeneratorMode( ApiPageSet $generatorPageSet ) {
+ if ( $generatorPageSet === null ) {
+ ApiBase::dieDebug( __METHOD__, 'Required parameter missing - $generatorPageSet' );
+ }
+ $this->mGeneratorPageSet = $generatorPageSet;
}
/**
- * Switch this module to generator mode. By default, generator mode is
- * switched off and the module acts like a normal query module.
+ * Get the PageSet object to work on.
+ * If this module is generator, the pageSet object is different from other module's
+ * @return ApiPageSet
*/
- public function setGeneratorMode() {
- $this->mIsGenerator = true;
+ protected function getPageSet() {
+ if ( $this->mGeneratorPageSet !== null ) {
+ return $this->mGeneratorPageSet;
+ }
+ return parent::getPageSet();
}
/**
* Overrides base class to prepend 'g' to every generator parameter
- * @param $paramName string Parameter name
+ * @param string $paramName Parameter name
* @return string Prefixed parameter name
*/
public function encodeParamName( $paramName ) {
- if ( $this->mIsGenerator ) {
+ if ( $this->mGeneratorPageSet !== null ) {
return 'g' . parent::encodeParamName( $paramName );
} else {
return parent::encodeParamName( $paramName );
@@ -603,9 +604,24 @@ abstract class ApiQueryGeneratorBase extends ApiQueryBase {
}
/**
+ * Overrides base in case of generator & smart continue to
+ * notify ApiQueryMain instead of adding them to the result right away.
+ * @param string $paramName Parameter name
+ * @param string $paramValue Parameter value
+ */
+ protected function setContinueEnumParameter( $paramName, $paramValue ) {
+ // If this is a generator and query->setGeneratorContinue() returns false, treat as before
+ if ( $this->mGeneratorPageSet === null
+ || !$this->getQuery()->setGeneratorContinue( $this, $paramName, $paramValue )
+ ) {
+ parent::setContinueEnumParameter( $paramName, $paramValue );
+ }
+ }
+
+ /**
* Execute this module as a generator
* @param $resultPageSet ApiPageSet: All output should be appended to
* this object
*/
- public abstract function executeGenerator( $resultPageSet );
+ abstract public function executeGenerator( $resultPageSet );
}