BlueSpice MediaWiki REL1_27
 All Classes Namespaces Files Functions Variables Groups Pages
ApiResult Class Reference
Inheritance diagram for ApiResult:
Collaboration diagram for ApiResult:

Public Member Functions

 __construct ($maxSize)
 
 setErrorFormatter (ApiErrorFormatter $formatter)
 
 serializeForApiResult ()
 

Public Attributes

const OVERRIDE = 1
 
const ADD_ON_TOP = 2
 
const NO_SIZE_CHECK = 4
 
const NO_VALIDATE = 12
 
const META_INDEXED_TAG_NAME = '_element'
 
const META_SUBELEMENTS = '_subelements'
 
const META_PRESERVE_KEYS = '_preservekeys'
 
const META_CONTENT = '_content'
 
const META_TYPE = '_type'
 
const META_KVP_KEY_NAME = '_kvpkeyname'
 
const META_KVP_MERGE = '_kvpmerge'
 
const META_BC_BOOLS = '_BC_bools'
 
const META_BC_SUBELEMENTS = '_BC_subelements'
 
 $size
 
 $maxSize
 
 $mainForContinuation
 

Content

 reset ()
 
 getResultData ($path=[], $transforms=[])
 
 getSize ()
 
 addValue ($path, $name, $value, $flags=0)
 
 removeValue ($path, $name, $flags=0)
 
 addContentValue ($path, $name, $value, $flags=0)
 
 addParsedLimit ($moduleName, $limit)
 
static setValue (array &$arr, $name, $value, $flags=0)
 
static unsetValue (array &$arr, $name)
 
static setContentValue (array &$arr, $name, $value, $flags=0)
 

Metadata

 addContentField ($path, $name, $flags=0)
 
 addSubelementsList ($path, $names)
 
 removeSubelementsList ($path, $names)
 
 addIndexedTagName ($path, $tag)
 
 addIndexedTagNameRecursive ($path, $tag)
 
 addPreserveKeysList ($path, $names)
 
 removePreserveKeysList ($path, $names)
 
 addArrayType ($path, $tag, $kvpKeyName=null)
 
 addArrayTypeRecursive ($path, $tag, $kvpKeyName=null)
 
static setContentField (array &$arr, $name, $flags=0)
 
static setSubelementsList (array &$arr, $names)
 
static unsetSubelementsList (array &$arr, $names)
 
static setIndexedTagName (array &$arr, $tag)
 
static setIndexedTagNameRecursive (array &$arr, $tag)
 
static setPreserveKeysList (array &$arr, $names)
 
static unsetPreserveKeysList (array &$arr, $names)
 
static setArrayType (array &$arr, $type, $kvpKeyName=null)
 
static setArrayTypeRecursive (array &$arr, $type, $kvpKeyName=null)
 

Utility

static isMetadataKey ($key)
 
static stripMetadata ($data)
 
static stripMetadataNonRecursive ($data, &$metadata=null)
 
static addMetadataToResultVars ($vars, $forceHash=true)
 
static applyTransformations (array $dataIn, array $transforms)
 

Deprecated

 setRawMode ($flag=true)
 
 getIsRawMode ()
 
 getData ()
 
 disableSizeCheck ()
 
 enableSizeCheck ()
 
 setIndexedTagName_recursive (&$arr, $tag)
 
 setIndexedTagName_internal ($path, $tag)
 
 setParsedLimit ($moduleName, $limit)
 
 setMainForContinuation (ApiMain $main)
 
 beginContinuation ($continue, array $allModules=[], array $generatedModules=[])
 
 setContinueParam (ApiBase $module, $paramName, $paramValue)
 
 setGeneratorContinueParam (ApiBase $module, $paramName, $paramValue)
 
 endContinuation ($style= 'standard')
 
 cleanUpUTF8 ()
 
 convertStatusToArray ($status, $errorType= 'error')
 
static setElement (&$arr, $name, $value, $flags=0)
 
static setContent (&$arr, $value, $subElemName=null)
 
static size ($value)
 

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.

Since
1.25 this is no longer a subclass of ApiBase

Constructor & Destructor Documentation

ApiResult::__construct (   $maxSize)
Parameters
int | bool$maxSizeMaximum result "size", or false for no limit
Since
1.25 Takes an integer|bool rather than an ApiMain

Member Function Documentation

ApiResult::addArrayType (   $path,
  $tag,
  $kvpKeyName = null 
)

Set the array data type for a path

