ApiContinuationManager.php

Go to the documentation of this file.

<?php
namespace MediaWiki\Api;
 
use UnexpectedValueException;
 
class ApiContinuationManager {
    private $source;
 
    private $allModules = [];
    private $generatedModules;
 
    private $continuationData = [];
    private $generatorContinuationData = [];
    private $generatorNonContinuationData = [];
 
    private $generatorParams = [];
    private $generatorDone = false;
 
    public function __construct(
        ApiBase $module, array $allModules = [], array $generatedModules = []
    ) {
        $this->source = get_class( $module );
        $request = $module->getRequest();
 
        $this->generatedModules = $generatedModules
            ? array_combine( $generatedModules, $generatedModules )
            : [];
 
        $skip = [];
        $continue = $request->getVal( 'continue', '' );
        if ( $continue !== '' ) {
            $continue = explode( '||', $continue );
            if ( count( $continue ) !== 2 ) {
                throw ApiUsageException::newWithMessage( $module->getMain(), 'apierror-badcontinue' );
            }
            $this->generatorDone = ( $continue[0] === '-' );
            $skip = explode( '|', $continue[1] );
            if ( !$this->generatorDone ) {
                $params = explode( '|', $continue[0] );
                $this->generatorParams = array_intersect_key(
                    $request->getValues(),
                    array_fill_keys( $params, true )
                );
            } else {
                // When the generator is complete, don't run any modules that
                // depend on it.
                $skip += $this->generatedModules;
            }
        }
 
        foreach ( $allModules as $module ) {
            $name = $module->getModuleName();
            if ( in_array( $name, $skip, true ) ) {
                $this->allModules[$name] = false;
                // Prevent spurious "unused parameter" warnings
                $module->extractRequestParams();
            } else {
                $this->allModules[$name] = $module;
            }
        }
    }
 
    public function getSource() {
        return $this->source;
    }
 
    public function isGeneratorDone() {
        return $this->generatorDone;
    }
 
    public function getRunModules() {
        return array_values( array_filter( $this->allModules ) );
    }
 
    public function addContinueParam( ApiBase $module, $paramName, $paramValue ) {
        $name = $module->getModuleName();
        if ( !isset( $this->allModules[$name] ) ) {
            throw new UnexpectedValueException(
                "Module '$name' called " . __METHOD__ .
                    ' but was not passed to ' . __CLASS__ . '::__construct'
            );
        }
        if ( !$this->allModules[$name] ) {
            throw new UnexpectedValueException(
                "Module '$name' was not supposed to have been executed, but " .
                    'it was executed anyway'
            );
        }
        $paramName = $module->encodeParamName( $paramName );
        if ( is_array( $paramValue ) ) {
            $paramValue = implode( '|', $paramValue );
        }
        $this->continuationData[$name][$paramName] = $paramValue;
    }
 
    public function addGeneratorNonContinueParam( ApiBase $module, $paramName, $paramValue ) {
        $name = $module->getModuleName();
        $paramName = $module->encodeParamName( $paramName );
        if ( is_array( $paramValue ) ) {
            $paramValue = implode( '|', $paramValue );
        }
        $this->generatorNonContinuationData[$name][$paramName] = $paramValue;
    }
 
    public function addGeneratorContinueParam( ApiBase $module, $paramName, $paramValue ) {
        $name = $module->getModuleName();
        $paramName = $module->encodeParamName( $paramName );
        if ( is_array( $paramValue ) ) {
            $paramValue = implode( '|', $paramValue );
        }
        $this->generatorContinuationData[$name][$paramName] = $paramValue;
    }
 
    public function getRawContinuation() {
        return array_merge_recursive( $this->continuationData, $this->generatorContinuationData );
    }
 
    public function getRawNonContinuation() {
        return $this->generatorNonContinuationData;
    }
 
    public function getContinuation() {
        $data = [];
        $batchcomplete = false;
 
        $finishedModules = array_diff(
            array_keys( $this->allModules ),
            array_keys( $this->continuationData )
        );
 
        // First, grab the non-generator-using continuation data
        $continuationData = array_diff_key( $this->continuationData, $this->generatedModules );
        foreach ( $continuationData as $kvp ) {
            $data += $kvp;
        }
 
        // Next, handle the generator-using continuation data
        $continuationData = array_intersect_key( $this->continuationData, $this->generatedModules );
        if ( $continuationData ) {
            // Some modules are unfinished: include those params, and copy
            // the generator params.
            foreach ( $continuationData as $kvp ) {
                $data += $kvp;
            }
            $generatorParams = [];
            foreach ( $this->generatorNonContinuationData as $kvp ) {
                $generatorParams += $kvp;
            }
            $generatorParams += $this->generatorParams;
            // @phan-suppress-next-line PhanTypeInvalidLeftOperand False positive in phan
            $data += $generatorParams;
            $generatorKeys = implode( '|', array_keys( $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
            $generatorParams = [];
            foreach ( $this->generatorContinuationData as $kvp ) {
                $generatorParams += $kvp;
            }
            $data += $generatorParams;
            $finishedModules = array_diff( $finishedModules, $this->generatedModules );
            $generatorKeys = implode( '|', array_keys( $generatorParams ) );
            $batchcomplete = true;
        } else {
            // Generator and prop modules are all done. Mark it so.
            $generatorKeys = '-';
            $batchcomplete = true;
        }
 
        // Set 'continue' if any continuation data is set or if the generator
        // still needs to run
        if ( $data || $generatorKeys !== '-' ) {
            $data['continue'] = $generatorKeys . '||' . implode( '|', $finishedModules );
        }
 
        return [ $data, $batchcomplete ];
    }
 
    public function setContinuationIntoResult( ApiResult $result ) {
        [ $data, $batchcomplete ] = $this->getContinuation();
        if ( $data ) {
            $result->addValue( null, 'continue', $data,
                ApiResult::ADD_ON_TOP | ApiResult::NO_SIZE_CHECK );
        }
        if ( $batchcomplete ) {
            $result->addValue( null, 'batchcomplete', true,
                ApiResult::ADD_ON_TOP | ApiResult::NO_SIZE_CHECK );
        }
    }
}
 
class_alias( ApiContinuationManager::class, 'ApiContinuationManager' );