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' );
    }
}