ResponseFactory.php

Go to the documentation of this file.

<?php
 
namespace MediaWiki\Rest;
 
use HttpStatus;
use InvalidArgumentException;
use LanguageCode;
use MWExceptionHandler;
use stdClass;
use Throwable;
use Wikimedia\Message\ITextFormatter;
use Wikimedia\Message\MessageValue;
 
class ResponseFactory {
    private const CT_PLAIN = 'text/plain; charset=utf-8';
    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->createRedirectBase( $target );
        $response->setStatus( 301 );
        return $response;
    }
 
    public function createLegacyTemporaryRedirect( $target ) {
        $response = $this->createRedirectBase( $target );
        $response->setStatus( 302 );
        return $response;
    }
 
    public function createTemporaryRedirect( $target ) {
        $response = $this->createRedirectBase( $target );
        $response->setStatus( 307 );
        return $response;
    }
 
    public function createSeeOther( $target ) {
        $response = $this->createRedirectBase( $target );
        $response->setStatus( 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 ) {
        if ( $exception instanceof LocalizedHttpException ) {
            $response = $this->createLocalizedHttpError(
                $exception->getCode(),
                $exception->getMessageValue(),
                (array)$exception->getErrorData()
            );
        } elseif ( $exception instanceof ResponseException ) {
            return $exception->getResponse();
        } elseif ( $exception instanceof RedirectException ) {
            $response = $this->createRedirectBase( $exception->getTarget() );
            $response->setStatus( $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() ],
                        (array)$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 = gettype( $originalValue );
            if ( $type === 'object' ) {
                $type = get_class( $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 ) {
        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 ];
    }
 
}