ResponseFactory.php

Go to the documentation of this file.

<?php
 
namespace MediaWiki\Rest;
 
use InvalidArgumentException;
use MediaWiki\Exception\MWExceptionHandler;
use MediaWiki\Language\LanguageCode;
use stdClass;
use Throwable;
use Wikimedia\Http\HttpStatus;
use Wikimedia\Message\ITextFormatter;
use Wikimedia\Message\MessageValue;
 
class ResponseFactory {
    private const CT_HTML = 'text/html; charset=utf-8';
    private const CT_JSON = 'application/json';
 
    private $textFormatters;
 
    private $showExceptionDetails = false;
 
    public function __construct( $textFormatters ) {
        $this->textFormatters = $textFormatters;
    }
 
    public function setShowExceptionDetails( bool $showExceptionDetails ): void {
        $this->showExceptionDetails = $showExceptionDetails;
    }
 
    public function encodeJson( $value ) {
        $json = json_encode( $value,
            JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_INVALID_UTF8_SUBSTITUTE );
        if ( $json === false ) {
            throw new JsonEncodingException( json_last_error_msg(), json_last_error() );
        }
        return $json;
    }
 
    public function create() {
        return new Response();
    }
 
    public function createJson( $value, $contentType = null ) {
        $contentType ??= self::CT_JSON;
        $response = new Response( $this->encodeJson( $value ) );
        $response->setHeader( 'Content-Type', $contentType );
        return $response;
    }
 
    public function createNoContent() {
        $response = new Response();
        $response->setStatus( 204 );
        return $response;
    }
 
    public function createPermanentRedirect( $target ) {
        $response = $this->createRedirect( $target, 301 );
        return $response;
    }
 
    public function createLegacyTemporaryRedirect( $target ) {
        $response = $this->createRedirect( $target, 302 );
        return $response;
    }
 
    public function createRedirect( $target, $code ) {
        $response = $this->createRedirectBase( $target );
        $response->setStatus( $code );
        return $response;
    }
 
    public function createTemporaryRedirect( $target ) {
        $response = $this->createRedirect( $target, 307 );
        return $response;
    }
 
    public function createSeeOther( $target ) {
        $response = $this->createRedirect( $target, 303 );
        return $response;
    }
 
    public function createNotModified() {
        $response = new Response();
        $response->setStatus( 304 );
        return $response;
    }
 
    public function createHttpError( $errorCode, array $bodyData = [] ) {
        if ( $errorCode < 400 || $errorCode >= 600 ) {
            throw new InvalidArgumentException( 'error code must be 4xx or 5xx' );
        }
        $response = $this->createJson( $bodyData + [
            'httpCode' => $errorCode,
            'httpReason' => HttpStatus::getMessage( $errorCode )
        ] );
        // TODO add link to error code documentation
        $response->setStatus( $errorCode );
        return $response;
    }
 
    public function createLocalizedHttpError(
        $errorCode,
        MessageValue $messageValue,
        array $extraData = []
    ) {
        return $this->createHttpError(
            $errorCode,
            array_merge( $extraData, $this->formatMessage( $messageValue ) )
        );
    }
 
    public function createFromException( Throwable $exception, array $extraData = [] ) {
        if ( $exception instanceof LocalizedHttpException ) {
            $response = $this->createLocalizedHttpError(
                $exception->getCode(),
                $exception->getMessageValue(),
                $exception->getErrorData() + $extraData + [
                    'errorKey' => $exception->getErrorKey(),
                ]
            );
        } elseif ( $exception instanceof ResponseException ) {
            return $exception->getResponse();
        } elseif ( $exception instanceof RedirectException ) {
            $response = $this->createRedirect( $exception->getTarget(), $exception->getCode() );
        } elseif ( $exception instanceof HttpException ) {
            if ( in_array( $exception->getCode(), [ 204, 304 ], true ) ) {
                $response = $this->create();
                $response->setStatus( $exception->getCode() );
            } else {
                $response = $this->createHttpError(
                    $exception->getCode(),
                    array_merge(
                        [ 'message' => $exception->getMessage() ],
                        $exception->getErrorData()
                    )
                );
            }
        } elseif ( $this->showExceptionDetails ) {
            $response = $this->createHttpError( 500, [
                'message' => 'Error: exception of type ' . get_class( $exception ) . ': '
                    . $exception->getMessage(),
                'exception' => MWExceptionHandler::getStructuredExceptionData(
                    $exception,
                    MWExceptionHandler::CAUGHT_BY_OTHER
                )
            ] );
            // XXX: should we try to do something useful with ILocalizedException?
            // XXX: should we try to do something useful with common MediaWiki errors like ReadOnlyError?
        } else {
            $response = $this->createHttpError( 500, [
                'message' => 'Error: exception of type ' . get_class( $exception ),
            ] );
        }
        return $response;
    }
 
    public function createFromReturnValue( $value ) {
        $originalValue = $value;
        if ( is_scalar( $value ) ) {
            $data = [ 'value' => $value ];
        } elseif ( is_array( $value ) || $value instanceof stdClass ) {
            $data = $value;
        } else {
            $type = get_debug_type( $originalValue );
            throw new InvalidArgumentException( __METHOD__ . ": Invalid return value type $type" );
        }
        $response = $this->createJson( $data );
        return $response;
    }
 
    protected function createRedirectBase( $target ) {
        $response = new Response( $this->getHyperLink( $target ) );
        $response->setHeader( 'Content-Type', self::CT_HTML );
        $response->setHeader( 'Location', $target );
        return $response;
    }
 
    protected function getHyperLink( $url ) {
        $url = htmlspecialchars( $url, ENT_COMPAT );
        return "<!doctype html><title>Redirect</title><a href=\"$url\">$url</a>";
    }
 
    public function formatMessage( MessageValue $messageValue ): array {
        if ( !$this->textFormatters ) {
            // For unit tests
            return [];
        }
        $translations = [];
        foreach ( $this->textFormatters as $formatter ) {
            $lang = LanguageCode::bcp47( $formatter->getLangCode() );
            $messageText = $formatter->format( $messageValue );
            $translations[$lang] = $messageText;
        }
        return [ 'messageTranslations' => $translations ];
    }
 
    public function getFormattedMessage(
        MessageValue $messageValue, string $preferredlang = ''
    ): string {
        $strings = $this->formatMessage( $messageValue );
        if ( !$strings ) {
            return $messageValue->getKey();
        }
 
        $strings = $strings['messageTranslations'];
        if ( $preferredlang && array_key_exists( $preferredlang, $strings ) ) {
            return $strings[ $preferredlang ];
        } else {
            return reset( $strings );
        }
    }
 
    public static function getResponseComponents(): array {
        return [
            'responses' => [
                'GenericErrorResponse' => [
                    'description' => 'Generic error response',
                    'content' => [
                        'application/json' => [
                            'schema' => [
                                '$ref' => '#/components/schemas/GenericErrorResponseModel'
                            ]
                        ],
                    ],
                ]
            ],
            'schemas' => [
                'GenericErrorResponseModel' => [
                    'description' => 'Generic error response body',
                    'required' => [ 'httpCode' ],
                    'properties' => [
                        'httpCode' => [
                            'type' => 'integer'
                        ],
                        'httpMessage' => [
                            'type' => 'string'
                        ],
                        'message' => [
                            'type' => 'string'
                        ],
                        'messageTranslations' => [
                            'type' => 'object',
                            'additionalProperties' => [
                                'type' => 'string'
                            ]
                        ],
                    ]
                ]
            ],
        ];
    }
 
}