Message.php

Go to the documentation of this file.

<?php
use MediaWiki\Logger\LoggerFactory;
use MediaWiki\MediaWikiServices;
 
class Message implements MessageSpecifier, Serializable {
    public const FORMAT_PLAIN = 'plain';
    public const FORMAT_BLOCK_PARSE = 'block-parse';
    public const FORMAT_PARSE = 'parse';
    public const FORMAT_TEXT = 'text';
    public const FORMAT_ESCAPED = 'escaped';
 
    protected static $listTypeMap = [
        'comma' => 'commaList',
        'semicolon' => 'semicolonList',
        'pipe' => 'pipeList',
        'text' => 'listToText',
    ];
 
    protected $interface = true;
 
    protected $language = false;
 
    protected $key;
 
    protected $keysToTry;
 
    protected $parameters = [];
 
    protected $format = 'parse';
 
    protected $useDatabase = true;
 
    protected $title = null;
 
    protected $content = null;
 
    protected $message;
 
    public function __construct( $key, $params = [], Language $language = null ) {
        if ( $key instanceof MessageSpecifier ) {
            if ( $params ) {
                throw new InvalidArgumentException(
                    '$params must be empty if $key is a MessageSpecifier'
                );
            }
            $params = $key->getParams();
            $key = $key->getKey();
        }
 
        if ( !is_string( $key ) && !is_array( $key ) ) {
            throw new InvalidArgumentException( '$key must be a string or an array' );
        }
 
        $this->keysToTry = (array)$key;
 
        if ( empty( $this->keysToTry ) ) {
            throw new InvalidArgumentException( '$key must not be an empty list' );
        }
 
        $this->key = reset( $this->keysToTry );
 
        $this->parameters = array_values( $params );
        // User language is only resolved in getLanguage(). This helps preserve the
        // semantic intent of "user language" across serialize() and unserialize().
        $this->language = $language ?: false;
    }
 
    public function serialize(): string {
        return serialize( $this->__serialize() );
    }
 
    public function __serialize() {
        return [
            'interface' => $this->interface,
            'language' => $this->language ? $this->language->getCode() : false,
            'key' => $this->key,
            'keysToTry' => $this->keysToTry,
            'parameters' => $this->parameters,
            'format' => $this->format,
            'useDatabase' => $this->useDatabase,
            // Optimisation: Avoid cost of TitleFormatter on serialize,
            // and especially cost of TitleParser (via Title::newFromText)
            // on retrieval.
            'titlevalue' => ( $this->title
                ? [ 0 => $this->title->getNamespace(), 1 => $this->title->getDBkey() ]
                : null
            ),
        ];
    }
 
    public function unserialize( $serialized ): void {
        $this->__unserialize( unserialize( $serialized ) );
    }
 
    public function __unserialize( $data ) {
        if ( !is_array( $data ) ) {
            throw new InvalidArgumentException( __METHOD__ . ': Invalid serialized data' );
        }
        $this->interface = $data['interface'];
        $this->key = $data['key'];
        $this->keysToTry = $data['keysToTry'];
        $this->parameters = $data['parameters'];
        $this->format = $data['format'];
        $this->useDatabase = $data['useDatabase'];
        $this->language = $data['language']
            ? MediaWikiServices::getInstance()->getLanguageFactory()
                ->getLanguage( $data['language'] )
            : false;
 
        // Since 1.35, the key 'titlevalue' is set, instead of 'titlestr'.
        if ( isset( $data['titlevalue'] ) ) {
            $this->title = Title::makeTitle( $data['titlevalue'][0], $data['titlevalue'][1] );
        } elseif ( isset( $data['titlestr'] ) ) {
            $this->title = Title::newFromText( $data['titlestr'] );
        } else {
            $this->title = null; // Explicit for sanity
        }
    }
 
    public function isMultiKey() {
        return count( $this->keysToTry ) > 1;
    }
 
    public function getKeysToTry() {
        return $this->keysToTry;
    }
 
    public function getKey() {
        return $this->key;
    }
 
    public function getParams() {
        return $this->parameters;
    }
 
    public function getFormat() {
        wfDeprecated( __METHOD__, '1.29' );
        return $this->format;
    }
 
    public function getLanguage() {
        // Defaults to false which means current user language
        return $this->language ?: RequestContext::getMain()->getLanguage();
    }
 
    public static function newFromKey( $key, ...$params ) {
        return new self( $key, $params );
    }
 
