wiki.techinc.nl/includes/api/ApiContinuationManager.php

<?php
/**
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 * http://www.gnu.org/copyleft/gpl.html
 *
 * @file
 */

/**
 * This manages continuation state.
 * @since 1.25 this is no longer a subclass of ApiBase
 * @ingroup API
 */
class ApiContinuationManager {
	/** @var string */
	private $source;

	/** @var (ApiBase|false)[] */
	private $allModules = [];
	/** @var string[] */
	private $generatedModules;

	/** @var array[] */
	private $continuationData = [];
	/** @var array[] */
	private $generatorContinuationData = [];
	/** @var array[] */
	private $generatorNonContinuationData = [];

	/** @var array */
	private $generatorParams = [];
	/** @var bool */
	private $generatorDone = false;

	/**
	 * @param ApiBase $module Module starting the continuation
	 * @param ApiBase[] $allModules Contains ApiBase instances that will be executed
	 * @param string[] $generatedModules Names of modules that depend on the generator
	 * @throws ApiUsageException
	 */
	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;
			}
		}
	}

	/**
	 * Get the class that created this manager
	 * @return string
	 */
	public function getSource() {
		return $this->source;
	}

	/**
	 * @return bool
	 */
	public function isGeneratorDone() {
		return $this->generatorDone;
	}

	/**
	 * Get the list of modules that should actually be run
	 * @return ApiBase[]
	 */
	public function getRunModules() {
		return array_values( array_filter( $this->allModules ) );
	}

	/**
	 * Set the continuation parameter for a module
	 * @param ApiBase $module
	 * @param string $paramName
	 * @param string|array $paramValue
	 * @throws UnexpectedValueException
	 */
	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;
	}

	/**
	 * Set the non-continuation parameter for the generator module
	 *
	 * In case the generator isn't going to be continued, this sets the fields
	 * to return.
	 *
	 * @since 1.28
	 * @param ApiBase $module
	 * @param string $paramName
	 * @param string|array $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;
	}

	/**
	 * Set the continuation parameter for the generator module
	 * @param ApiBase $module
	 * @param string $paramName
	 * @param int|string|array $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;
	}

	/**
	 * Fetch raw continuation data
	 * @return array[]
	 */
	public function getRawContinuation() {
		return array_merge_recursive( $this->continuationData, $this->generatorContinuationData );
	}

	/**
	 * Fetch raw non-continuation data
	 * @since 1.28
	 * @return array[]
	 */
	public function getRawNonContinuation() {
		return $this->generatorNonContinuationData;
	}

	/**
	 * Fetch continuation result data
	 * @return array [ (array)$data, (bool)$batchcomplete ]
	 */
	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 $module => $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 $module => $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 ];
	}

	/**
	 * Store the continuation data into the result
	 * @param ApiResult $result
	 */
	public function setContinuationIntoResult( ApiResult $result ) {
		list( $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 );
		}
	}
}