ApiResult.php

Go to the documentation of this file.

<?php
class ApiResult implements ApiSerializable {
 
    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';
 
    private $data, $size, $maxSize;
    private $errorFormatter;
 
    // Deprecated fields
    private $checkingSize, $mainForContinuation;
 
    public function __construct( $maxSize ) {
        if ( $maxSize instanceof ApiMain ) {
            wfDeprecated( 'ApiMain to ' . __METHOD__, '1.25' );
            $this->errorFormatter = $maxSize->getErrorFormatter();
            $this->mainForContinuation = $maxSize;
            $maxSize = $maxSize->getConfig()->get( 'APIMaxResultSize' );
        }
 
        $this->maxSize = $maxSize;
        $this->checkingSize = true;
        $this->reset();
    }
 
    public function setErrorFormatter( ApiErrorFormatter $formatter ) {
        $this->errorFormatter = $formatter;
    }
 
    public function serializeForApiResult() {
        return $this->data;
    }
 
    /************************************************************************/
    public function reset() {
        $this->data = [
            self::META_TYPE => 'assoc', // Usually what's desired
        ];
        $this->size = 0;
    }
 
    public function getResultData( $path = [], $transforms = [] ) {
        $path = (array)$path;
        if ( !$path ) {
            return self::applyTransformations( $this->data, $transforms );
        }
 
        $last = array_pop( $path );
        $ret = &$this->path( $path, 'dummy' );
        if ( !isset( $ret[$last] ) ) {
            return null;
        } elseif ( is_array( $ret[$last] ) ) {
            return self::applyTransformations( $ret[$last], $transforms );
        } else {
            return $ret[$last];
        }
    }
 
    public function getSize() {
        return $this->size;
    }
 
    public static function setValue( array &$arr, $name, $value, $flags = 0 ) {
        if ( ( $flags & ApiResult::NO_VALIDATE ) !== ApiResult::NO_VALIDATE ) {
            $value = self::validateValue( $value );
        }
 
        if ( $name === null ) {
            if ( $flags & ApiResult::ADD_ON_TOP ) {
                array_unshift( $arr, $value );
            } else {
                array_push( $arr, $value );
            }
            return;
        }
 
        $exists = isset( $arr[$name] );
        if ( !$exists || ( $flags & ApiResult::OVERRIDE ) ) {
            if ( !$exists && ( $flags & ApiResult::ADD_ON_TOP ) ) {
                $arr = [ $name => $value ] + $arr;
            } else {
                $arr[$name] = $value;
            }
        } elseif ( is_array( $arr[$name] ) && is_array( $value ) ) {
            $conflicts = array_intersect_key( $arr[$name], $value );
            if ( !$conflicts ) {
                $arr[$name] += $value;
            } else {
                $keys = implode( ', ', array_keys( $conflicts ) );
                throw new RuntimeException(
                    "Conflicting keys ($keys) when attempting to merge element $name"
                );
            }
        } else {
            throw new RuntimeException(
                "Attempting to add element $name=$value, existing value is {$arr[$name]}"
            );
        }
    }
 
    private static function validateValue( $value ) {
        global $wgContLang;
 
        if ( is_object( $value ) ) {
            // Note we use is_callable() here instead of instanceof because
            // ApiSerializable is an informal protocol (see docs there for details).
            if ( is_callable( [ $value, 'serializeForApiResult' ] ) ) {
                $oldValue = $value;
                $value = $value->serializeForApiResult();
                if ( is_object( $value ) ) {
                    throw new UnexpectedValueException(
                        get_class( $oldValue ) . '::serializeForApiResult() returned an object of class ' .
                            get_class( $value )
                    );
                }
 
                // Recursive call instead of fall-through so we can throw a
                // better exception message.
                try {
                    return self::validateValue( $value );
                } catch ( Exception $ex ) {
                    throw new UnexpectedValueException(
                        get_class( $oldValue ) . '::serializeForApiResult() returned an invalid value: ' .
                            $ex->getMessage(),
                        0,
                        $ex
                    );
                }
            } elseif ( is_callable( [ $value, '__toString' ] ) ) {
                $value = (string)$value;
            } else {
                $value = (array)$value + [ self::META_TYPE => 'assoc' ];
            }
        }
        if ( is_array( $value ) ) {
            // Work around PHP bug 45959 by copying to a temporary
            // (in this case, foreach gets $k === "1" but $tmp[$k] assigns as if $k === 1)
            $tmp = [];
            foreach ( $value as $k => $v ) {
                $tmp[$k] = self::validateValue( $v );
            }
            $value = $tmp;
        } elseif ( is_float( $value ) && !is_finite( $value ) ) {
            throw new InvalidArgumentException( 'Cannot add non-finite floats to ApiResult' );
        } elseif ( is_string( $value ) ) {
            $value = $wgContLang->normalize( $value );
        } elseif ( $value !== null && !is_scalar( $value ) ) {
            $type = gettype( $value );
            if ( is_resource( $value ) ) {
                $type .= '(' . get_resource_type( $value ) . ')';
            }
            throw new InvalidArgumentException( "Cannot add $type to ApiResult" );
        }
 
        return $value;
    }
 
