From 1c57794e371d74e1d88748de567a1c3358c3ad2e Mon Sep 17 00:00:00 2001 From: Brad Jorsch Date: Wed, 3 Dec 2014 17:14:22 -0500 Subject: 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 --- includes/api/ApiErrorFormatter.php | 303 +++++++++++++++++++++++++++++++++++++ 1 file changed, 303 insertions(+) create mode 100644 includes/api/ApiErrorFormatter.php (limited to 'includes/api/ApiErrorFormatter.php') 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 @@ +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 ); + } + } +} -- cgit v1.2.3