ApiResult.php

Go to the documentation of this file.

<?php
class ApiResult extends ApiBase {

        const OVERRIDE = 1;

        const ADD_ON_TOP = 2;

        private $mData, $mIsRawMode, $mSize, $mCheckingSize;

        public function __construct( $main ) {
                parent::__construct( $main, 'result' );
                $this->mIsRawMode = false;
                $this->mCheckingSize = true;
                $this->reset();
        }

        public function reset() {
                $this->mData = array();
                $this->mSize = 0;
        }

        public function setRawMode() {
                $this->mIsRawMode = true;
        }

        public function getIsRawMode() {
                return $this->mIsRawMode;
        }

        public function getData() {
                return $this->mData;
        }

        public static function size( $value ) {
                $s = 0;
                if ( is_array( $value ) ) {
                        foreach ( $value as $v ) {
                                $s += self::size( $v );
                        }
                } elseif ( !is_object( $value ) ) {
                        // Objects can't always be cast to string
                        $s = strlen( $value );
                }
                return $s;
        }

        public function getSize() {
                return $this->mSize;
        }

        public function disableSizeCheck() {
                $this->mCheckingSize = false;
        }

        public function enableSizeCheck() {
                $this->mCheckingSize = true;
        }

        public static function setElement( &$arr, $name, $value, $flags = 0 ) {
                if ( $arr === null || $name === null || $value === null || !is_array( $arr ) || is_array( $name ) ) {
                        ApiBase::dieDebug( __METHOD__, 'Bad parameter' );
                }

                $exists = isset( $arr[$name] );
                if ( !$exists || ( $flags & ApiResult::OVERRIDE ) ) {
                        if ( !$exists && ( $flags & ApiResult::ADD_ON_TOP ) ) {
                                $arr = array( $name => $value ) + $arr;
                        } else {
                                $arr[$name] = $value;
                        }
                } elseif ( is_array( $arr[$name] ) && is_array( $value ) ) {
                        $merged = array_intersect_key( $arr[$name], $value );
                        if ( !count( $merged ) ) {
                                $arr[$name] += $value;
                        } else {
                                ApiBase::dieDebug( __METHOD__, "Attempting to merge element $name" );
                        }
                } else {
                        ApiBase::dieDebug( __METHOD__, "Attempting to add element $name=$value, existing value is {$arr[$name]}" );
                }
        }

        public static function setContent( &$arr, $value, $subElemName = null ) {
                if ( is_array( $value ) ) {
                        ApiBase::dieDebug( __METHOD__, 'Bad parameter' );
                }
                if ( is_null( $subElemName ) ) {
                        ApiResult::setElement( $arr, '*', $value );
                } else {
                        if ( !isset( $arr[$subElemName] ) ) {
                                $arr[$subElemName] = array();
                        }
                        ApiResult::setElement( $arr[$subElemName], '*', $value );
                }
        }

        public function setIndexedTagName( &$arr, $tag ) {
                // In raw mode, add the '_element', otherwise just ignore
                if ( !$this->getIsRawMode() ) {
                        return;
                }
                if ( $arr === null || $tag === null || !is_array( $arr ) || is_array( $tag ) ) {
                        ApiBase::dieDebug( __METHOD__, 'Bad parameter' );
                }
                // Do not use setElement() as it is ok to call this more than once
                $arr['_element'] = $tag;
        }

        public function setIndexedTagName_recursive( &$arr, $tag ) {
                if ( !is_array( $arr ) ) {
                        return;
                }
                foreach ( $arr as &$a ) {
                        if ( !is_array( $a ) ) {
                                continue;
                        }
                        $this->setIndexedTagName( $a, $tag );
                        $this->setIndexedTagName_recursive( $a, $tag );
                }
        }

        public function setIndexedTagName_internal( $path, $tag ) {
                $data = &$this->mData;
                foreach ( (array)$path as $p ) {
                        if ( !isset( $data[$p] ) ) {
                                $data[$p] = array();
                        }
                        $data = &$data[$p];
                }
                if ( is_null( $data ) ) {
                        return;
                }
                $this->setIndexedTagName( $data, $tag );
        }

        public function addValue( $path, $name, $value, $flags = 0 ) {
                global $wgAPIMaxResultSize;

                $data = &$this->mData;
                if ( $this->mCheckingSize ) {
                        $newsize = $this->mSize + self::size( $value );
                        if ( $newsize > $wgAPIMaxResultSize ) {
                                $this->setWarning(
                                        "This result was truncated because it would otherwise be larger than the " .
                                                        "limit of {$wgAPIMaxResultSize} bytes" );
                                return false;
                        }
                        $this->mSize = $newsize;
                }

                $addOnTop = $flags & ApiResult::ADD_ON_TOP;
                if ( $path !== null ) {
                        foreach ( (array)$path as $p ) {
                                if ( !isset( $data[$p] ) ) {
                                        if ( $addOnTop ) {
                                                $data = array( $p => array() ) + $data;
                                                $addOnTop = false;
                                        } else {
                                                $data[$p] = array();
                                        }
                                }
                                $data = &$data[$p];
                        }
                }

                if ( !$name ) {
                        // Add list element
                        if ( $addOnTop ) {
                                // This element needs to be inserted in the beginning
                                // Numerical indexes will be renumbered
                                array_unshift( $data, $value );
                        } else {
                                // Add new value at the end
                                $data[] = $value;
                        }
                } else {
                        // Add named element
                        self::setElement( $data, $name, $value, $flags );
                }
                return true;
        }

        public function setParsedLimit( $moduleName, $limit ) {
                // Add value, allowing overwriting
                $this->addValue( 'limits', $moduleName, $limit, ApiResult::OVERRIDE );
        }

        public function unsetValue( $path, $name ) {
                $data = &$this->mData;
                if ( $path !== null ) {
                        foreach ( (array)$path as $p ) {
                                if ( !isset( $data[$p] ) ) {
                                        return;
                                }
                                $data = &$data[$p];
                        }
                }
                $this->mSize -= self::size( $data[$name] );
                unset( $data[$name] );
        }

        public function cleanUpUTF8() {
                array_walk_recursive( $this->mData, array( 'ApiResult', 'cleanUp_helper' ) );
        }

        private static function cleanUp_helper( &$s ) {
                if ( !is_string( $s ) ) {
                        return;
                }
                global $wgContLang;
                $s = $wgContLang->normalize( $s );
        }

        public function convertStatusToArray( $status, $errorType = 'error' ) {
                if ( $status->isGood() ) {
                        return array();
                }

                $result = array();
                foreach ( $status->getErrorsByType( $errorType ) as $error ) {
                        $this->setIndexedTagName( $error['params'], 'param' );
                        $result[] = $error;
                }
                $this->setIndexedTagName( $result, $errorType );
                return $result;
        }

        public function execute() {
                ApiBase::dieDebug( __METHOD__, 'execute() is not supported on Result object' );
        }
}