    public function addValue( $path, $name, $value, $flags = 0 ) {
        $arr = &$this->path( $path, ( $flags & ApiResult::ADD_ON_TOP ) ? 'prepend' : 'append' );
 
        if ( $this->checkingSize && !( $flags & ApiResult::NO_SIZE_CHECK ) ) {
            // self::size needs the validated value. Then flag
            // to not re-validate later.
            $value = self::validateValue( $value );
            $flags |= ApiResult::NO_VALIDATE;
 
            $newsize = $this->size + self::size( $value );
            if ( $this->maxSize !== false && $newsize > $this->maxSize ) {
                $msg = new ApiRawMessage( 'This result was truncated because it would otherwise ' .
                    'be larger than the limit of $1 bytes', 'truncatedresult' );
                $msg->numParams( $this->maxSize );
                $this->errorFormatter->addWarning( 'result', $msg );
                return false;
            }
            $this->size = $newsize;
        }
 
        self::setValue( $arr, $name, $value, $flags );
        return true;
    }
 
    public static function unsetValue( array &$arr, $name ) {
        $ret = null;
        if ( isset( $arr[$name] ) ) {
            $ret = $arr[$name];
            unset( $arr[$name] );
        }
        return $ret;
    }
 
    public function removeValue( $path, $name, $flags = 0 ) {
        $path = (array)$path;
        if ( $name === null ) {
            if ( !$path ) {
                throw new InvalidArgumentException( 'Cannot remove the data root' );
            }
            $name = array_pop( $path );
        }
        $ret = self::unsetValue( $this->path( $path, 'dummy' ), $name );
        if ( $this->checkingSize && !( $flags & ApiResult::NO_SIZE_CHECK ) ) {
            $newsize = $this->size - self::size( $ret );
            $this->size = max( $newsize, 0 );
        }
        return $ret;
    }
 
    public static function setContentValue( array &$arr, $name, $value, $flags = 0 ) {
        if ( $name === null ) {
            throw new InvalidArgumentException( 'Content value must be named' );
        }
        self::setContentField( $arr, $name, $flags );
        self::setValue( $arr, $name, $value, $flags );
    }
 
    public function addContentValue( $path, $name, $value, $flags = 0 ) {
        if ( $name === null ) {
            throw new InvalidArgumentException( 'Content value must be named' );
        }
        $this->addContentField( $path, $name, $flags );
        $this->addValue( $path, $name, $value, $flags );
    }
 
    public function addParsedLimit( $moduleName, $limit ) {
        // Add value, allowing overwriting
        $this->addValue( 'limits', $moduleName, $limit,
            ApiResult::OVERRIDE | ApiResult::NO_SIZE_CHECK );
    }
 
    /************************************************************************/
    public static function setContentField( array &$arr, $name, $flags = 0 ) {
        if ( isset( $arr[self::META_CONTENT] ) &&
            isset( $arr[$arr[self::META_CONTENT]] ) &&
            !( $flags & self::OVERRIDE )
        ) {
            throw new RuntimeException(
                "Attempting to set content element as $name when " . $arr[self::META_CONTENT] .
                    ' is already set as the content element'
            );
        }
        $arr[self::META_CONTENT] = $name;
    }
 
    public function addContentField( $path, $name, $flags = 0 ) {
        $arr = &$this->path( $path, ( $flags & ApiResult::ADD_ON_TOP ) ? 'prepend' : 'append' );
        self::setContentField( $arr, $name, $flags );
    }
 