    public static function newFromSpecifier( $value ) {
        $params = [];
        if ( is_array( $value ) ) {
            $params = $value;
            $value = array_shift( $params );
        }
 
        if ( $value instanceof Message ) { // Message, RawMessage, ApiMessage, etc
            $message = clone $value;
        } elseif ( $value instanceof MessageSpecifier ) {
            $message = new Message( $value );
        } elseif ( is_string( $value ) ) {
            $message = new Message( $value, $params );
        } else {
            throw new InvalidArgumentException( __METHOD__ . ': invalid argument type '
                . gettype( $value ) );
        }
 
        return $message;
    }
 
    public static function newFallbackSequence( ...$keys ) {
        if ( func_num_args() == 1 ) {
            if ( is_array( $keys[0] ) ) {
                // Allow an array to be passed as the first argument instead
                $keys = array_values( $keys[0] );
            } else {
                // Optimize a single string to not need special fallback handling
                $keys = $keys[0];
            }
        }
        return new self( $keys );
    }
 
    public function getTitle() {
        global $wgForceUIMsgAsContentMsg;
 
        $contLang = MediaWikiServices::getInstance()->getContentLanguage();
        $lang = $this->getLanguage();
        $title = $this->key;
        if (
            !$lang->equals( $contLang )
            && in_array( $this->key, (array)$wgForceUIMsgAsContentMsg )
        ) {
            $title .= '/' . $lang->getCode();
        }
 
        return Title::makeTitle(
            NS_MEDIAWIKI, $contLang->ucfirst( strtr( $title, ' ', '_' ) ) );
    }
 
    public function params( ...$args ) {
        // If $args has only one entry and it's an array, then it's either a
        // non-varargs call or it happens to be a call with just a single
        // "special" parameter. Since the "special" parameters don't have any
        // numeric keys, we'll test that to differentiate the cases.
        if ( count( $args ) === 1 && isset( $args[0] ) && is_array( $args[0] ) ) {
            if ( $args[0] === [] ) {
                $args = [];
            } else {
                foreach ( $args[0] as $key => $value ) {
                    if ( is_int( $key ) ) {
                        $args = $args[0];
                        break;
                    }
                }
            }
        }
 
        $this->parameters = array_merge( $this->parameters, array_values( $args ) );
        return $this;
    }
 
    public function rawParams( ...$params ) {
        if ( isset( $params[0] ) && is_array( $params[0] ) ) {
            $params = $params[0];
        }
        foreach ( $params as $param ) {
            $this->parameters[] = self::rawParam( $param );
        }
        return $this;
    }
 
    public function numParams( ...$params ) {
        if ( isset( $params[0] ) && is_array( $params[0] ) ) {
            $params = $params[0];
        }
        foreach ( $params as $param ) {
            $this->parameters[] = self::numParam( $param );
        }
        return $this;
    }
 
    public function durationParams( ...$params ) {
        if ( isset( $params[0] ) && is_array( $params[0] ) ) {
            $params = $params[0];
        }
        foreach ( $params as $param ) {
            $this->parameters[] = self::durationParam( $param );
        }
        return $this;
    }
 
    public function expiryParams( ...$params ) {
        if ( isset( $params[0] ) && is_array( $params[0] ) ) {
            $params = $params[0];
        }
        foreach ( $params as $param ) {
            $this->parameters[] = self::expiryParam( $param );
        }
        return $this;
    }
 
    public function timeperiodParams( ...$params ) {
        if ( isset( $params[0] ) && is_array( $params[0] ) ) {
            $params = $params[0];
        }
        foreach ( $params as $param ) {
            $this->parameters[] = self::timeperiodParam( $param );
        }
        return $this;
    }
 
    public function sizeParams( ...$params ) {
        if ( isset( $params[0] ) && is_array( $params[0] ) ) {
            $params = $params[0];
        }
        foreach ( $params as $param ) {
            $this->parameters[] = self::sizeParam( $param );
        }
        return $this;
    }
 
    public function bitrateParams( ...$params ) {
        if ( isset( $params[0] ) && is_array( $params[0] ) ) {
            $params = $params[0];
        }
        foreach ( $params as $param ) {
            $this->parameters[] = self::bitrateParam( $param );
        }
        return $this;
    }
 
    public function plaintextParams( ...$params ) {
        if ( isset( $params[0] ) && is_array( $params[0] ) ) {
            $params = $params[0];
        }
        foreach ( $params as $param ) {
            $this->parameters[] = self::plaintextParam( $param );
        }
        return $this;
    }
 
    public function setContext( IContextSource $context ) {
        $this->inLanguage( $context->getLanguage() );
        $this->title( $context->getTitle() );
        $this->interface = true;
 
        return $this;
    }
 
