This class represents the result of the API operations. More...

Inheritance diagram for ApiResult:

Collaboration diagram for ApiResult:

Public Member Functions
	__construct (ApiMain $main)
	addValue ($path, $name, $value, $flags=0)
	Add value to the output data at the given path.
	beginContinuation ($continue, array $allModules=array(), array $generatedModules=array())
	Parse a 'continue' parameter and return status information.
	cleanUpUTF8 ()
	Ensure all values in this result are valid UTF-8.
	convertStatusToArray ($status, $errorType= 'error')
	Converts a Status object to an array suitable for addValue.
	disableSizeCheck ()
	Disable size checking in addValue().
	enableSizeCheck ()
	Re-enable size checking in addValue()
	endContinuation ($style= 'standard')
	Close continuation, writing the data into the result.
	execute ()
	Evaluates the parameters, performs the requested query, and sets up the result.
	getData ()
	Get the result's internal data array (read-only)
	getIsRawMode ()
	Returns true whether the formatter requested raw data.
	getSize ()
	Get the size of the result, i.e.
	reset ()
	Clear the current result data.
	setContinueParam (ApiBase $module, $paramName, $paramValue)
	Set the continuation parameter for a module.
	setGeneratorContinueParam (ApiBase $module, $paramName, $paramValue)
	Set the continuation parameter for the generator module.
	setIndexedTagName (&$arr, $tag)
	In case the array contains indexed values (in addition to named), give all indexed values the given tag name.
	setIndexedTagName_internal ($path, $tag)
	Calls setIndexedTagName() on an array already in the result.
	setIndexedTagName_recursive (&$arr, $tag)
	Calls setIndexedTagName() on each sub-array of $arr.
	setParsedLimit ($moduleName, $limit)
	Add a parsed limit=max to the result.
	setRawMode ($flag=true)
	Call this function when special elements such as '_element' are needed by the formatter, for example in XML printing.
	setSubelements (&$arr, $names)
	Causes the elements with the specified names to be output as subelements rather than attributes.
	unsetValue ($path, $name)
	Unset a value previously added to the result set.
Static Public Member Functions
static	setContent (&$arr, $value, $subElemName=null)
	Adds a content element to an array.
static	setElement (&$arr, $name, $value, $flags=0)
	Add an output value to the array by name.
static	size ($value)
	Get the 'real' size of a result item.
Public Attributes
	$mCheckingSize
	$mIsRawMode
	$mSize
const	ADD_ON_TOP = 2
	For addValue() and setElement(), if the value does not exist, add it as the first element.
const	NO_SIZE_CHECK = 4
	For addValue() and setElement(), do not check size while adding a value Don't use this unless you REALLY know what you're doing.
const	OVERRIDE = 1
	override existing value in addValue() and setElement()
Static Private Member Functions
static	cleanUp_helper (&$s)
	Callback function for cleanUpUTF8()
Private Attributes
	$continuationData = array()
	$continueAllModules = array()
	$continueGeneratedModules = array()
	$generatorContinuationData = array()
	$generatorDone = false
	$generatorParams = array()
	$mData

Detailed Description

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.

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 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.

Definition at line 46 of file ApiResult.php.

Constructor & Destructor Documentation

ApiResult::__construct ( ApiMain $ main )

Parameters:

ApiMain $main

Definition at line 81 of file ApiResult.php.

References reset().

Member Function Documentation

ApiResult::addValue	(	$	path,
		$	name,
		$	value,
		$	flags = `0`
	)

Add value to the output data at the given path.

Path can be an indexed array, each element specifying the branch at which to add the new value. Setting $path to array('a','b','c') is equivalent to data['a']['b']['c'] = $value. 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.

Parameters:

array \| string \| null	$path
string	$name
mixed	$value
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.

Returns:: bool True if $value fits in the result, false if not

Since:: 1.21 int $flags replaced boolean $override

Definition at line 332 of file ApiResult.php.

References $flags, $name, $path, $value, ADD_ON_TOP, array(), as, ContextSource\getConfig(), NO_SIZE_CHECK, setElement(), ApiBase\setWarning(), and size().

Referenced by MWDebug\appendDebugInfoToApiResult(), endContinuation(), and setParsedLimit().

ApiResult::beginContinuation	(	$	continue,
		array $	allModules = `array()`,
		array $	generatedModules = `array()`
	)

Parse a 'continue' parameter and return status information.

This must be balanced by a call to endContinuation().

Since:: 1.24

Parameters:

string \| null	$continue	The "continue" parameter, if any
	ApiBase[]	$allModules Contains ApiBase instances that will be executed
array	$generatedModules	Names of modules that depend on the generator

Returns:: array Two elements: a boolean indicating if the generator is done, and an array of modules to actually execute.