    public static function setSubelementsList( array &$arr, $names ) {
        if ( !isset( $arr[self::META_SUBELEMENTS] ) ) {
            $arr[self::META_SUBELEMENTS] = (array)$names;
        } else {
            $arr[self::META_SUBELEMENTS] = array_merge( $arr[self::META_SUBELEMENTS], (array)$names );
        }
    }
 
    public function addSubelementsList( $path, $names ) {
        $arr = &$this->path( $path );
        self::setSubelementsList( $arr, $names );
    }
 
    public static function unsetSubelementsList( array &$arr, $names ) {
        if ( isset( $arr[self::META_SUBELEMENTS] ) ) {
            $arr[self::META_SUBELEMENTS] = array_diff( $arr[self::META_SUBELEMENTS], (array)$names );
        }
    }
 
    public function removeSubelementsList( $path, $names ) {
        $arr = &$this->path( $path );
        self::unsetSubelementsList( $arr, $names );
    }
 
    public static function setIndexedTagName( array &$arr, $tag ) {
        if ( !is_string( $tag ) ) {
            throw new InvalidArgumentException( 'Bad tag name' );
        }
        $arr[self::META_INDEXED_TAG_NAME] = $tag;
    }
 
    public function addIndexedTagName( $path, $tag ) {
        $arr = &$this->path( $path );
        self::setIndexedTagName( $arr, $tag );
    }
 
    public static function setIndexedTagNameRecursive( array &$arr, $tag ) {
        if ( !is_string( $tag ) ) {
            throw new InvalidArgumentException( 'Bad tag name' );
        }
        $arr[self::META_INDEXED_TAG_NAME] = $tag;
        foreach ( $arr as $k => &$v ) {
            if ( !self::isMetadataKey( $k ) && is_array( $v ) ) {
                self::setIndexedTagNameRecursive( $v, $tag );
            }
        }
    }
 
    public function addIndexedTagNameRecursive( $path, $tag ) {
        $arr = &$this->path( $path );
        self::setIndexedTagNameRecursive( $arr, $tag );
    }
 
    public static function setPreserveKeysList( array &$arr, $names ) {
        if ( !isset( $arr[self::META_PRESERVE_KEYS] ) ) {
            $arr[self::META_PRESERVE_KEYS] = (array)$names;
        } else {
            $arr[self::META_PRESERVE_KEYS] = array_merge( $arr[self::META_PRESERVE_KEYS], (array)$names );
        }
    }
 
    public function addPreserveKeysList( $path, $names ) {
        $arr = &$this->path( $path );
        self::setPreserveKeysList( $arr, $names );
    }
 
    public static function unsetPreserveKeysList( array &$arr, $names ) {
        if ( isset( $arr[self::META_PRESERVE_KEYS] ) ) {
            $arr[self::META_PRESERVE_KEYS] = array_diff( $arr[self::META_PRESERVE_KEYS], (array)$names );
        }
    }
 
    public function removePreserveKeysList( $path, $names ) {
        $arr = &$this->path( $path );
        self::unsetPreserveKeysList( $arr, $names );
    }
 
    public static function setArrayType( array &$arr, $type, $kvpKeyName = null ) {
        if ( !in_array( $type, [
                'default', 'array', 'assoc', 'kvp', 'BCarray', 'BCassoc', 'BCkvp'
                ], true ) ) {
            throw new InvalidArgumentException( 'Bad type' );
        }
        $arr[self::META_TYPE] = $type;
        if ( is_string( $kvpKeyName ) ) {
            $arr[self::META_KVP_KEY_NAME] = $kvpKeyName;
        }
    }
 
    public function addArrayType( $path, $tag, $kvpKeyName = null ) {
        $arr = &$this->path( $path );
        self::setArrayType( $arr, $tag, $kvpKeyName );
    }
 
    public static function setArrayTypeRecursive( array &$arr, $type, $kvpKeyName = null ) {
        self::setArrayType( $arr, $type, $kvpKeyName );
        foreach ( $arr as $k => &$v ) {
            if ( !self::isMetadataKey( $k ) && is_array( $v ) ) {
                self::setArrayTypeRecursive( $v, $type, $kvpKeyName );
            }
        }
    }
 