    public function inLanguage( $lang ) {
        $previousLanguage = $this->language;
 
        if ( $lang instanceof Language ) {
            $this->language = $lang;
        } elseif ( is_string( $lang ) ) {
            if ( !$this->language instanceof Language || $this->language->getCode() != $lang ) {
                $this->language = MediaWikiServices::getInstance()->getLanguageFactory()
                    ->getLanguage( $lang );
            }
        } elseif ( $lang instanceof StubUserLang ) {
            $this->language = false;
        } else {
            $type = gettype( $lang );
            throw new MWException( __METHOD__ . " must be "
                . "passed a String or Language object; $type given"
            );
        }
 
        if ( $this->language !== $previousLanguage ) {
            // The language has changed. Clear the message cache.
            $this->message = null;
        }
        $this->interface = false;
        return $this;
    }
 
    public function inContentLanguage() {
        global $wgForceUIMsgAsContentMsg;
        if ( in_array( $this->key, (array)$wgForceUIMsgAsContentMsg ) ) {
            return $this;
        }
 
        $this->inLanguage( MediaWikiServices::getInstance()->getContentLanguage() );
        return $this;
    }
 
    public function setInterfaceMessageFlag( $interface ) {
        $this->interface = (bool)$interface;
        return $this;
    }
 
    public function useDatabase( $useDatabase ) {
        $this->useDatabase = (bool)$useDatabase;
        $this->message = null;
        return $this;
    }
 
    public function title( $title ) {
        $this->title = $title;
        return $this;
    }
 
    public function content() {
        if ( !$this->content ) {
            $this->content = new MessageContent( $this );
        }
 
        return $this->content;
    }
 
    public function toString( $format = null ) {
        if ( $format === null ) {
            $ex = new LogicException( __METHOD__ . ' using implicit format: ' . $this->format );
            LoggerFactory::getInstance( 'message-format' )->warning(
                $ex->getMessage(), [ 'exception' => $ex, 'format' => $this->format, 'key' => $this->key ] );
            $format = $this->format;
        }
        $string = $this->fetchMessage();
 
        if ( $string === false ) {
            // Err on the side of safety, ensure that the output
            // is always html safe in the event the message key is
            // missing, since in that case its highly likely the
            // message key is user-controlled.
            // '⧼' is used instead of '<' to side-step any
            // double-escaping issues.
            // (Keep synchronised with mw.Message#toString in JS.)
            return '⧼' . htmlspecialchars( $this->key ) . '⧽';
        }
 
        # Replace $* with a list of parameters for &uselang=qqx.
        if ( strpos( $string, '$*' ) !== false ) {
            $paramlist = '';
            if ( $this->parameters !== [] ) {
                $paramlist = ': $' . implode( ', $', range( 1, count( $this->parameters ) ) );
            }
            $string = str_replace( '$*', $paramlist, $string );
        }
 
        # Replace parameters before text parsing
        $string = $this->replaceParameters( $string, 'before', $format );
 
        # Maybe transform using the full parser
        if ( $format === self::FORMAT_PARSE ) {
            $string = $this->parseText( $string );
            $string = Parser::stripOuterParagraph( $string );
        } elseif ( $format === self::FORMAT_BLOCK_PARSE ) {
            $string = $this->parseText( $string );
        } elseif ( $format === self::FORMAT_TEXT ) {
            $string = $this->transformText( $string );
        } elseif ( $format === self::FORMAT_ESCAPED ) {
            $string = $this->transformText( $string );
            $string = htmlspecialchars( $string, ENT_QUOTES, 'UTF-8', false );
        }
 
        # Raw parameter replacement
        $string = $this->replaceParameters( $string, 'after', $format );
 
        return $string;
    }
 
    public function __toString() {
        // PHP doesn't allow __toString to throw exceptions and will
        // trigger a fatal error if it does. So, catch any exceptions.
 
        try {
            return $this->toString( self::FORMAT_PARSE );
        } catch ( Exception $ex ) {
            try {
                trigger_error( "Exception caught in " . __METHOD__ . " (message " . $this->key . "): "
                    . $ex, E_USER_WARNING );
            } catch ( Exception $ex ) {
                // Doh! Cause a fatal error after all?
            }
 
            return '⧼' . htmlspecialchars( $this->key ) . '⧽';
        }
    }
 
    public function parse() {
        $this->format = self::FORMAT_PARSE;
        return $this->toString( self::FORMAT_PARSE );
    }
 
    public function text() {
        $this->format = self::FORMAT_TEXT;
        return $this->toString( self::FORMAT_TEXT );
    }
 