Definition at line 469 of file ApiResult.php.

References $name, array(), as, and ApiBase\dieContinueUsageIf().

static ApiResult::cleanUp_helper ( &$ s ) [static, private]

Callback function for cleanUpUTF8()

Parameters:

string $s

Definition at line 424 of file ApiResult.php.

References $s, $wgContLang, and global.

ApiResult::cleanUpUTF8 ( )

Ensure all values in this result are valid UTF-8.

Definition at line 415 of file ApiResult.php.

References array().

ApiResult::convertStatusToArray	(	$	status,
		$	errorType = `'error'`
	)

Converts a Status object to an array suitable for addValue.

Parameters:

Status	$status
string	$errorType

Returns:: array

Definition at line 438 of file ApiResult.php.

References $error, $result, array(), as, and setIndexedTagName().

ApiResult::disableSizeCheck ( )

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

Definition at line 156 of file ApiResult.php.

ApiResult::enableSizeCheck ( )

Re-enable size checking in addValue()

Deprecated:: since 1.24, use ApiResult::NO_SIZE_CHECK

Definition at line 164 of file ApiResult.php.

ApiResult::endContinuation ( $ style = 'standard' )

Close continuation, writing the data into the result.

Since:: 1.24

Parameters:

string $style 'standard' for the new style since 1.21, 'raw' for the style used in 1.20 and earlier.

Definition at line 563 of file ApiResult.php.

References $continuationData, $key, ADD_ON_TOP, addValue(), array(), as, ApiBase\getMain(), ContextSource\getRequest(), and NO_SIZE_CHECK.

ApiResult::execute ( )

Evaluates the parameters, performs the requested query, and sets up the result.

Concrete implementations of ApiBase must override this method to provide whatever functionality their module offers. Implementations must not produce any output on their own and are not expected to handle any errors.

The execute() method will be invoked directly by ApiMain immediately before the result of the module is output. Aside from the constructor, implementations should assume that no other methods will be called externally on the module before the result is processed.

The result data should be stored in the ApiResult object available through getResult().

Reimplemented from ApiBase.

Definition at line 453 of file ApiResult.php.

References ApiBase\dieDebug().

ApiResult::getData ( )

Get the result's internal data array (read-only)

Returns:: array

Definition at line 118 of file ApiResult.php.

ApiResult::getIsRawMode ( )

Returns true whether the formatter requested raw data.

Returns:: bool

Definition at line 110 of file ApiResult.php.

Referenced by setIndexedTagName(), and setSubelements().

ApiResult::getSize ( )

Get the size of the result, i.e.

the amount of bytes in it

Returns:: int

Definition at line 146 of file ApiResult.php.

ApiResult::reset ( )

Clear the current result data.

Definition at line 91 of file ApiResult.php.

References array().

Referenced by __construct().

static ApiResult::setContent	(	&$	arr,
		$	value,
		$	subElemName = `null`
	)		`[static]`

Adds a content element to an array.

Use this function instead of hardcoding the '*' element.

Parameters:

array	$arr	To add the content element to
mixed	$value
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.

Definition at line 219 of file ApiResult.php.

References $value, array(), ApiBase\dieDebug(), and setElement().

Referenced by ApiQuerySiteinfo\appendLanguages(), ApiQuerySiteinfo\appendNamespaceAliases(), ApiQuerySiteinfo\appendNamespaces(), ApiQuerySiteinfo\appendSkins(), ApiComparePages\execute(), ApiRsd\execute(), ApiExpandTemplates\execute(), ApiQueryAllMessages\execute(), ApiQueryLangLinks\execute(), ApiQueryDeletedrevs\execute(), ApiQueryExternalLinks\execute(), ApiQueryIWLinks\execute(), ApiQueryRevisions\extractRowInfo(), ApiRsd\formatRsdApiList(), ApiQueryUserInfo\getCurrentUserInfo(), and ApiQueryAllCategories\run().

ApiResult::setContinueParam	(	ApiBase $	module,
		$	paramName,
		$	paramValue
	)

Set the continuation parameter for a module.

Since:: 1.24

Parameters:

ApiBase	$module
string	$paramName
string \| array	$paramValue

Definition at line 518 of file ApiResult.php.

References $name, ApiBase\encodeParamName(), and ApiBase\getModuleName().

static ApiResult::setElement	(	&$	arr,
		$	name,
		$	value,
		$	flags = `0`
	)		`[static]`

Add an output value to the array by name.

Verifies that value with the same name has not been added before.

Parameters:

array	$arr	To add $value to
string	$name	Index of $arr to add $value at
mixed	$value
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

Definition at line 181 of file ApiResult.php.

References $flags, $name, $value, ADD_ON_TOP, array(), ApiBase\dieDebug(), and OVERRIDE.