    public function addArrayTypeRecursive( $path, $tag, $kvpKeyName = null ) {
        $arr = &$this->path( $path );
        self::setArrayTypeRecursive( $arr, $tag, $kvpKeyName );
    }
 
    /************************************************************************/
    public static function isMetadataKey( $key ) {
        return substr( $key, 0, 1 ) === '_';
    }
 
    protected static function applyTransformations( array $dataIn, array $transforms ) {
        $strip = isset( $transforms['Strip'] ) ? $transforms['Strip'] : 'none';
        if ( $strip === 'base' ) {
            $transforms['Strip'] = 'none';
        }
        $transformTypes = isset( $transforms['Types'] ) ? $transforms['Types'] : null;
        if ( $transformTypes !== null && !is_array( $transformTypes ) ) {
            throw new InvalidArgumentException( __METHOD__ . ':Value for "Types" must be an array' );
        }
 
        $metadata = [];
        $data = self::stripMetadataNonRecursive( $dataIn, $metadata );
 
        if ( isset( $transforms['Custom'] ) ) {
            if ( !is_callable( $transforms['Custom'] ) ) {
                throw new InvalidArgumentException( __METHOD__ . ': Value for "Custom" must be callable' );
            }
            call_user_func_array( $transforms['Custom'], [ &$data, &$metadata ] );
        }
 
        if ( ( isset( $transforms['BC'] ) || $transformTypes !== null ) &&
            isset( $metadata[self::META_TYPE] ) && $metadata[self::META_TYPE] === 'BCkvp' &&
            !isset( $metadata[self::META_KVP_KEY_NAME] )
        ) {
            throw new UnexpectedValueException( 'Type "BCkvp" used without setting ' .
                'ApiResult::META_KVP_KEY_NAME metadata item' );
        }
 
        // BC transformations
        $boolKeys = null;
        if ( isset( $transforms['BC'] ) ) {
            if ( !is_array( $transforms['BC'] ) ) {
                throw new InvalidArgumentException( __METHOD__ . ':Value for "BC" must be an array' );
            }
            if ( !in_array( 'nobool', $transforms['BC'], true ) ) {
                $boolKeys = isset( $metadata[self::META_BC_BOOLS] )
                    ? array_flip( $metadata[self::META_BC_BOOLS] )
                    : [];
            }
 
            if ( !in_array( 'no*', $transforms['BC'], true ) &&
                isset( $metadata[self::META_CONTENT] ) && $metadata[self::META_CONTENT] !== '*'
            ) {
                $k = $metadata[self::META_CONTENT];
                $data['*'] = $data[$k];
                unset( $data[$k] );
                $metadata[self::META_CONTENT] = '*';
            }
 
            if ( !in_array( 'nosub', $transforms['BC'], true ) &&
                isset( $metadata[self::META_BC_SUBELEMENTS] )
            ) {
                foreach ( $metadata[self::META_BC_SUBELEMENTS] as $k ) {
                    if ( isset( $data[$k] ) ) {
                        $data[$k] = [
                            '*' => $data[$k],
                            self::META_CONTENT => '*',
                            self::META_TYPE => 'assoc',
                        ];
                    }
                }
            }
 
            if ( isset( $metadata[self::META_TYPE] ) ) {
                switch ( $metadata[self::META_TYPE] ) {
                    case 'BCarray':
                    case 'BCassoc':
                        $metadata[self::META_TYPE] = 'default';
                        break;
                    case 'BCkvp':
                        $transformTypes['ArmorKVP'] = $metadata[self::META_KVP_KEY_NAME];
                        break;
                }
            }
        }
 
        // Figure out type, do recursive calls, and do boolean transform if necessary
        $defaultType = 'array';
        $maxKey = -1;
        foreach ( $data as $k => &$v ) {
            $v = is_array( $v ) ? self::applyTransformations( $v, $transforms ) : $v;
            if ( $boolKeys !== null && is_bool( $v ) && !isset( $boolKeys[$k] ) ) {
                if ( !$v ) {
                    unset( $data[$k] );
                    continue;
                }
                $v = '';
            }
            if ( is_string( $k ) ) {
                $defaultType = 'assoc';
            } elseif ( $k > $maxKey ) {
                $maxKey = $k;
            }
        }
        unset( $v );
 
        // Determine which metadata to keep
        switch ( $strip ) {
            case 'all':
            case 'base':
                $keepMetadata = [];
                break;
            case 'none':
                $keepMetadata = &$metadata;
                break;
            case 'bc':
                $keepMetadata = array_intersect_key( $metadata, [
                    self::META_INDEXED_TAG_NAME => 1,
                    self::META_SUBELEMENTS => 1,
                ] );
                break;
            default:
                throw new InvalidArgumentException( __METHOD__ . ': Unknown value for "Strip"' );
        }
 
        // Type transformation
        if ( $transformTypes !== null ) {
            if ( $defaultType === 'array' && $maxKey !== count( $data ) - 1 ) {
                $defaultType = 'assoc';
            }
 
            // Override type, if provided
            $type = $defaultType;
            if ( isset( $metadata[self::META_TYPE] ) && $metadata[self::META_TYPE] !== 'default' ) {
                $type = $metadata[self::META_TYPE];
            }
            if ( ( $type === 'kvp' || $type === 'BCkvp' ) &&
                empty( $transformTypes['ArmorKVP'] )
            ) {
                $type = 'assoc';
            } elseif ( $type === 'BCarray' ) {
                $type = 'array';
            } elseif ( $type === 'BCassoc' ) {
                $type = 'assoc';
            }
 
            // Apply transformation
            switch ( $type ) {
                case 'assoc':
                    $metadata[self::META_TYPE] = 'assoc';
                    $data += $keepMetadata;
                    return empty( $transformTypes['AssocAsObject'] ) ? $data : (object)$data;
 
                case 'array':
                    ksort( $data );
                    $data = array_values( $data );
                    $metadata[self::META_TYPE] = 'array';
                    return $data + $keepMetadata;
 
                case 'kvp':
                case 'BCkvp':
                    $key = isset( $metadata[self::META_KVP_KEY_NAME] )
                        ? $metadata[self::META_KVP_KEY_NAME]
                        : $transformTypes['ArmorKVP'];
                    $valKey = isset( $transforms['BC'] ) ? '*' : 'value';
                    $assocAsObject = !empty( $transformTypes['AssocAsObject'] );
                    $merge = !empty( $metadata[self::META_KVP_MERGE] );
 
                    $ret = [];
                    foreach ( $data as $k => $v ) {
                        if ( $merge && ( is_array( $v ) || is_object( $v ) ) ) {
                            $vArr = (array)$v;
                            if ( isset( $vArr[self::META_TYPE] ) ) {
                                $mergeType = $vArr[self::META_TYPE];
                            } elseif ( is_object( $v ) ) {
                                $mergeType = 'assoc';
                            } else {
                                $keys = array_keys( $vArr );
                                sort( $keys, SORT_NUMERIC );
                                $mergeType = ( $keys === array_keys( $keys ) ) ? 'array' : 'assoc';
                            }
                        } else {
                            $mergeType = 'n/a';
                        }
                        if ( $mergeType === 'assoc' ) {
                            $item = $vArr + [
                                $key => $k,
                            ];
                            if ( $strip === 'none' ) {
                                self::setPreserveKeysList( $item, [ $key ] );
                            }
                        } else {
                            $item = [
                                $key => $k,
                                $valKey => $v,
                            ];
                            if ( $strip === 'none' ) {
                                $item += [
                                    self::META_PRESERVE_KEYS => [ $key ],
                                    self::META_CONTENT => $valKey,
                                    self::META_TYPE => 'assoc',
                                ];
                            }
                        }
                        $ret[] = $assocAsObject ? (object)$item : $item;
                    }
                    $metadata[self::META_TYPE] = 'array';
 
                    return $ret + $keepMetadata;
 
                default:
                    throw new UnexpectedValueException( "Unknown type '$type'" );
            }
        } else {
            return $data + $keepMetadata;
        }
    }
 