    public function plain() {
        $this->format = self::FORMAT_PLAIN;
        return $this->toString( self::FORMAT_PLAIN );
    }
 
    public function parseAsBlock() {
        $this->format = self::FORMAT_BLOCK_PARSE;
        return $this->toString( self::FORMAT_BLOCK_PARSE );
    }
 
    public function escaped() {
        $this->format = self::FORMAT_ESCAPED;
        return $this->toString( self::FORMAT_ESCAPED );
    }
 
    public function exists() {
        return $this->fetchMessage() !== false;
    }
 
    public function isBlank() {
        $message = $this->fetchMessage();
        return $message === false || $message === '';
    }
 
    public function isDisabled() {
        $message = $this->fetchMessage();
        return $message === false || $message === '' || $message === '-';
    }
 
    public static function rawParam( $raw ) {
        return [ 'raw' => $raw ];
    }
 
    public static function numParam( $num ) {
        return [ 'num' => $num ];
    }
 
    public static function durationParam( $duration ) {
        return [ 'duration' => $duration ];
    }
 
    public static function expiryParam( $expiry ) {
        return [ 'expiry' => $expiry ];
    }
 
    public static function timeperiodParam( $period ) {
        return [ 'period' => $period ];
    }
 
    public static function sizeParam( $size ) {
        return [ 'size' => $size ];
    }
 
    public static function bitrateParam( $bitrate ) {
        return [ 'bitrate' => $bitrate ];
    }
 
    public static function plaintextParam( $plaintext ) {
        return [ 'plaintext' => $plaintext ];
    }
 
    public static function listParam( array $list, $type = 'text' ) {
        if ( !isset( self::$listTypeMap[$type] ) ) {
            throw new InvalidArgumentException(
                "Invalid type '$type'. Known types are: " . implode( ', ', array_keys( self::$listTypeMap ) )
            );
        }
        return [ 'list' => $list, 'type' => $type ];
    }
 
    protected function replaceParameters( $message, $type, $format ) {
        // A temporary marker for $1 parameters that is only valid
        // in non-attribute contexts. However if the entire message is escaped
        // then we don't want to use it because it will be mangled in all contexts
        // and its unnessary as ->escaped() messages aren't html.
        $marker = $format === self::FORMAT_ESCAPED ? '$' : '$\'"';
        $replacementKeys = [];
        foreach ( $this->parameters as $n => $param ) {
            list( $paramType, $value ) = $this->extractParam( $param, $format );
            if ( $type === 'before' ) {
                if ( $paramType === 'before' ) {
                    $replacementKeys['$' . ( $n + 1 )] = $value;
                } else /* $paramType === 'after' */ {
                    // To protect against XSS from replacing parameters
                    // inside html attributes, we convert $1 to $'"1.
                    // In the event that one of the parameters ends up
                    // in an attribute, either the ' or the " will be
                    // escaped, breaking the replacement and avoiding XSS.
                    $replacementKeys['$' . ( $n + 1 )] = $marker . ( $n + 1 );
                }
            } elseif ( $paramType === 'after' ) {
                $replacementKeys[$marker . ( $n + 1 )] = $value;
            }
        }
        return strtr( $message, $replacementKeys );
    }
 
    protected function extractParam( $param, $format ) {
        if ( is_array( $param ) ) {
            if ( isset( $param['raw'] ) ) {
                return [ 'after', $param['raw'] ];
            } elseif ( isset( $param['num'] ) ) {
                // Replace number params always in before step for now.
                // No support for combined raw and num params
                return [ 'before', $this->getLanguage()->formatNum( $param['num'] ) ];
            } elseif ( isset( $param['duration'] ) ) {
                return [ 'before', $this->getLanguage()->formatDuration( $param['duration'] ) ];
            } elseif ( isset( $param['expiry'] ) ) {
                return [ 'before', $this->getLanguage()->formatExpiry( $param['expiry'] ) ];
            } elseif ( isset( $param['period'] ) ) {
                return [ 'before', $this->getLanguage()->formatTimePeriod( $param['period'] ) ];
            } elseif ( isset( $param['size'] ) ) {
                return [ 'before', $this->getLanguage()->formatSize( $param['size'] ) ];
            } elseif ( isset( $param['bitrate'] ) ) {
                return [ 'before', $this->getLanguage()->formatBitrate( $param['bitrate'] ) ];
            } elseif ( isset( $param['plaintext'] ) ) {
                return [ 'after', $this->formatPlaintext( $param['plaintext'], $format ) ];
            } elseif ( isset( $param['list'] ) ) {
                return $this->formatListParam( $param['list'], $param['type'], $format );
            } else {
                LoggerFactory::getInstance( 'Bug58676' )->warning(
                    'Invalid parameter for message "{msgkey}": {param}',
                    [
                        'exception' => new Exception,
                        'msgkey' => $this->getKey(),
                        'param' => htmlspecialchars( serialize( $param ) ),
                    ]
                );
 
                return [ 'before', '[INVALID]' ];
            }
        } elseif ( $param instanceof Message ) {
            // Match language, flags, etc. to the current message.
            $msg = clone $param;
            if ( $msg->language !== $this->language || $msg->useDatabase !== $this->useDatabase ) {
                // Cache depends on these parameters
                $msg->message = null;
            }
            $msg->interface = $this->interface;
            $msg->language = $this->language;
            $msg->useDatabase = $this->useDatabase;
            $msg->title = $this->title;
 
            // DWIM
            if ( $format === 'block-parse' ) {
                $format = 'parse';
            }
            $msg->format = $format;
 
            // Message objects should not be before parameters because
            // then they'll get double escaped. If the message needs to be
            // escaped, it'll happen right here when we call toString().
            return [ 'after', $msg->toString( $format ) ];
        } else {
            return [ 'before', $param ];
        }
    }
 