Referenced by addValue(), and setContent().

ApiResult::setGeneratorContinueParam	(	ApiBase $	module,
		$	paramName,
		$	paramValue
	)

Set the continuation parameter for the generator module.

Since:: 1.24

Parameters:

ApiBase	$module
string	$paramName
string \| array	$paramValue

Definition at line 547 of file ApiResult.php.

References $name, ApiBase\encodeParamName(), and ApiBase\getModuleName().

ApiResult::setIndexedTagName	(	&$	arr,
		$	tag
	)

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.

Parameters:

array	$arr
string	$tag	Tag name

Definition at line 264 of file ApiResult.php.

References ApiBase\dieDebug(), and getIsRawMode().

Referenced by MWDebug\appendDebugInfoToApiResult(), convertStatusToArray(), setIndexedTagName_internal(), and setIndexedTagName_recursive().

ApiResult::setIndexedTagName_internal	(	$	path,
		$	tag
	)

Calls setIndexedTagName() on an array already in the result.

Don't specify a path to a value that's not in the result, or you'll get nasty errors.

Parameters:

array	$path	Path to the array, like addValue()'s $path
string	$tag

Definition at line 301 of file ApiResult.php.

References $path, array(), as, and setIndexedTagName().

ApiResult::setIndexedTagName_recursive	(	&$	arr,
		$	tag
	)

Calls setIndexedTagName() on each sub-array of $arr.

Parameters:

array	$arr
string	$tag	Tag name

Definition at line 281 of file ApiResult.php.

References as, and setIndexedTagName().

ApiResult::setParsedLimit	(	$	moduleName,
		$	limit
	)

Add a parsed limit=max to the result.

Parameters:

string	$moduleName
int	$limit

Definition at line 386 of file ApiResult.php.

References $limit, addValue(), and OVERRIDE.

ApiResult::setRawMode ( $ flag = true )

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

Parameters:

bool $flag Set the raw mode flag to this state

Definition at line 102 of file ApiResult.php.

ApiResult::setSubelements	(	&$	arr,
		$	names
	)

Causes the elements with the specified names to be output as subelements rather than attributes.

Parameters:

array	$arr
array \| string	$names	The element name(s) to be output as subelements

Definition at line 239 of file ApiResult.php.

References array(), ApiBase\dieDebug(), and getIsRawMode().

static ApiResult::size ( $ value ) [static]

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.

Parameters:

mixed $value

Returns:: int

Definition at line 128 of file ApiResult.php.

References $s, $value, and as.

Referenced by addValue(), and unsetValue().

ApiResult::unsetValue	(	$	path,
		$	name
	)

Unset a value previously added to the result set.

Fails silently if the value isn't found. For parameters, see addValue()

Parameters:

array \| null	$path
string	$name

Definition at line 398 of file ApiResult.php.

References $name, $path, array(), as, and size().

Member Data Documentation

ApiResult::$continuationData = array() [private]

Definition at line 73 of file ApiResult.php.

Referenced by endContinuation().

ApiResult::$continueAllModules = array() [private]

Definition at line 71 of file ApiResult.php.

ApiResult::$continueGeneratedModules = array() [private]

Definition at line 72 of file ApiResult.php.

ApiResult::$generatorContinuationData = array() [private]

Definition at line 74 of file ApiResult.php.

ApiResult::$generatorDone = false [private]

Definition at line 76 of file ApiResult.php.

ApiResult::$generatorParams = array() [private]

Definition at line 75 of file ApiResult.php.

ApiResult::$mCheckingSize

Definition at line 69 of file ApiResult.php.

ApiResult::$mData [private]

Definition at line 69 of file ApiResult.php.

ApiResult::$mIsRawMode

Definition at line 69 of file ApiResult.php.

ApiResult::$mSize

Definition at line 69 of file ApiResult.php.

const ApiResult::ADD_ON_TOP = 2

For addValue() and setElement(), if the value does not exist, add it as the first element.

In case the new value has no name (numerical index), all indexes will be renumbered.

Since:: 1.21

Definition at line 59 of file ApiResult.php.

Referenced by addValue(), endContinuation(), and setElement().

const ApiResult::NO_SIZE_CHECK = 4

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

Definition at line 67 of file ApiResult.php.

Referenced by addValue(), endContinuation(), and ApiFormatFeedWrapper\setResult().

const ApiResult::OVERRIDE = 1

override existing value in addValue() and setElement()

Since:: 1.21

Definition at line 52 of file ApiResult.php.

Referenced by setElement(), and setParsedLimit().

The documentation for this class was generated from the following file:

includes/api/ApiResult.php

Public Member Functions

Static Public Member Functions

Public Attributes

Static Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation