diff options
Diffstat (limited to 'includes/api/ApiResult.php')
| -rw-r--r-- | includes/api/ApiResult.php | 314 |
1 files changed, 271 insertions, 43 deletions
diff --git a/includes/api/ApiResult.php b/includes/api/ApiResult.php index 39c114b8..2e80447e 100644 --- a/includes/api/ApiResult.php +++ b/includes/api/ApiResult.php @@ -26,18 +26,20 @@ /** * This class represents the result of the API operations. - * It simply wraps a nested array() structure, adding some functions to simplify array's modifications. - * As various modules execute, they add different pieces of information to this result, - * structuring it as it will be given to the client. + * It simply wraps a nested array() structure, adding some functions to simplify + * array's modifications. As various modules execute, they add different pieces + * of information to this result, structuring it as it will be given to the client. * * Each subarray may either be a dictionary - key-value pairs with unique keys, * or lists, where the items are added using $data[] = $value notation. * - * There are two special key values that change how XML output is generated: - * '_element' This key sets the tag name for the rest of the elements in the current array. - * It is only inserted if the formatter returned true for getNeedsRawData() - * '*' This key has special meaning only to the XML formatter, and is outputted as is - * for all others. In XML it becomes the content of the current element. + * There are three special key values that change how XML output is generated: + * '_element' This key sets the tag name for the rest of the elements in the current array. + * It is only inserted if the formatter returned true for getNeedsRawData() + * '_subelements' This key causes the specified elements to be returned as subelements rather than attributes. + * It is only inserted if the formatter returned true for getNeedsRawData() + * '*' This key has special meaning only to the XML formatter, and is outputted as is + * for all others. In XML it becomes the content of the current element. * * @ingroup API */ @@ -56,13 +58,27 @@ class ApiResult extends ApiBase { */ const ADD_ON_TOP = 2; + /** + * For addValue() and setElement(), do not check size while adding a value + * Don't use this unless you REALLY know what you're doing. + * Values added while the size checking was disabled will never be counted + * @since 1.24 + */ + const NO_SIZE_CHECK = 4; + private $mData, $mIsRawMode, $mSize, $mCheckingSize; + private $continueAllModules = array(); + private $continueGeneratedModules = array(); + private $continuationData = array(); + private $generatorContinuationData = array(); + private $generatorParams = array(); + private $generatorDone = false; + /** - * Constructor - * @param $main ApiMain object + * @param ApiMain $main */ - public function __construct( $main ) { + public function __construct( ApiMain $main ) { parent::__construct( $main, 'result' ); $this->mIsRawMode = false; $this->mCheckingSize = true; @@ -80,9 +96,11 @@ class ApiResult extends ApiBase { /** * Call this function when special elements such as '_element' * are needed by the formatter, for example in XML printing. + * @since 1.23 $flag parameter added + * @param bool $flag Set the raw mode flag to this state */ - public function setRawMode() { - $this->mIsRawMode = true; + public function setRawMode( $flag = true ) { + $this->mIsRawMode = $flag; } /** @@ -104,7 +122,7 @@ class ApiResult extends ApiBase { /** * Get the 'real' size of a result item. This means the strlen() of the item, * or the sum of the strlen()s of the elements if the item is an array. - * @param $value mixed + * @param mixed $value * @return int */ public static function size( $value ) { @@ -117,6 +135,7 @@ class ApiResult extends ApiBase { // Objects can't always be cast to string $s = strlen( $value ); } + return $s; } @@ -132,6 +151,7 @@ class ApiResult extends ApiBase { * Disable size checking in addValue(). Don't use this unless you * REALLY know what you're doing. Values added while size checking * was disabled will not be counted (ever) + * @deprecated since 1.24, use ApiResult::NO_SIZE_CHECK */ public function disableSizeCheck() { $this->mCheckingSize = false; @@ -139,6 +159,7 @@ class ApiResult extends ApiBase { /** * Re-enable size checking in addValue() + * @deprecated since 1.24, use ApiResult::NO_SIZE_CHECK */ public function enableSizeCheck() { $this->mCheckingSize = true; @@ -147,17 +168,20 @@ class ApiResult extends ApiBase { /** * Add an output value to the array by name. * Verifies that value with the same name has not been added before. - * @param array $arr to add $value to + * @param array $arr To add $value to * @param string $name Index of $arr to add $value at - * @param $value mixed - * @param int $flags Zero or more OR-ed flags like OVERRIDE | ADD_ON_TOP. This parameter used to be - * boolean, and the value of OVERRIDE=1 was specifically chosen so that it would be backwards - * compatible with the new method signature. + * @param mixed $value + * @param int $flags Zero or more OR-ed flags like OVERRIDE | ADD_ON_TOP. + * This parameter used to be boolean, and the value of OVERRIDE=1 was + * specifically chosen so that it would be backwards compatible with the + * new method signature. * * @since 1.21 int $flags replaced boolean $override */ public static function setElement( &$arr, $name, $value, $flags = 0 ) { - if ( $arr === null || $name === null || $value === null || !is_array( $arr ) || is_array( $name ) ) { + if ( $arr === null || $name === null || $value === null + || !is_array( $arr ) || is_array( $name ) + ) { ApiBase::dieDebug( __METHOD__, 'Bad parameter' ); } @@ -176,16 +200,19 @@ class ApiResult extends ApiBase { ApiBase::dieDebug( __METHOD__, "Attempting to merge element $name" ); } } else { - ApiBase::dieDebug( __METHOD__, "Attempting to add element $name=$value, existing value is {$arr[$name]}" ); + ApiBase::dieDebug( + __METHOD__, + "Attempting to add element $name=$value, existing value is {$arr[$name]}" + ); } } /** * Adds a content element to an array. * Use this function instead of hardcoding the '*' element. - * @param array $arr to add the content element to - * @param $value Mixed - * @param string $subElemName when present, content element is created + * @param array $arr To add the content element to + * @param mixed $value + * @param string $subElemName When present, content element is created * as a sub item of $arr. Use this parameter to create elements in * format "<elem>text</elem>" without attributes. */ @@ -204,10 +231,34 @@ class ApiResult extends ApiBase { } /** + * Causes the elements with the specified names to be output as + * subelements rather than attributes. + * @param array $arr + * @param array|string $names The element name(s) to be output as subelements + */ + public function setSubelements( &$arr, $names ) { + // In raw mode, add the '_subelements', otherwise just ignore + if ( !$this->getIsRawMode() ) { + return; + } + if ( $arr === null || $names === null || !is_array( $arr ) ) { + ApiBase::dieDebug( __METHOD__, 'Bad parameter' ); + } + if ( !is_array( $names ) ) { + $names = array( $names ); + } + if ( !isset( $arr['_subelements'] ) ) { + $arr['_subelements'] = $names; + } else { + $arr['_subelements'] = array_merge( $arr['_subelements'], $names ); + } + } + + /** * In case the array contains indexed values (in addition to named), * give all indexed values the given tag name. This function MUST be * called on every array that has numerical indexes. - * @param $arr array + * @param array $arr * @param string $tag Tag name */ public function setIndexedTagName( &$arr, $tag ) { @@ -224,7 +275,7 @@ class ApiResult extends ApiBase { /** * Calls setIndexedTagName() on each sub-array of $arr - * @param $arr array + * @param array $arr * @param string $tag Tag name */ public function setIndexedTagName_recursive( &$arr, $tag ) { @@ -245,7 +296,7 @@ class ApiResult extends ApiBase { * Don't specify a path to a value that's not in the result, or * you'll get nasty errors. * @param array $path Path to the array, like addValue()'s $path - * @param $tag string + * @param string $tag */ public function setIndexedTagName_internal( $path, $tag ) { $data = &$this->mData; @@ -268,26 +319,26 @@ class ApiResult extends ApiBase { * If $path is null, the value will be inserted at the data root. * If $name is empty, the $value is added as a next list element data[] = $value. * - * @param $path array|string|null - * @param $name string - * @param $value mixed - * @param int $flags Zero or more OR-ed flags like OVERRIDE | ADD_ON_TOP. This parameter used to be - * boolean, and the value of OVERRIDE=1 was specifically chosen so that it would be backwards - * compatible with the new method signature. + * @param array|string|null $path + * @param string $name + * @param mixed $value + * @param int $flags Zero or more OR-ed flags like OVERRIDE | ADD_ON_TOP. + * This parameter used to be boolean, and the value of OVERRIDE=1 was specifically + * chosen so that it would be backwards compatible with the new method signature. * @return bool True if $value fits in the result, false if not * * @since 1.21 int $flags replaced boolean $override */ public function addValue( $path, $name, $value, $flags = 0 ) { - global $wgAPIMaxResultSize; - $data = &$this->mData; - if ( $this->mCheckingSize ) { + if ( $this->mCheckingSize && !( $flags & ApiResult::NO_SIZE_CHECK ) ) { $newsize = $this->mSize + self::size( $value ); - if ( $newsize > $wgAPIMaxResultSize ) { + $maxResultSize = $this->getConfig()->get( 'APIMaxResultSize' ); + if ( $newsize > $maxResultSize ) { $this->setWarning( "This result was truncated because it would otherwise be larger than the " . - "limit of {$wgAPIMaxResultSize} bytes" ); + "limit of {$maxResultSize} bytes" ); + return false; } $this->mSize = $newsize; @@ -322,14 +373,15 @@ class ApiResult extends ApiBase { // Add named element self::setElement( $data, $name, $value, $flags ); } + return true; } /** * Add a parsed limit=max to the result. * - * @param $moduleName string - * @param $limit int + * @param string $moduleName + * @param int $limit */ public function setParsedLimit( $moduleName, $limit ) { // Add value, allowing overwriting @@ -340,8 +392,8 @@ class ApiResult extends ApiBase { * Unset a value previously added to the result set. * Fails silently if the value isn't found. * For parameters, see addValue() - * @param $path array|null - * @param $name string + * @param array|null $path + * @param string $name */ public function unsetValue( $path, $name ) { $data = &$this->mData; @@ -367,7 +419,7 @@ class ApiResult extends ApiBase { /** * Callback function for cleanUpUTF8() * - * @param $s string + * @param string $s */ private static function cleanUp_helper( &$s ) { if ( !is_string( $s ) ) { @@ -394,10 +446,186 @@ class ApiResult extends ApiBase { $result[] = $error; } $this->setIndexedTagName( $result, $errorType ); + return $result; } public function execute() { ApiBase::dieDebug( __METHOD__, 'execute() is not supported on Result object' ); } + + /** + * Parse a 'continue' parameter and return status information. + * + * This must be balanced by a call to endContinuation(). + * + * @since 1.24 + * @param string|null $continue The "continue" parameter, if any + * @param ApiBase[] $allModules Contains ApiBase instances that will be executed + * @param array $generatedModules Names of modules that depend on the generator + * @return array Two elements: a boolean indicating if the generator is done, + * and an array of modules to actually execute. + */ + public function beginContinuation( + $continue, array $allModules = array(), array $generatedModules = array() + ) { + $this->continueGeneratedModules = $generatedModules + ? array_combine( $generatedModules, $generatedModules ) + : array(); + $this->continuationData = array(); + $this->generatorContinuationData = array(); + $this->generatorParams = array(); + + $skip = array(); + if ( is_string( $continue ) && $continue !== '' ) { + $continue = explode( '||', $continue ); + $this->dieContinueUsageIf( count( $continue ) !== 2 ); + $this->generatorDone = ( $continue[0] === '-' ); + if ( !$this->generatorDone ) { + $this->generatorParams = explode( '|', $continue[0] ); + } + $skip = explode( '|', $continue[1] ); + } + + $this->continueAllModules = array(); + $runModules = array(); + foreach ( $allModules as $module ) { + $name = $module->getModuleName(); + if ( in_array( $name, $skip ) ) { + $this->continueAllModules[$name] = false; + // Prevent spurious "unused parameter" warnings + $module->extractRequestParams(); + } else { + $this->continueAllModules[$name] = true; + $runModules[] = $module; + } + } + + return array( + $this->generatorDone, + $runModules, + ); + } + + /** + * Set the continuation parameter for a module + * + * @since 1.24 + * @param ApiBase $module + * @param string $paramName + * @param string|array $paramValue + */ + public function setContinueParam( ApiBase $module, $paramName, $paramValue ) { + $name = $module->getModuleName(); + if ( !isset( $this->continueAllModules[$name] ) ) { + throw new MWException( + "Module '$name' called ApiResult::setContinueParam but was not " . + 'passed to ApiResult::beginContinuation' + ); + } + if ( !$this->continueAllModules[$name] ) { + throw new MWException( + "Module '$name' was not supposed to have been executed, but " . + 'it was executed anyway' + ); + } + $paramName = $module->encodeParamName( $paramName ); + if ( is_array( $paramValue ) ) { + $paramValue = join( '|', $paramValue ); + } + $this->continuationData[$name][$paramName] = $paramValue; + } + + /** + * Set the continuation parameter for the generator module + * + * @since 1.24 + * @param ApiBase $module + * @param string $paramName + * @param string|array $paramValue + */ + public function setGeneratorContinueParam( ApiBase $module, $paramName, $paramValue ) { + $name = $module->getModuleName(); + $paramName = $module->encodeParamName( $paramName ); + if ( is_array( $paramValue ) ) { + $paramValue = join( '|', $paramValue ); + } + $this->generatorContinuationData[$name][$paramName] = $paramValue; + } + + /** + * Close continuation, writing the data into the result + * + * @since 1.24 + * @param string $style 'standard' for the new style since 1.21, 'raw' for + * the style used in 1.20 and earlier. + */ + public function endContinuation( $style = 'standard' ) { + if ( $style === 'raw' ) { + $key = 'query-continue'; + $data = array_merge_recursive( + $this->continuationData, $this->generatorContinuationData + ); + } else { + $key = 'continue'; + $data = array(); + + $finishedModules = array_diff( + array_keys( $this->continueAllModules ), + array_keys( $this->continuationData ) + ); + + // First, grab the non-generator-using continuation data + $continuationData = array_diff_key( + $this->continuationData, $this->continueGeneratedModules + ); + foreach ( $continuationData as $module => $kvp ) { + $data += $kvp; + } + + // Next, handle the generator-using continuation data + $continuationData = array_intersect_key( + $this->continuationData, $this->continueGeneratedModules + ); + if ( $continuationData ) { + // Some modules are unfinished: include those params, and copy + // the generator params. + foreach ( $continuationData as $module => $kvp ) { + $data += $kvp; + } + $data += array_intersect_key( + $this->getMain()->getRequest()->getValues(), + array_flip( $this->generatorParams ) + ); + } elseif ( $this->generatorContinuationData ) { + // All the generator-using modules are complete, but the + // generator isn't. Continue the generator and restart the + // generator-using modules + $this->generatorParams = array(); + foreach ( $this->generatorContinuationData as $kvp ) { + $this->generatorParams = array_merge( + $this->generatorParams, array_keys( $kvp ) + ); + $data += $kvp; + } + $finishedModules = array_diff( + $finishedModules, $this->continueGeneratedModules + ); + } else { + // Generator and prop modules are all done. Mark it so. + $this->generatorDone = true; + } + + // Set 'continue' if any continuation data is set or if the generator + // still needs to run + if ( $data || !$this->generatorDone ) { + $data['continue'] = + ( $this->generatorDone ? '-' : join( '|', $this->generatorParams ) ) . + '||' . join( '|', $finishedModules ); + } + } + if ( $data ) { + $this->addValue( null, $key, $data, ApiResult::ADD_ON_TOP | ApiResult::NO_SIZE_CHECK ); + } + } } |