    protected function parseText( $string ) {
        $out = MediaWikiServices::getInstance()->getMessageCache()->parse(
            $string,
            $this->title,
            /*linestart*/true,
            $this->interface,
            $this->getLanguage()
        );
 
        return $out instanceof ParserOutput
            ? $out->getText( [
                'enableSectionEditLinks' => false,
                // Wrapping messages in an extra <div> is probably not expected. If
                // they're outside the content area they probably shouldn't be
                // targeted by CSS that's targeting the parser output, and if
                // they're inside they already are from the outer div.
                'unwrap' => true,
            ] )
            : $out;
    }
 
    protected function transformText( $string ) {
        return MediaWikiServices::getInstance()->getMessageCache()->transform(
            $string,
            $this->interface,
            $this->getLanguage(),
            $this->title
        );
    }
 
    protected function fetchMessage() {
        if ( $this->message === null ) {
            $cache = MediaWikiServices::getInstance()->getMessageCache();
 
            foreach ( $this->keysToTry as $key ) {
                $message = $cache->get( $key, $this->useDatabase, $this->getLanguage() );
                if ( $message !== false && $message !== '' ) {
                    break;
                }
            }
 
            // NOTE: The constructor makes sure keysToTry isn't empty,
            //       so we know that $key and $message are initialized.
            $this->key = $key;
            $this->message = $message;
        }
        return $this->message;
    }
 
    protected function formatPlaintext( $plaintext, $format ) {
        switch ( $format ) {
            case self::FORMAT_TEXT:
            case self::FORMAT_PLAIN:
                return $plaintext;
 
            case self::FORMAT_PARSE:
            case self::FORMAT_BLOCK_PARSE:
            case self::FORMAT_ESCAPED:
            default:
                return htmlspecialchars( $plaintext, ENT_QUOTES );
        }
    }
 
    protected function formatListParam( array $params, $listType, $format ) {
        if ( !isset( self::$listTypeMap[$listType] ) ) {
            $warning = 'Invalid list type for message "' . $this->getKey() . '": '
                . htmlspecialchars( $listType )
                . ' (params are ' . htmlspecialchars( serialize( $params ) ) . ')';
            trigger_error( $warning, E_USER_WARNING );
            $e = new Exception;
            wfDebugLog( 'Bug58676', $warning . "\n" . $e->getTraceAsString() );
            return [ 'before', '[INVALID]' ];
        }
        $func = self::$listTypeMap[$listType];
 
        // Handle an empty list sensibly
        if ( !$params ) {
            return [ 'before', $this->getLanguage()->$func( [] ) ];
        }
 
        // First, determine what kinds of list items we have
        $types = [];
        $vars = [];
        $list = [];
        foreach ( $params as $n => $p ) {
            list( $type, $value ) = $this->extractParam( $p, $format );
            $types[$type] = true;
            $list[] = $value;
            $vars[] = '$' . ( $n + 1 );
        }
 
        // Easy case: all are 'before' or 'after', so just join the
        // values and use the same type.
        if ( count( $types ) === 1 ) {
            return [ key( $types ), $this->getLanguage()->$func( $list ) ];
        }
 
        // Hard case: We need to process each value per its type, then
        // return the concatenated values as 'after'. We handle this by turning
        // the list into a RawMessage and processing that as a parameter.
        $vars = $this->getLanguage()->$func( $vars );
        return $this->extractParam( new RawMessage( $vars, $params ), $format );
    }
}