Since
1.25
Parameters
array | string | null$pathSee ApiResult::addValue()
string$tagSee ApiResult::META_TYPE
string$kvpKeyNameSee ApiResult::META_KVP_KEY_NAME
ApiResult::addArrayTypeRecursive (   $path,
  $tag,
  $kvpKeyName = null 
)

Set the array data type for a path recursively

Since
1.25
Parameters
array | string | null$pathSee ApiResult::addValue()
string$tagSee ApiResult::META_TYPE
string$kvpKeyNameSee ApiResult::META_KVP_KEY_NAME
ApiResult::addContentField (   $path,
  $name,
  $flags = 0 
)

Set the name of the content field name (META_CONTENT)

Since
1.25
Parameters
array | string | null$pathSee ApiResult::addValue()
string | int$nameName of the field
int$flagsZero or more OR-ed flags like OVERRIDE | ADD_ON_TOP.
ApiResult::addContentValue (   $path,
  $name,
  $value,
  $flags = 0 
)

Add value to the output data at the given path and mark as META_CONTENT

Since
1.25
Parameters
array | string | null$pathSee ApiResult::addValue()
string | int$nameSee ApiResult::setValue()
mixed$value
int$flagsZero or more OR-ed flags like OVERRIDE | ADD_ON_TOP.
Returns
bool True if $value fits in the result, false if not
ApiResult::addIndexedTagName (   $path,
  $tag 
)

Set the tag name for numeric-keyed values in XML format

Since
1.25
Parameters
array | string | null$pathSee ApiResult::addValue()
string$tagTag name
ApiResult::addIndexedTagNameRecursive (   $path,
  $tag 
)

Set indexed tag name on $path and all subarrays

Since
1.25
Parameters
array | string | null$pathSee ApiResult::addValue()
string$tagTag name
static ApiResult::addMetadataToResultVars (   $vars,
  $forceHash = true 
)
static

Add the correct metadata to an array of vars we want to export through the API.

Parameters
array$vars
bool$forceHash
Returns
array
ApiResult::addParsedLimit (   $moduleName,
  $limit 
)

Add the numeric limit for a limit=max to the result.

Since
1.25
Parameters
string$moduleName
int$limit
ApiResult::addPreserveKeysList (   $path,
  $names 
)

Preserve specified keys.

Since
1.25
See Also
self::setPreserveKeysList()
Parameters
array | string | null$pathSee ApiResult::addValue()
array | string$namesThe element name(s) to preserve
ApiResult::addSubelementsList (   $path,
  $names 
)

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

Since
1.25
Parameters
array | string | null$pathSee ApiResult::addValue()
array | string | int$namesThe element name(s) to be output as subelements
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.

Parameters
array | string | int | null$path
string | int | null$nameSee ApiResult::setValue()
mixed$value
int$flagsZero 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
Todo:
Add i18n message when replacing calls to ->setWarning()
static ApiResult::applyTransformations ( array  $dataIn,
array  $transforms 
)
staticprotected

Apply transformations to an array, returning the transformed array.

See Also
ApiResult::getResultData()
Since
1.25
Parameters
array$dataIn
array$transforms
Returns
array|object
ApiResult::beginContinuation (   $continue,
array  $allModules = [],
array  $generatedModules = [] 
)

Parse a 'continue' parameter and return status information.

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

Since
1.24
Deprecated:
since 1.25, use ApiContinuationManager instead
Parameters
string | null$continue
ApiBase[]$allModules
array$generatedModules
Returns
array
ApiResult::cleanUpUTF8 ( )

No-op, this is now checked on insert.

Deprecated:
since 1.25
ApiResult::convertStatusToArray (   $status,
  $errorType = 'error' 
)

Converts a Status object to an array suitable for addValue

Deprecated:
since 1.25, use ApiErrorFormatter::arrayFromStatus()
Parameters
Status$status
string$errorType
Returns
array
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
ApiResult::enableSizeCheck ( )

Re-enable size checking in addValue()

Deprecated:
since 1.24, use ApiResult::NO_SIZE_CHECK
ApiResult::endContinuation (   $style = 'standard')

Close continuation, writing the data into the result

Since
1.24
Deprecated:
since 1.25, use ApiContinuationManager instead
Parameters
string$style'standard' for the new style since 1.21, 'raw' for the style used in 1.20 and earlier.
ApiResult::getData ( )

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

Deprecated:
since 1.25, use $this->getResultData() instead
Returns
array
ApiResult::getIsRawMode ( )

