ApiResult.php

Go to the documentation of this file.

<?php
use MediaWiki\MediaWikiServices;
 
class ApiResult implements ApiSerializable {
 
    public const OVERRIDE = 1;
 
    public const ADD_ON_TOP = 2;
 
    public const NO_SIZE_CHECK = 4;
 
    public const NO_VALIDATE = self::NO_SIZE_CHECK | 8;
 
    public const META_INDEXED_TAG_NAME = '_element';
 
    public const META_SUBELEMENTS = '_subelements';
 
    public const META_PRESERVE_KEYS = '_preservekeys';
 
    public const META_CONTENT = '_content';
 
    public const META_TYPE = '_type';
 
    public const META_KVP_KEY_NAME = '_kvpkeyname';
 
    public const META_KVP_MERGE = '_kvpmerge';
 
    public const META_BC_BOOLS = '_BC_bools';
 
    public const META_BC_SUBELEMENTS = '_BC_subelements';
 
    private $data, $size, $maxSize;
    private $errorFormatter;
 
    public function __construct( $maxSize ) {
        $this->maxSize = $maxSize;
        $this->reset();
    }
 
    public function setErrorFormatter( ApiErrorFormatter $formatter ) {
        $this->errorFormatter = $formatter;
    }
 
    public function serializeForApiResult() {
        return $this->data;
    }
 