    public static function stripMetadata( $data ) {
        if ( is_array( $data ) || is_object( $data ) ) {
            $isObj = is_object( $data );
            if ( $isObj ) {
                $data = (array)$data;
            }
            $preserveKeys = isset( $data[self::META_PRESERVE_KEYS] )
                ? (array)$data[self::META_PRESERVE_KEYS]
                : [];
            foreach ( $data as $k => $v ) {
                if ( self::isMetadataKey( $k ) && !in_array( $k, $preserveKeys, true ) ) {
                    unset( $data[$k] );
                } elseif ( is_array( $v ) || is_object( $v ) ) {
                    $data[$k] = self::stripMetadata( $v );
                }
            }
            if ( $isObj ) {
                $data = (object)$data;
            }
        }
        return $data;
    }
 
    public static function stripMetadataNonRecursive( $data, &$metadata = null ) {
        if ( !is_array( $metadata ) ) {
            $metadata = [];
        }
        if ( is_array( $data ) || is_object( $data ) ) {
            $isObj = is_object( $data );
            if ( $isObj ) {
                $data = (array)$data;
            }
            $preserveKeys = isset( $data[self::META_PRESERVE_KEYS] )
                ? (array)$data[self::META_PRESERVE_KEYS]
                : [];
            foreach ( $data as $k => $v ) {
                if ( self::isMetadataKey( $k ) && !in_array( $k, $preserveKeys, true ) ) {
                    $metadata[$k] = $v;
                    unset( $data[$k] );
                }
            }
            if ( $isObj ) {
                $data = (object)$data;
            }
        }
        return $data;
    }
 
