ApiFormatBase.php

Go to the documentation of this file.

<?php
abstract class ApiFormatBase extends ApiBase {
    private $mIsHtml, $mFormat, $mUnescapeAmps, $mHelp;
    private $mBuffer, $mDisabled = false;
    private $mIsWrappedHtml = false;
    protected $mForceDefaultParams = false;

    public function __construct( ApiMain $main, $format ) {
        parent::__construct( $main, $format );

        $this->mIsHtml = ( substr( $format, -2, 2 ) === 'fm' ); // ends with 'fm'
        if ( $this->mIsHtml ) {
            $this->mFormat = substr( $format, 0, -2 ); // remove ending 'fm'
            $this->mIsWrappedHtml = $this->getMain()->getCheck( 'wrappedhtml' );
        } else {
            $this->mFormat = $format;
        }
        $this->mFormat = strtoupper( $this->mFormat );
    }

    abstract public function getMimeType();

    public function getFilename() {
        if ( $this->getIsWrappedHtml() ) {
            return 'api-result-wrapped.json';
        } elseif ( $this->getIsHtml() ) {
            return 'api-result.html';
        } else {
            $exts = MimeMagic::singleton()->getExtensionsForType( $this->getMimeType() );
            $ext = $exts ? strtok( $exts, ' ' ) : strtolower( $this->mFormat );
            return "api-result.$ext";
        }
    }

    public function getFormat() {
        return $this->mFormat;
    }

    public function getIsHtml() {
        return $this->mIsHtml;
    }

    protected function getIsWrappedHtml() {
        return $this->mIsWrappedHtml;
    }

    public function disable() {
        $this->mDisabled = true;
    }

    public function isDisabled() {
        return $this->mDisabled;
    }

    public function canPrintErrors() {
        return true;
    }

    public function forceDefaultParams() {
        $this->mForceDefaultParams = true;
    }

    protected function getParameterFromSettings( $paramName, $paramSettings, $parseLimit ) {
        if ( !$this->mForceDefaultParams ) {
            return parent::getParameterFromSettings( $paramName, $paramSettings, $parseLimit );
        }

        if ( !is_array( $paramSettings ) ) {
            return $paramSettings;
        } elseif ( isset( $paramSettings[self::PARAM_DFLT] ) ) {
            return $paramSettings[self::PARAM_DFLT];
        } else {
            return null;
        }
    }

    public function initPrinter( $unused = false ) {
        if ( $this->mDisabled ) {
            return;
        }

        $mime = $this->getIsWrappedHtml()
            ? 'text/mediawiki-api-prettyprint-wrapped'
            : ( $this->getIsHtml() ? 'text/html' : $this->getMimeType() );

        // Some printers (ex. Feed) do their own header settings,
        // in which case $mime will be set to null
        if ( $mime === null ) {
            return; // skip any initialization
        }

        $this->getMain()->getRequest()->response()->header( "Content-Type: $mime; charset=utf-8" );

        // Set X-Frame-Options API results (bug 39180)
        $apiFrameOptions = $this->getConfig()->get( 'ApiFrameOptions' );
        if ( $apiFrameOptions ) {
            $this->getMain()->getRequest()->response()->header( "X-Frame-Options: $apiFrameOptions" );
        }

        // Set a Content-Disposition header so something downloading an API
        // response uses a halfway-sensible filename (T128209).
        $filename = $this->getFilename();
        $this->getMain()->getRequest()->response()->header(
            "Content-Disposition: inline; filename=\"{$filename}\""
        );
    }

    public function closePrinter() {
        if ( $this->mDisabled ) {
            return;
        }

        $mime = $this->getMimeType();
        if ( $this->getIsHtml() && $mime !== null ) {
            $format = $this->getFormat();
            $lcformat = strtolower( $format );
            $result = $this->getBuffer();

            $context = new DerivativeContext( $this->getMain() );
            $context->setSkin( SkinFactory::getDefaultInstance()->makeSkin( 'apioutput' ) );
            $context->setTitle( SpecialPage::getTitleFor( 'ApiHelp' ) );
            $out = new OutputPage( $context );
            $context->setOutput( $out );

            $out->addModuleStyles( 'mediawiki.apipretty' );
            $out->setPageTitle( $context->msg( 'api-format-title' ) );

            if ( !$this->getIsWrappedHtml() ) {
                // When the format without suffix 'fm' is defined, there is a non-html version
                if ( $this->getMain()->getModuleManager()->isDefined( $lcformat, 'format' ) ) {
                    $msg = $context->msg( 'api-format-prettyprint-header' )->params( $format, $lcformat );
                } else {
                    $msg = $context->msg( 'api-format-prettyprint-header-only-html' )->params( $format );
                }

                $header = $msg->parseAsBlock();
                $out->addHTML(
                    Html::rawElement( 'div', [ 'class' => 'api-pretty-header' ],
                        ApiHelp::fixHelpLinks( $header )
                    )
                );
            }

            if ( Hooks::run( 'ApiFormatHighlight', [ $context, $result, $mime, $format ] ) ) {
                $out->addHTML(
                    Html::element( 'pre', [ 'class' => 'api-pretty-content' ], $result )
                );
            }

            if ( $this->getIsWrappedHtml() ) {
                // This is a special output mode mainly intended for ApiSandbox use
                $time = microtime( true ) - $this->getConfig()->get( 'RequestTime' );
                $json = FormatJson::encode(
                    [
                        'html' => $out->getHTML(),
                        'modules' => array_values( array_unique( array_merge(
                            $out->getModules(),
                            $out->getModuleScripts(),
                            $out->getModuleStyles()
                        ) ) ),
                        'time' => round( $time * 1000 ),
                    ],
                    false, FormatJson::ALL_OK
                );

                // Bug 66776: wfMangleFlashPolicy() is needed to avoid a nasty bug in
                // Flash, but what it does isn't friendly for the API, so we need to
                // work around it.
                if ( preg_match( '/<\s*cross-domain-policy\s*>/i', $json ) ) {
                    $json = preg_replace(
                        '/<(\s*cross-domain-policy\s*)>/i', '\\u003C$1\\u003E', $json
                    );
                }

                echo $json;
            } else {
                // API handles its own clickjacking protection.
                // Note, that $wgBreakFrames will still override $wgApiFrameOptions for format mode.
                $out->allowClickjacking();
                $out->output();
            }
        } else {
            // For non-HTML output, clear all errors that might have been
            // displayed if display_errors=On
            ob_clean();

            echo $this->getBuffer();
        }
    }

