ApiResult.php

Go to the documentation of this file.

<?php
class ApiResult extends ApiBase {

    const OVERRIDE = 1;

    const ADD_ON_TOP = 2;

    const NO_SIZE_CHECK = 4;

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

    private $continueAllModules = array();
    private $continueGeneratedModules = array();
    private $continuationData = array();
    private $generatorContinuationData = array();
    private $generatorParams = array();
    private $generatorDone = false;

    public function __construct( ApiMain $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( $flag = true ) {
        $this->mIsRawMode = $flag;
    }

    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 setSubelements( &$arr, $names ) {
        // In raw mode, add the '_subelements', otherwise just ignore
        if ( !$this->getIsRawMode() ) {
            return;
        }
        if ( $arr === null || $names === null || !is_array( $arr ) ) {
            ApiBase::dieDebug( __METHOD__, 'Bad parameter' );
        }
        if ( !is_array( $names ) ) {
            $names = array( $names );
        }
        if ( !isset( $arr['_subelements'] ) ) {
            $arr['_subelements'] = $names;
        } else {
            $arr['_subelements'] = array_merge( $arr['_subelements'], $names );
        }
    }

    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 ) {
        $data = &$this->mData;
        if ( $this->mCheckingSize && !( $flags & ApiResult::NO_SIZE_CHECK ) ) {
            $newsize = $this->mSize + self::size( $value );
            $maxResultSize = $this->getConfig()->get( 'APIMaxResultSize' );
            if ( $newsize > $maxResultSize ) {
                $this->setWarning(
                    "This result was truncated because it would otherwise be larger than the " .
                        "limit of {$maxResultSize} 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' );
    }

    public function beginContinuation(
        $continue, array $allModules = array(), array $generatedModules = array()
    ) {
        $this->continueGeneratedModules = $generatedModules
            ? array_combine( $generatedModules, $generatedModules )
            : array();
        $this->continuationData = array();
        $this->generatorContinuationData = array();
        $this->generatorParams = array();

        $skip = array();
        if ( is_string( $continue ) && $continue !== '' ) {
            $continue = explode( '||', $continue );
            $this->dieContinueUsageIf( count( $continue ) !== 2 );
            $this->generatorDone = ( $continue[0] === '-' );
            if ( !$this->generatorDone ) {
                $this->generatorParams = explode( '|', $continue[0] );
            }
            $skip = explode( '|', $continue[1] );
        }

        $this->continueAllModules = array();
        $runModules = array();
        foreach ( $allModules as $module ) {
            $name = $module->getModuleName();
            if ( in_array( $name, $skip ) ) {
                $this->continueAllModules[$name] = false;
                // Prevent spurious "unused parameter" warnings
                $module->extractRequestParams();
            } else {
                $this->continueAllModules[$name] = true;
                $runModules[] = $module;
            }
        }

        return array(
            $this->generatorDone,
            $runModules,
        );
    }

    public function setContinueParam( ApiBase $module, $paramName, $paramValue ) {
        $name = $module->getModuleName();
        if ( !isset( $this->continueAllModules[$name] ) ) {
            throw new MWException(
                "Module '$name' called ApiResult::setContinueParam but was not " .
                'passed to ApiResult::beginContinuation'
            );
        }
        if ( !$this->continueAllModules[$name] ) {
            throw new MWException(
                "Module '$name' was not supposed to have been executed, but " .
                'it was executed anyway'
            );
        }
        $paramName = $module->encodeParamName( $paramName );
        if ( is_array( $paramValue ) ) {
            $paramValue = join( '|', $paramValue );
        }
        $this->continuationData[$name][$paramName] = $paramValue;
    }

    public function setGeneratorContinueParam( ApiBase $module, $paramName, $paramValue ) {
        $name = $module->getModuleName();
        $paramName = $module->encodeParamName( $paramName );
        if ( is_array( $paramValue ) ) {
            $paramValue = join( '|', $paramValue );
        }
        $this->generatorContinuationData[$name][$paramName] = $paramValue;
    }

    public function endContinuation( $style = 'standard' ) {
        if ( $style === 'raw' ) {
            $key = 'query-continue';
            $data = array_merge_recursive(
                $this->continuationData, $this->generatorContinuationData
            );
        } else {
            $key = 'continue';
            $data = array();

            $finishedModules = array_diff(
                array_keys( $this->continueAllModules ),
                array_keys( $this->continuationData )
            );

            // First, grab the non-generator-using continuation data
            $continuationData = array_diff_key(
                $this->continuationData, $this->continueGeneratedModules
            );
            foreach ( $continuationData as $module => $kvp ) {
                $data += $kvp;
            }

            // Next, handle the generator-using continuation data
            $continuationData = array_intersect_key(
                $this->continuationData, $this->continueGeneratedModules
            );
            if ( $continuationData ) {
                // Some modules are unfinished: include those params, and copy
                // the generator params.
                foreach ( $continuationData as $module => $kvp ) {
                    $data += $kvp;
                }
                $data += array_intersect_key(
                    $this->getMain()->getRequest()->getValues(),
                    array_flip( $this->generatorParams )
                );
            } elseif ( $this->generatorContinuationData ) {
                // All the generator-using modules are complete, but the
                // generator isn't. Continue the generator and restart the
                // generator-using modules
                $this->generatorParams = array();
                foreach ( $this->generatorContinuationData as $kvp ) {
                    $this->generatorParams = array_merge(
                        $this->generatorParams, array_keys( $kvp )
                    );
                    $data += $kvp;
                }
                $finishedModules = array_diff(
                    $finishedModules, $this->continueGeneratedModules
                );
            } else {
                // Generator and prop modules are all done. Mark it so.
                $this->generatorDone = true;
            }

            // Set 'continue' if any continuation data is set or if the generator
            // still needs to run
            if ( $data || !$this->generatorDone ) {
                $data['continue'] =
                    ( $this->generatorDone ? '-' : join( '|', $this->generatorParams ) ) .
                    '||' . join( '|', $finishedModules );
            }
        }
        if ( $data ) {
            $this->addValue( null, $key, $data, ApiResult::ADD_ON_TOP | ApiResult::NO_SIZE_CHECK );
        }
    }
}