    private static function size( $value ) {
        $s = 0;
        if ( is_array( $value ) ) {
            foreach ( $value as $k => $v ) {
                if ( !self::isMetadataKey( $k ) ) {
                    $s += self::size( $v );
                }
            }
        } elseif ( is_scalar( $value ) ) {
            $s = strlen( $value );
        }
 
        return $s;
    }
 
    private function &path( $path, $create = 'append' ) {
        $path = (array)$path;
        $ret = &$this->data;
        foreach ( $path as $i => $k ) {
            if ( !isset( $ret[$k] ) ) {
                switch ( $create ) {
                    case 'append':
                        $ret[$k] = [];
                        break;
                    case 'prepend':
                        $ret = [ $k => [] ] + $ret;
                        break;
                    case 'dummy':
                        $tmp = [];
                        return $tmp;
                    default:
                        $fail = implode( '.', array_slice( $path, 0, $i + 1 ) );
                        throw new InvalidArgumentException( "Path $fail does not exist" );
                }
            }
            if ( !is_array( $ret[$k] ) ) {
                $fail = implode( '.', array_slice( $path, 0, $i + 1 ) );
                throw new InvalidArgumentException( "Path $fail is not an array" );
            }
            $ret = &$ret[$k];
        }
        return $ret;
    }
 
    public static function addMetadataToResultVars( $vars, $forceHash = true ) {
        // Process subarrays and determine if this is a JS [] or {}
        $hash = $forceHash;
        $maxKey = -1;
        $bools = [];
        foreach ( $vars as $k => $v ) {
            if ( is_array( $v ) || is_object( $v ) ) {
                $vars[$k] = ApiResult::addMetadataToResultVars( (array)$v, is_object( $v ) );
            } elseif ( is_bool( $v ) ) {
                // Better here to use real bools even in BC formats
                $bools[] = $k;
            }
            if ( is_string( $k ) ) {
                $hash = true;
            } elseif ( $k > $maxKey ) {
                $maxKey = $k;
            }
        }
        if ( !$hash && $maxKey !== count( $vars ) - 1 ) {
            $hash = true;
        }
 
        // Set metadata appropriately
        if ( $hash ) {
            // Get the list of keys we actually care about. Unfortunately, we can't support
            // certain keys that conflict with ApiResult metadata.
            $keys = array_diff( array_keys( $vars ), [
                ApiResult::META_TYPE, ApiResult::META_PRESERVE_KEYS, ApiResult::META_KVP_KEY_NAME,
                ApiResult::META_INDEXED_TAG_NAME, ApiResult::META_BC_BOOLS
            ] );
 
            return [
                ApiResult::META_TYPE => 'kvp',
                ApiResult::META_KVP_KEY_NAME => 'key',
                ApiResult::META_PRESERVE_KEYS => $keys,
                ApiResult::META_BC_BOOLS => $bools,
                ApiResult::META_INDEXED_TAG_NAME => 'var',
            ] + $vars;
        } else {
            return [
                ApiResult::META_TYPE => 'array',
                ApiResult::META_BC_BOOLS => $bools,
                ApiResult::META_INDEXED_TAG_NAME => 'value',
            ] + $vars;
        }
    }
 
}