    public function printText( $text ) {
        $this->mBuffer .= $text;
    }

    public function getBuffer() {
        return $this->mBuffer;
    }

    public function getAllowedParams() {
        $ret = [];
        if ( $this->getIsHtml() ) {
            $ret['wrappedhtml'] = [
                ApiBase::PARAM_DFLT => false,
                ApiBase::PARAM_HELP_MSG => 'apihelp-format-param-wrappedhtml',

            ];
        }
        return $ret;
    }

    protected function getExamplesMessages() {
        return [
            'action=query&meta=siteinfo&siprop=namespaces&format=' . $this->getModuleName()
                => [ 'apihelp-format-example-generic', $this->getFormat() ]
        ];
    }

    public function getHelpUrls() {
        return 'https://www.mediawiki.org/wiki/API:Data_formats';
    }

    /************************************************************************/
    public function setUnescapeAmps( $b ) {
        wfDeprecated( __METHOD__, '1.25' );
        $this->mUnescapeAmps = $b;
    }

    public function getWantsHelp() {
        wfDeprecated( __METHOD__, '1.25' );
        return $this->getIsHtml();
    }

    public function setHelp( $help = true ) {
        wfDeprecated( __METHOD__, '1.25' );
        $this->mHelp = $help;
    }

    protected function formatHTML( $text ) {
        wfDeprecated( __METHOD__, '1.25' );

        // Escape everything first for full coverage
        $text = htmlspecialchars( $text );

        if ( $this->mFormat === 'XML' ) {
            // encode all comments or tags as safe blue strings
            $text = str_replace( '&lt;', '<span style="color:blue;">&lt;', $text );
            $text = str_replace( '&gt;', '&gt;</span>', $text );
        }

        // identify requests to api.php
        $text = preg_replace( '#^(\s*)(api\.php\?[^ <\n\t]+)$#m', '\1<a href="\2">\2</a>', $text );
        if ( $this->mHelp ) {
            // make lines inside * bold
            $text = preg_replace( '#^(\s*)(\*[^<>\n]+\*)(\s*)$#m', '$1<b>$2</b>$3', $text );
        }

        // Armor links (bug 61362)
        $masked = [];
        $text = preg_replace_callback( '#<a .*?</a>#', function ( $matches ) use ( &$masked ) {
            $sha = sha1( $matches[0] );
            $masked[$sha] = $matches[0];
            return "<$sha>";
        }, $text );

        // identify URLs
        $protos = wfUrlProtocolsWithoutProtRel();
        // This regex hacks around bug 13218 (&quot; included in the URL)
        $text = preg_replace(
            "#(((?i)$protos).*?)(&quot;)?([ \\'\"<>\n]|&lt;|&gt;|&quot;)#",
            '<a href="\\1">\\1</a>\\3\\4',
            $text
        );

        // Unarmor links
        $text = preg_replace_callback( '#<([0-9a-f]{40})>#', function ( $matches ) use ( &$masked ) {
            $sha = $matches[1];
            return isset( $masked[$sha] ) ? $masked[$sha] : $matches[0];
        }, $text );

        if ( $this->mUnescapeAmps ) {
            $text = preg_replace( '/&amp;(amp|quot|lt|gt);/', '&\1;', $text );
        }

        return $text;
    }

    public function getDescription() {
        return $this->getIsHtml() ? ' (pretty-print in HTML)' : '';
    }

    public function setBufferResult( $value ) {
    }

    public function getNeedsRawData() {
        wfDeprecated( __METHOD__, '1.25' );
        return true;
    }

}