API: Overhaul ApiResult, make format=xml not throw, and add json formatversion

ApiResult was a mess: some methods could only be used with an array
reference instead of manipulating the stored data, methods that had both
array-ref and internal-data versions had names that didn't at all
correspond, some methods that worked on an array reference were
annoyingly non-static, and then the whole mess with setIndexedTagName.

ApiFormatXml is also entirely annoying to deal with, as it liked to
throw exceptions if certain metadata wasn't provided that no other
formatter required. Its legacy also means we have this silly convention
of using empty-string rather than boolean true, annoying restrictions on
keys (leading to things that should be hashes being arrays of key-value
object instead), '*' used as a key all over the place, and so on.

So, changes here:
* ApiResult is no longer an ApiBase or a ContextSource.
* Wherever sensible, ApiResult provides a static method working on an
  arrayref and a non-static method working on internal data.
* Metadata is now always added to ApiResult's internal data structure.
  Formatters are responsible for stripping it if necessary. "raw mode"
  is deprecated.
* New metadata to replace the '*' key, solve the array() => '[]' vs '{}'
  question, and so on.
* New class for formatting warnings and errors using i18n messages, and
  support for multiple errors and a more machine-readable format for
  warnings. For the moment, though, the actual output will not be changing
  yet (see T47843 for future plans).
* New formatversion parameter for format=json and format=php, to select
  between BC mode and the modern output.
* In BC mode, booleans will be converted to empty-string presence style;
  modules currently returning booleans will need to use
  ApiResult::META_BC_BOOLS to preserve their current output.

Actual changes to the API modules' output (e.g. actually returning
booleans for the new formatversion) beyond the use of
ApiResult::setContentValue() are left for a future change.

Bug: T76728
Bug: T57371
Bug: T33629
Change-Id: I7b37295e8862b188d1f3b0cd07f66ac34629678f

1 files changed, 303 insertions, 0 deletions