Returns true, the equivalent of "raw mode" is always enabled now

Deprecated:
since 1.25, you shouldn't have been using it in the first place
Returns
bool
ApiResult::getResultData (   $path = [],
  $transforms = [] 
)

Get the result data array

The returned value should be considered read-only.

Transformations include:

Custom: (callable) Applied before other transformations. Signature is function ( &$data, &$metadata ), return value is ignored. Called for each nested array.

BC: (array) This transformation does various adjustments to bring the output in line with the pre-1.25 result format. The value array is a list of flags: 'nobool', 'no*', 'nosub'.

  • Boolean-valued items are changed to '' if true or removed if false, unless listed in META_BC_BOOLS. This may be skipped by including 'nobool' in the value array.
  • The tag named by META_CONTENT is renamed to '*', and META_CONTENT is set to '*'. This may be skipped by including 'no*' in the value array.
  • Tags listed in META_BC_SUBELEMENTS will have their values changed to array( '*' => $value ). This may be skipped by including 'nosub' in the value array.
  • If META_TYPE is 'BCarray', set it to 'default'
  • If META_TYPE is 'BCassoc', set it to 'default'
  • If META_TYPE is 'BCkvp', perform the transformation (even if the Types transformation is not being applied).

Types: (assoc) Apply transformations based on META_TYPE. The values array is an associative array with the following possible keys:

  • AssocAsObject: (bool) If true, return arrays with META_TYPE 'assoc' as objects.
  • ArmorKVP: (string) If provided, transform arrays with META_TYPE 'kvp' and 'BCkvp' into arrays of two-element arrays, something like this: $output = array(); foreach ( $input as $key => $value ) { $pair = array(); $pair[$META_KVP_KEY_NAME ?: $ArmorKVP_value] = $key; ApiResult::setContentValue( $pair, 'value', $value ); $output[] = $pair; }

Strip: (string) Strips metadata keys from the result.

  • 'all': Strip all metadata, recursively
  • 'base': Strip metadata at the top-level only.
  • 'none': Do not strip metadata.
  • 'bc': Like 'all', but leave certain pre-1.25 keys.
Since
1.25
Parameters
array | string | null$pathPath to fetch, see ApiResult::addValue
array$transformsSee above
Returns
mixed Result data, or null if not found
ApiResult::getSize ( )

Get the size of the result, i.e. the amount of bytes in it

Returns
int
static ApiResult::isMetadataKey (   $key)
static

Test whether a key should be considered metadata

Parameters
string$key
Returns
bool
ApiResult::removePreserveKeysList (   $path,
  $names 
)

Don't preserve specified keys.

Since
1.25
See Also
self::setPreserveKeysList()
Parameters
array | string | null$pathSee ApiResult::addValue()
array | string$namesThe element name(s) to not preserve
ApiResult::removeSubelementsList (   $path,
  $names 
)

Causes the elements with the specified names to be output as attributes (when possible) rather than as subelements.

Since
1.25
Parameters
array | string | null$pathSee ApiResult::addValue()
array | string | int$namesThe element name(s) to not be output as subelements
ApiResult::removeValue (   $path,
  $name,
  $flags = 0 
)

Remove value from the output data at the given path.

Since
1.25
Parameters
array | string | null$pathSee ApiResult::addValue()
string | int | null$nameIndex to remove at $path. If null, $path itself is removed.
int$flagsFlags used when adding the value
Returns
mixed Old value, or null
ApiResult::reset ( )

Clear the current result data.

ApiResult::serializeForApiResult ( )

Allow for adding one ApiResult into another

Since
1.25
Returns
mixed

Implements ApiSerializable.

static ApiResult::setArrayType ( array &  $arr,
  $type,
  $kvpKeyName = null 
)
static

Set the array data type

Since
1.25
Parameters
array&$arr
string$typeSee ApiResult::META_TYPE
string$kvpKeyNameSee ApiResult::META_KVP_KEY_NAME
static ApiResult::setArrayTypeRecursive ( array &  $arr,
  $type,
  $kvpKeyName = null 
)
static

Set the array data type recursively

Since
1.25
Parameters
array&$arr
string$typeSee ApiResult::META_TYPE
string$kvpKeyNameSee ApiResult::META_KVP_KEY_NAME
static ApiResult::setContent ( $arr,
  $value,
  $subElemName = null 
)
static

Adds a content element to an array. Use this function instead of hardcoding the '*' element.

Deprecated:
since 1.25, use self::setContentValue() instead
Parameters
array$arrTo add the content element to
mixed$value
string$subElemNameWhen present, content element is created as a sub item of $arr. Use this parameter to create elements in format "<elem>text</elem>" without attributes.
static ApiResult::setContentField ( array &  $arr,
  $name,
  $flags = 0 
)
static

Set the name of the content field name (META_CONTENT)

Since
1.25
Parameters
array&$arr
string | int$nameName of the field
int$flagsZero or more OR-ed flags like OVERRIDE | ADD_ON_TOP.
static ApiResult::setContentValue ( array &  $arr,
  $name,
  $value,
  $flags = 0 
)
static

Add an output value to the array by name and mark as META_CONTENT.

Since
1.25
Parameters
array&$arrTo add $value to
string | int$nameIndex of $arr to add $value at.
mixed$value
int$flagsZero or more OR-ed flags like OVERRIDE | ADD_ON_TOP.
ApiResult::setContinueParam ( ApiBase  $module,
  $paramName,
  $paramValue 
)
Since
1.24
Deprecated:
since 1.25, use ApiContinuationManager instead
Parameters
ApiBase$module
string$paramName
string | array$paramValue
static ApiResult::setElement ( $arr,
  $name,
  $value,
  $flags = 0 
)
static

Alias for self::setValue()

Since
1.21 int $flags replaced boolean $override
Deprecated:
since 1.25, use self::setValue() instead
Parameters
array$arrTo add $value to
string$nameIndex of $arr to add $value at
mixed$value
int$flagsZero 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.
ApiResult::setErrorFormatter ( ApiErrorFormatter  $formatter)

Set the error formatter

Since
1.25
Parameters
ApiErrorFormatter$formatter
ApiResult::setGeneratorContinueParam ( ApiBase  $module,
  $paramName,
  $paramValue 
)
Since
1.24
Deprecated:
since 1.25, use ApiContinuationManager instead
Parameters
ApiBase$module
string$paramName
string | array$paramValue
static ApiResult::setIndexedTagName ( array &  $arr,
  $tag 
)
static

Set the tag name for numeric-keyed values in XML format

Since
1.25 is static
Parameters
array&$arr
string$tagTag name
ApiResult::setIndexedTagName_internal (   $path,
  $tag 
)

Alias for self::addIndexedTagName()

Deprecated:
since 1.25, use $this->addIndexedTagName() instead
Parameters
array$pathPath to the array, like addValue()'s $path
string$tag
ApiResult::setIndexedTagName_recursive ( $arr,
  $tag 
)

Set indexed tag name on all subarrays of $arr

Does not set the tag name for $arr itself.

Deprecated:
since 1.25, use self::setIndexedTagNameRecursive() instead
Parameters
array$arr
string$tagTag name
static ApiResult::setIndexedTagNameRecursive ( array &  $arr,
  $tag 
)
static

Set indexed tag name on $arr and all subarrays

Since
1.25
Parameters
array&$arr
string$tagTag name
ApiResult::setMainForContinuation ( ApiMain  $main)

Set the ApiMain for use by $this->beginContinuation()

Since
1.25
Deprecated:
for backwards compatibility only, do not use
Parameters
ApiMain$main
ApiResult::setParsedLimit (   $moduleName,
  $limit 
)

Alias for self::addParsedLimit()

Deprecated:
since 1.25, use $this->addParsedLimit() instead
Parameters
string$moduleName
int$limit
static ApiResult::setPreserveKeysList ( array &  $arr,
  $names 
)
static

Preserve specified keys.

This prevents XML name mangling and preventing keys from being removed by self::stripMetadata().

Since
1.25
Parameters
array&$arr
array | string$namesThe element name(s) to preserve
ApiResult::setRawMode (   $flag = true)

Formerly used to enable/disable "raw mode".

Deprecated:
since 1.25, you shouldn't have been using it in the first place
Since
1.23 $flag parameter added
Parameters
bool$flagSet the raw mode flag to this state
static ApiResult::setSubelementsList ( array &  $arr,
  $names 
)
static

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