    /***************************************************************************/
    // region   Content
    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 & self::NO_VALIDATE ) !== self::NO_VALIDATE ) {
            $value = self::validateValue( $value );
        }
 
        if ( $name === null ) {
            if ( $flags & self::ADD_ON_TOP ) {
                array_unshift( $arr, $value );
            } else {
                $arr[] = $value;
            }
            return;
        }
 
        $exists = isset( $arr[$name] );
        if ( !$exists || ( $flags & self::OVERRIDE ) ) {
            if ( !$exists && ( $flags & self::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"
                );
            }
        } elseif ( $value !== $arr[$name] ) {
            throw new RuntimeException(
                "Attempting to add element $name=$value, existing value is {$arr[$name]}"
            );
        }
    }
 
    private static function validateValue( $value ) {
        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_string( $value ) ) {
            // Optimization: avoid querying the service locator for each value.
            static $contentLanguage = null;
            if ( !$contentLanguage ) {
                $contentLanguage = MediaWikiServices::getInstance()->getContentLanguage();
            }
            $value = $contentLanguage->normalize( $value );
        } elseif ( is_array( $value ) ) {
            foreach ( $value as $k => $v ) {
                $value[$k] = self::validateValue( $v );
            }
        } elseif ( $value !== null && !is_scalar( $value ) ) {
            $type = gettype( $value );
            // phpcs:ignore MediaWiki.Usage.ForbiddenFunctions.is_resource
            if ( is_resource( $value ) ) {
                $type .= '(' . get_resource_type( $value ) . ')';
            }
            throw new InvalidArgumentException( "Cannot add $type to ApiResult" );
        } elseif ( is_float( $value ) && !is_finite( $value ) ) {
            throw new InvalidArgumentException( 'Cannot add non-finite floats to ApiResult' );
        }
 
        return $value;
    }
 
    public function addValue( $path, $name, $value, $flags = 0 ) {
        $arr = &$this->path( $path, ( $flags & self::ADD_ON_TOP ) ? 'prepend' : 'append' );
 
        if ( !( $flags & self::NO_SIZE_CHECK ) ) {
            // self::size needs the validated value. Then flag
            // to not re-validate later.
            $value = self::validateValue( $value );
            $flags |= self::NO_VALIDATE;
 
            $newsize = $this->size + self::size( $value );
            if ( $this->maxSize !== false && $newsize > $this->maxSize ) {
                $this->errorFormatter->addWarning(
                    'result', [ 'apiwarn-truncatedresult', Message::numParam( $this->maxSize ) ]
                );
                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 ( !( $flags & self::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 );
        return $this->addValue( $path, $name, $value, $flags );
    }
 
    public function addParsedLimit( $moduleName, $limit ) {
        // Add value, allowing overwriting
        $this->addValue( 'limits', $moduleName, $limit,
            self::OVERRIDE | self::NO_SIZE_CHECK );
    }
 
    // endregion -- end of Content
 
    /***************************************************************************/
    // region   Metadata
    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 & self::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 ( is_array( $v ) && !self::isMetadataKey( $k ) ) {
                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 ( is_array( $v ) && !self::isMetadataKey( $k ) ) {
                self::setArrayTypeRecursive( $v, $type, $kvpKeyName );
            }
        }
    }
 
    public function addArrayTypeRecursive( $path, $tag, $kvpKeyName = null ) {
        $arr = &$this->path( $path );
        self::setArrayTypeRecursive( $arr, $tag, $kvpKeyName );
    }
 
    // endregion -- end of Metadata
 
    /***************************************************************************/
    // region   Utility
    public static function isMetadataKey( $key ) {
        // Optimization: This is a very hot and highly optimized code path. Note that ord() only
        // considers the first character and also works with empty strings and integers.
        // 95 corresponds to the '_' character.
        return ord( $key ) === 95;
    }
 
    protected static function applyTransformations( array $dataIn, array $transforms ) {
        $strip = $transforms['Strip'] ?? 'none';
        if ( $strip === 'base' ) {
            $transforms['Strip'] = 'none';
        }
        $transformTypes = $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_fill_keys( $metadata[self::META_BC_BOOLS], true )
                    : [];
            }
 
            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':
                // @phan-suppress-next-line PhanTypeMismatchArgumentNullableInternal Type mismatch on pass-by-ref args
                $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"' );
        }
 
        // No type transformation
        if ( $transformTypes === null ) {
            return $data + $keepMetadata;
        }
 
        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':
                // Sort items in ascending order by key. Note that $data may contain a mix of number and string keys,
                // for which the sorting behavior of krsort() with SORT_REGULAR is inconsistent between PHP versions.
                // Given a comparison of a string key and a number key, PHP < 8.2 coerces the string key into a number
                // (which yields zero if the string was non-numeric), and then performs the comparison,
                // while PHP >= 8.2 makes the behavior consistent with stricter numeric comparisons introduced by
                // PHP 8.0 in that if the string key is non-numeric, it converts the number key into a string
                // and compares those two strings instead. We therefore use a custom comparison function
                // implementing PHP >= 8.2 ordering semantics to ensure consistent ordering of items
                // irrespective of the PHP version (T326480).
                uksort( $data, static function ( $a, $b ): int {
                    // In a comparison of a number or numeric string with a non-numeric string,
                    // coerce both values into a string prior to comparing and compare the resulting strings.
                    // Note that PHP prior to 8.0 did not consider numeric strings with trailing whitespace
                    // to be numeric, so trim the inputs prior to the numeric checks to make the behavior
                    // consistent across PHP versions.
                    if ( is_numeric( trim( $a ) ) xor is_numeric( trim( $b ) ) ) {
                        return (string)$a <=> (string)$b;
                    }
 
                    return $a <=> $b;
                } );
 
                $data = array_values( $data );
                $metadata[self::META_TYPE] = 'array';
                // @phan-suppress-next-line PhanTypeMismatchReturnNullable Type mismatch on pass-by-ref args
                return $data + $keepMetadata;
 
            case 'kvp':
            case 'BCkvp':
                $key = $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' ) {
                        // @phan-suppress-next-line PhanPossiblyUndeclaredVariable vArr set when used
                        $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';
 
                // @phan-suppress-next-line PhanTypeMismatchReturnNullable Type mismatch on pass-by-ref args
                return $ret + $keepMetadata;
 
            default:
                throw new UnexpectedValueException( "Unknown type '$type'" );
        }
    }
 
    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] = self::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 ), [
                self::META_TYPE, self::META_PRESERVE_KEYS, self::META_KVP_KEY_NAME,
                self::META_INDEXED_TAG_NAME, self::META_BC_BOOLS
            ] );
 
            return [
                self::META_TYPE => 'kvp',
                self::META_KVP_KEY_NAME => 'key',
                self::META_PRESERVE_KEYS => $keys,
                self::META_BC_BOOLS => $bools,
                self::META_INDEXED_TAG_NAME => 'var',
            ] + $vars;
        } else {
            return [
                self::META_TYPE => 'array',
                self::META_BC_BOOLS => $bools,
                self::META_INDEXED_TAG_NAME => 'value',
            ] + $vars;
        }
    }
 
    public static function formatExpiry( $expiry, $infinity = 'infinity' ) {
        static $dbInfinity;
        $dbInfinity ??= MediaWikiServices::getInstance()->getDBLoadBalancerFactory()
            ->getReplicaDatabase()
            ->getInfinity();
 
        if ( $expiry === '' || $expiry === null || $expiry === false ||
            wfIsInfinity( $expiry ) || $expiry === $dbInfinity
        ) {
            return $infinity;
        } else {
            return wfTimestamp( TS_ISO_8601, $expiry );
        }
    }
 
    // endregion -- end of Utility
 
}
 
/*
 * This file uses VisualStudio style region/endregion fold markers which are
 * recognised by PHPStorm. If modelines are enabled, the following editor
 * configuration will also enable folding in vim, if it is in the last 5 lines
 * of the file. We also use "@name" which creates sections in Doxygen.
 *
 * vim: foldmarker=//\ region,//\ endregion foldmethod=marker
 */