diff --git a/includes/api/ApiErrorFormatter.php b/includes/api/ApiErrorFormatter.php
new file mode 100644
index 000000000000..9414329102c6
--- /dev/null
+++ b/includes/api/ApiErrorFormatter.php
@@ -0,0 +1,303 @@
+<?php
+/**
+ * This file contains the ApiErrorFormatter definition, plus implementations of
+ * specific formatters.
+ *
+ * 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
+ */
+
+/**
+ * Formats errors and warnings for the API, and add them to the associated
+ * ApiResult.
+ * @since 1.25
+ * @ingroup API
+ */
+class ApiErrorFormatter {
+	/** @var Title Dummy title to silence warnings from MessageCache::parse() */
+	private static $dummyTitle = null;
+
+	/** @var ApiResult */
+	protected $result;
+
+	/** @var Language */
+	protected $lang;
+	protected $useDB = false;
+	protected $format = 'none';
+
+	/**
+	 * @param ApiResult $result Into which data will be added
+	 * @param Language $lang Used for i18n
+	 * @param string $format
+	 *  - text: Error message as wikitext
+	 *  - html: Error message as HTML
+	 *  - raw: Raw message key and parameters, no human-readable text
+	 *  - none: Code and data only, no human-readable text
+	 * @param bool $useDB Whether to use local translations for errors and warnings.
+	 */
+	public function __construct( ApiResult $result, Language $lang, $format, $useDB = false ) {
+		$this->result = $result;
+		$this->lang = $lang;
+		$this->useDB = $useDB;
+		$this->format = $format;
+	}
+
+	/**
+	 * Fetch a dummy title to set on Messages
+	 * @return Title
+	 */
+	protected function getDummyTitle() {
+		if ( self::$dummyTitle === null ) {
+			self::$dummyTitle = Title::makeTitle( NS_SPECIAL, 'Badtitle/' . __METHOD__ );
+		}
+		return self::$dummyTitle;
+	}
+
+	/**
+	 * Add a warning to the result
+	 * @param string $moduleName
+	 * @param MessageSpecifier|array|string $msg i18n message for the warning
+	 * @param string $code Machine-readable code for the warning. Defaults as
+	 *   for IApiMessage::getApiCode().
+	 * @param array $data Machine-readable data for the warning, if any.
+	 *   Uses IApiMessage::getApiData() if $msg implements that interface.
+	 */
+	public function addWarning( $moduleName, $msg, $code = null, $data = null ) {
+		$msg = ApiMessage::create( $msg, $code, $data )
+			->inLanguage( $this->lang )
+			->title( $this->getDummyTitle() )
+			->useDatabase( $this->useDB );
+		$this->addWarningOrError( 'warning', $moduleName, $msg );
+	}
+
+	/**
+	 * Add an error to the result
+	 * @param string $moduleName
+	 * @param MessageSpecifier|array|string $msg i18n message for the error
+	 * @param string $code Machine-readable code for the warning. Defaults as
+	 *   for IApiMessage::getApiCode().
+	 * @param array $data Machine-readable data for the warning, if any.
+	 *   Uses IApiMessage::getApiData() if $msg implements that interface.
+	 */
+	public function addError( $moduleName, $msg, $code = null, $data = null ) {
+		$msg = ApiMessage::create( $msg, $code, $data )
+			->inLanguage( $this->lang )
+			->title( $this->getDummyTitle() )
+			->useDatabase( $this->useDB );
+		$this->addWarningOrError( 'error', $moduleName, $msg );
+	}
+
+	/**
+	 * Add warnings and errors from a Status object to the result
+	 * @param string $moduleName
+	 * @param Status $status
+	 * @param string[] $types 'warning' and/or 'error'
+	 */
+	public function addMessagesFromStatus(
+		$moduleName, Status $status, $types = array( 'warning', 'error' )
+	) {
+		if ( $status->isGood() || !$status->errors ) {
+			return;
+		}
+
+		$types = (array)$types;
+		foreach ( $status->errors as $error ) {
+			if ( !in_array( $error['type'], $types, true ) ) {
+				continue;
+			}
+
+			if ( $error['type'] === 'error' ) {
+				$tag = 'error';
+			} else {
+				// Assume any unknown type is a warning
+				$tag = 'warning';
+			}
+
+			if ( is_array( $error ) && isset( $error['message'] ) ) {
+				// Normal case
+				if ( $error['message'] instanceof Message ) {
+					$msg = ApiMessage::create( $error['message'], null, array() );
+				} else {
+					$args = isset( $error['params'] ) ? $error['params'] : array();
+					array_unshift( $args, $error['message'] );
+					$error += array( 'params' => array() );
+					$msg = ApiMessage::create( $args, null, array() );
+				}
+			} elseif ( is_array( $error ) ) {
+				// Weird case handled by Message::getErrorMessage
+				$msg = ApiMessage::create( $error, null, array() );
+			} else {
+				// Another weird case handled by Message::getErrorMessage
+				$msg = ApiMessage::create( $error, null, array() );
+			}
+
+			$msg->inLanguage( $this->lang )
+				->title( $this->getDummyTitle() )
+				->useDatabase( $this->useDB );
+			$this->addWarningOrError( $tag, $moduleName, $msg );
+		}
+	}
+
+	/**
+	 * Format messages from a Status as an array
+	 * @param Status $status
+	 * @param string $type 'warning' or 'error'
+	 * @param string|null $format
+	 * @return array
+	 */
+	public function arrayFromStatus( Status $status, $type = 'error', $format = null ) {
+		if ( $status->isGood() || !$status->errors ) {
+			return array();
+		}
+
+		$result = new ApiResult( 1e6 );
+		$formatter = new ApiErrorFormatter(
+			$result, $this->lang, $format ?: $this->format, $this->useDB
+		);
+		$formatter->addMessagesFromStatus( 'dummy', $status, array( $type ) );
+		switch ( $type ) {
+			case 'error':
+				return (array)$result->getResultData( array( 'errors', 'dummy' ) );
+			case 'warning':
+				return (array)$result->getResultData( array( 'warnings', 'dummy' ) );
+		}
+	}
+
+	/**
+	 * Actually add the warning or error to the result
+	 * @param string $tag 'warning' or 'error'
+	 * @param string $moduleName
+	 * @param ApiMessage|ApiRawMessage $msg
+	 */
+	protected function addWarningOrError( $tag, $moduleName, $msg ) {
+		$value = array( 'code' => $msg->getApiCode() );
+		switch ( $this->format ) {
+			case 'wikitext':
+				$value += array(
+					'text' => $msg->text(),
+					ApiResult::META_CONTENT => 'text',
+				);
+				break;
+
+			case 'html':
+				$value += array(
+					'html' => $msg->parse(),
+					ApiResult::META_CONTENT => 'html',
+				);
+				break;
+
+			case 'raw':
+				$value += array(
+					'message' => $msg->getKey(),
+					'params' => $msg->getParams(),
+				);
+				ApiResult::setIndexedTagName( $value['params'], 'param' );
+				break;
+
+			case 'none':
+				break;
+		}
+		$value += $msg->getApiData();
+
+		$path = array( $tag . 's', $moduleName );
+		$existing = $this->result->getResultData( $path );
+		if ( $existing === null || !in_array( $value, $existing ) ) {
+			$flags = ApiResult::NO_SIZE_CHECK;
+			if ( $existing === null ) {
+				$flags |= ApiResult::ADD_ON_TOP;
+			}
+			$this->result->addValue( $path, null, $value, $flags );
+			$this->result->addIndexedTagName( $path, $tag );
+		}
+	}
+}
+
+/**
+ * Format errors and warnings in the old style, for backwards compatibility.
+ * @since 1.25
+ * @deprecated Only for backwards compatibility, do not use
+ * @ingroup API
+ */
+class ApiErrorFormatter_BackCompat extends ApiErrorFormatter {
+	/**
+	 * @param ApiResult $result Into which data will be added
+	 */
+	public function __construct( ApiResult $result ) {
+		parent::__construct( $result, Language::factory( 'en' ), 'none', false );
+	}
+
+	public function arrayFromStatus( Status $status, $type = 'error', $format = null ) {
+		if ( $status->isGood() || !$status->errors ) {
+			return array();
+		}
+
+		$result = array();
+		foreach ( $status->getErrorsByType( $type ) as $error ) {
+			if ( $error['message'] instanceof Message ) {
+				$error = array(
+					'message' => $error['message']->getKey(),
+					'params' => $error['message']->getParams(),
+				) + $error;
+			}
+			ApiResult::setIndexedTagName( $error['params'], 'param' );
+			$result[] = $error;
+		}
+		ApiResult::setIndexedTagName( $result, $type );
+
+		return $result;
+	}
+
+	protected function addWarningOrError( $tag, $moduleName, $msg ) {
+		$value = $msg->plain();
+
+		if ( $tag === 'error' ) {
+			// In BC mode, only one error
+			$code = $msg->getApiCode();
+			if ( isset( ApiBase::$messageMap[$code] ) ) {
+				// Backwards compatibility
+				$code = ApiBase::$messageMap[$code]['code'];
+			}
+
+			$value = array(
+				'code' => $code,
+				'info' => $value,
+			) + $msg->getApiData();
+			$this->result->addValue( null, 'error', $value,
+				ApiResult::OVERRIDE | ApiResult::ADD_ON_TOP | ApiResult::NO_SIZE_CHECK );
+		} else {
+			// Don't add duplicate warnings
+			$tag .= 's';
+			$path = array( $tag, $moduleName );
+			$oldWarning = $this->result->getResultData( array( $tag, $moduleName, $tag ) );
+			if ( $oldWarning !== null ) {
+				$warnPos = strpos( $oldWarning, $value );
+				// If $value was found in $oldWarning, check if it starts at 0 or after "\n"
+				if ( $warnPos !== false && ( $warnPos === 0 || $oldWarning[$warnPos - 1] === "\n" ) ) {
+					// Check if $value is followed by "\n" or the end of the $oldWarning
+					$warnPos += strlen( $value );
+					if ( strlen( $oldWarning ) <= $warnPos || $oldWarning[$warnPos] === "\n" ) {
+						return;
+					}
+				}
+				// If there is a warning already, append it to the existing one
+				$value = "$oldWarning\n$value";
+			}
+			$this->result->addContentValue( $path, $tag, $value,
+				ApiResult::OVERRIDE | ApiResult::ADD_ON_TOP | ApiResult::NO_SIZE_CHECK );
+		}
+	}
+}