Since
1.25 is static
Parameters
array&$arr
array | string | int$namesThe element name(s) to be output as subelements
static ApiResult::setValue ( array &  $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.

Since
1.25
Parameters
array&$arrTo add $value to
string | int | null$nameIndex of $arr to add $value at, or null to use the next numeric index.
mixed$value
int$flagsZero or more OR-ed flags like OVERRIDE | ADD_ON_TOP.
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.

Deprecated:
since 1.25, no external users known and there doesn't seem to be any case for such use over just checking the return value from the add/set methods.
Parameters
mixed$value
Returns
int
static ApiResult::stripMetadata (   $data)
static

Recursively remove metadata keys from a data array or object

Note this removes all potential metadata keys, not just the defined ones.

Since
1.25
Parameters
array | object$data
Returns
array|object
static ApiResult::stripMetadataNonRecursive (   $data,
$metadata = null 
)
static

Remove metadata keys from a data array or object, non-recursive

Note this removes all potential metadata keys, not just the defined ones.

Since
1.25
Parameters
array | object$data
array&$metadataStore metadata here, if provided
Returns
array|object
static ApiResult::unsetPreserveKeysList ( array &  $arr,
  $names 
)
static

Don't preserve specified keys.

Since
1.25
See Also
self::setPreserveKeysList()
Parameters
array&$arr
array | string$namesThe element name(s) to not preserve
static ApiResult::unsetSubelementsList ( array &  $arr,
  $names 
)
static

Causes the elements with the specified names to be output as attributes (when possible) rather than as subelements.

Since
1.25
Parameters
array&$arr
array | string | int$namesThe element name(s) to not be output as subelements
static ApiResult::unsetValue ( array &  $arr,
  $name 
)
static

Remove an output value to the array by name.

Parameters
array&$arrTo remove $value from
string | int$nameIndex of $arr to remove
Returns
mixed Old value, or null

Member Data Documentation

const ApiResult::ADD_ON_TOP = 2

For addValue(), setValue() and similar functions, 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
const ApiResult::META_BC_BOOLS = '_BC_bools'

Key for the 'BC bools' metadata item. Value is string[]. Note no setter is provided.

Since
1.25
const ApiResult::META_BC_SUBELEMENTS = '_BC_subelements'

Key for the 'BC subelements' metadata item. Value is string[]. Note no setter is provided.

Since
1.25
const ApiResult::META_CONTENT = '_content'

Key for the 'content' metadata item. Value is string.

Since
1.25
const ApiResult::META_INDEXED_TAG_NAME = '_element'

Key for the 'indexed tag name' metadata item. Value is string.

Since
1.25
const ApiResult::META_KVP_KEY_NAME = '_kvpkeyname'

Key for the metadata item whose value specifies the name used for the kvp key in the alternative output format with META_TYPE 'kvp' or 'BCkvp', i.e. the "name" in <container>value</container>. Value is string.

Since
1.25
const ApiResult::META_KVP_MERGE = '_kvpmerge'

Key for the metadata item that indicates that the KVP key should be added into an assoc value, i.e. {"key":{"val1":"a","val2":"b"}} transforms to {"name":"key","val1":"a","val2":"b"} rather than {"name":"key","value":{"val1":"a","val2":"b"}}. Value is boolean.

Since
1.26
const ApiResult::META_PRESERVE_KEYS = '_preservekeys'

Key for the 'preserve keys' metadata item. Value is string[].

Since
1.25
const ApiResult::META_SUBELEMENTS = '_subelements'

Key for the 'subelements' metadata item. Value is string[].

Since
1.25
const ApiResult::META_TYPE = '_type'

Key for the 'type' metadata item. Value is one of the following strings:

  • default: Like 'array' if all (non-metadata) keys are numeric with no gaps, otherwise like 'assoc'.
  • array: Keys are used for ordering, but are not output. In a format like JSON, outputs as [].
  • assoc: In a format like JSON, outputs as {}.
  • kvp: For a format like XML where object keys have a restricted character set, use an alternative output format. For example, <container>value</container> rather than <container key="value">
  • BCarray: Like 'array' normally, 'default' in backwards-compatibility mode.
  • BCassoc: Like 'assoc' normally, 'default' in backwards-compatibility mode.
  • BCkvp: Like 'kvp' normally. In backwards-compatibility mode, forces the alternative output format for all formats, for example [{"name":key,"*":value}] in JSON. META_KVP_KEY_NAME must also be set.
    Since
    1.25
const ApiResult::NO_SIZE_CHECK = 4

For addValue() and similar functions, 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. Ignored for setValue() and similar functions.

Since
1.24
const ApiResult::NO_VALIDATE = 12

For addValue(), setValue() and similar functions, do not validate data. Also disables size checking. If you think you need to use this, you're probably wrong.

Since
1.25
const ApiResult::OVERRIDE = 1

Override existing value in addValue(), setValue(), and similar functions

Since
1.21

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