BlueSpice MediaWiki master
 All Classes Namespaces Files Functions Variables Groups Pages
Message Class Reference
Inheritance diagram for Message:
Collaboration diagram for Message:

Public Member Functions

 __construct ($key, $params=[], Language $language=null)
 
 serialize ()
 
 unserialize ($serialized)
 
 isMultiKey ()
 
 getKeysToTry ()
 
 getKey ()
 
 getParams ()
 
 getFormat ()
 
 getLanguage ()
 
 getTitle ()
 
 params ()
 
 rawParams ()
 
 numParams ()
 
 durationParams ()
 
 expiryParams ()
 
 timeperiodParams ()
 
 sizeParams ()
 
 bitrateParams ()
 
 plaintextParams ()
 
 setContext (IContextSource $context)
 
 inLanguage ($lang)
 
 inContentLanguage ()
 
 setInterfaceMessageFlag ($interface)
 
 useDatabase ($useDatabase)
 
 title ($title)
 
 content ()
 
 toString ($format=null)
 
 __toString ()
 
 parse ()
 
 text ()
 
 plain ()
 
 parseAsBlock ()
 
 escaped ()
 
 exists ()
 
 isBlank ()
 
 isDisabled ()
 

Static Public Member Functions

static newFromKey ($key)
 
static newFromSpecifier ($value)
 
static newFallbackSequence ()
 
static rawParam ($raw)
 
static numParam ($num)
 
static durationParam ($duration)
 
static expiryParam ($expiry)
 
static timeperiodParam ($period)
 
static sizeParam ($size)
 
static bitrateParam ($bitrate)
 
static plaintextParam ($plaintext)
 
static listParam (array $list, $type= 'text')
 

Public Attributes

const FORMAT_PLAIN = 'plain'
 
const FORMAT_BLOCK_PARSE = 'block-parse'
 
const FORMAT_PARSE = 'parse'
 
const FORMAT_TEXT = 'text'
 
const FORMAT_ESCAPED = 'escaped'
 

Protected Member Functions

 replaceParameters ($message, $type= 'before', $format)
 
 extractParam ($param, $format)
 
 parseText ($string)
 
 transformText ($string)
 
 fetchMessage ()
 
 formatPlaintext ($plaintext, $format)
 
 formatListParam (array $params, $listType, $format)
 

Protected Attributes

 $interface = true
 
 $language = false
 
 $key
 
 $keysToTry
 
 $parameters = []
 
 $format = 'parse'
 
 $useDatabase = true
 
 $title = null
 
 $content = null
 
 $message
 

Static Protected Attributes

static $listTypeMap
 

Detailed Description

The Message class provides methods which fulfil two basic services:

  • fetching interface messages
  • processing messages into a variety of formats

First implemented with MediaWiki 1.17, the Message class is intended to replace the old wfMsg* functions that over time grew unusable.

See Also
https://www.mediawiki.org/wiki/Manual:Messages_API for equivalences between old and new functions.

You should use the wfMessage() global function which acts as a wrapper for the Message class. The wrapper let you pass parameters as arguments.

The most basic usage cases would be:

// Initialize a Message object using the 'some_key' message key
$message = wfMessage( 'some_key' );
// Using two parameters those values are strings 'value1' and 'value2':
$message = wfMessage( 'some_key',
'value1', 'value2'
);

Global function wrapper:

Since wfMessage() returns a Message instance, you can chain its call with a method. Some of them return a Message instance too so you can chain them. You will find below several examples of wfMessage() usage.

Fetching a message text for interface message:

$button = Xml::button(
wfMessage( 'submit' )->text()
);

A Message instance can be passed parameters after it has been constructed, use the params() method to do so:

wfMessage( 'welcome-to' )
->params( $wgSitename )
->text();

{{GRAMMAR}} and friends work correctly:

wfMessage( 'are-friends',
$user, $friend
);
wfMessage( 'bad-message' )
->rawParams( '<script>...</script>' )
->escaped();

Changing language:

Messages can be requested in a different language or in whatever current content language is being used. The methods are:

Sometimes the message text ends up in the database, so content language is needed:

wfMessage( 'file-log',
$user, $filename
)->inContentLanguage()->text();

Checking whether a message exists:

wfMessage( 'mysterious-message' )->exists()
// returns a boolean whether the 'mysterious-message' key exist.

If you want to use a different language:

$userLanguage = $user->getOption( 'language' );
wfMessage( 'email-header' )
->inLanguage( $userLanguage )
->plain();
Note
You can parse the text only in the content or interface languages

Comparison with old wfMsg* functions:

Use full parsing:

// old style:
wfMsgExt( 'key', [ 'parseinline' ], 'apple' );
// new style:
wfMessage( 'key', 'apple' )->parse();

Parseinline is used because it is more useful when pre-building HTML. In normal use it is better to use OutputPage::(add|wrap)WikiMsg.

Places where HTML cannot be used. {{-transformation is done.

// old style:
wfMsgExt( 'key', [ 'parsemag' ], 'apple', 'pear' );
// new style:
wfMessage( 'key', 'apple', 'pear' )->text();

Shortcut for escaping the message too, similar to wfMsgHTML(), but parameters are not replaced after escaping by default.

$escaped = wfMessage( 'key' )
->rawParams( 'apple' )
->escaped();

Appendix:

Todo:
  • test, can we have tests?
  • this documentation needs to be extended
See Also
https://www.mediawiki.org/wiki/WfMessage()
https://www.mediawiki.org/wiki/New_messages_API
https://www.mediawiki.org/wiki/Localisation
Since
1.17

Constructor & Destructor Documentation

Message::__construct (   $key,
  $params = [],
Language  $language = null 
)
Since
1.17
Parameters
string|string[]|MessageSpecifier$key Message key, or array of message keys to try and use the first non-empty message for, or a MessageSpecifier to copy from.
array$paramsMessage parameters.
Language$language[optional] Language to use (defaults to current user language).
Exceptions
InvalidArgumentException

Member Function Documentation

Message::__toString ( )

Magic method implementation of the above (for PHP >= 5.2.0), so we can do, eg: $foo = new Message( $key ); $string = "<abbr>$foo</abbr>";

Since
1.18
Returns
string
static Message::bitrateParam (   $bitrate)
static
Since
1.22
Parameters
int$bitrate
Returns
int[] Array with a single "bitrate" key.
Message::bitrateParams ( )

Add parameters that are bitrates and will be passed through Language::formatBitrate before substitution

Since
1.22
Parameters
int|int[]$param,... Bit rate parameters, or a single argument that is an array of bit rate parameters.
Returns
Message $this
Message::content ( )

Returns the message as a Content object.

Returns
Content
static Message::durationParam (   $duration)
static
Since
1.22
Parameters
int$duration
Returns
int[] Array with a single "duration" key.
Message::durationParams ( )

Add parameters that are durations of time and will be passed through Language::formatDuration before substitution

Since
1.22
Parameters
int|int[]$param,... Duration parameters, or a single argument that is an array of duration parameters.
Returns
Message $this
Message::escaped ( )

Returns the message text. {{-transformation is done and the result is escaped excluding any raw parameters.

Since
1.17
Returns
string Escaped message text.
Message::exists ( )

Check whether a message key has been defined currently.

Since
1.17
Returns
bool
static Message::expiryParam (   $expiry)
static
Since
1.22
Parameters
string$expiry
Returns
string[] Array with a single "expiry" key.
Message::expiryParams ( )

Add parameters that are expiration times and will be passed through Language::formatExpiry before substitution

Since
1.22
Parameters
string|string[]$param,... Expiry parameters, or a single argument that is an array of expiry parameters.
Returns
Message $this
Message::extractParam (   $param,
  $format 
)
protected

Extracts the parameter type and preprocessed the value if needed.

Since
1.18
Parameters
mixed$paramParameter as defined in this class.
string$formatOne of the FORMAT_* constants.
Returns
array Array with the parameter type (either "before" or "after") and the value.
Message::fetchMessage ( )
protected

Wrapper for what ever method we use to get message contents.

Since
1.17
Returns
string
Exceptions
MWExceptionIf message key array is empty.
Message::formatListParam ( array  $params,
  $listType,
  $format 
)
protected

Formats a list of parameters as a concatenated string.

Since
1.29
Parameters
array$params
string$listType
string$formatOne of the FORMAT_* constants.
Returns
array Array with the parameter type (either "before" or "after") and the value.
Message::formatPlaintext (   $plaintext,
  $format 
)
protected

Formats a message parameter wrapped with 'plaintext'. Ensures that the entire string is displayed unchanged when displayed in the output format.

Since
1.25
Parameters
string$plaintextString to ensure plaintext output of
string$formatOne of the FORMAT_* constants.
Returns
string Input plaintext encoded for output to $format
Message::getFormat ( )

Returns the message format.

Since
1.21
Returns
string
Deprecated:
since 1.29 formatting is not stateful
Message::getKey ( )

Returns the message key.

If a list of multiple possible keys was supplied to the constructor, this method may return any of these keys. After the message has been fetched, this method will return the key that was actually used to fetch the message.

Since
1.21
Returns
string

Implements MessageSpecifier.

Message::getKeysToTry ( )
Since
1.24
Returns
string[] The list of keys to try when fetching the message text, in order of preference.
Message::getLanguage ( )

Returns the Language of the Message.

Since
1.23
Returns
Language
Message::getParams ( )

Returns the message parameters.

Since
1.21
Returns
array

Implements MessageSpecifier.

Message::getTitle ( )

Get a title object for a mediawiki message, where it can be found in the mediawiki namespace. The title will be for the current language, if the message key is in $wgForceUIMsgAsContentMsg it will be append with the language code (except content language), because Message::inContentLanguage will also return in user language.

See Also
$wgForceUIMsgAsContentMsg
Returns
Title
Since
1.26
Message::inContentLanguage ( )

Request the message in the wiki's content language, unless it is disabled for this message.

Since
1.17
See Also
$wgForceUIMsgAsContentMsg
Returns
Message $this
Message::inLanguage (   $lang)

Request the message in any language that is supported.

As a side effect interface message status is unconditionally turned off.

Since
1.17
Parameters
Language | string$langLanguage code or Language object.
Returns
Message $this
Exceptions
MWException
Message::isBlank ( )

Check whether a message does not exist, or is an empty string

Since
1.18
Todo:
FIXME: Merge with isDisabled()?
Returns
bool
Message::isDisabled ( )

Check whether a message does not exist, is an empty string, or is "-".

Since
1.18
Returns
bool
Message::isMultiKey ( )
Since
1.24
Returns
bool True if this is a multi-key message, that is, if the key provided to the constructor was a fallback list of keys to try.
static Message::listParam ( array  $list,
  $type = 'text' 
)
static
Since
1.29
Parameters
array$list
string$type'comma', 'semicolon', 'pipe', 'text'
Returns
array Array with "list" and "type" keys.
static Message::newFallbackSequence ( )
static

Factory function accepting multiple message keys and returning a message instance for the first message which is non-empty. If all messages are empty then an instance of the first message key is returned.

Since
1.18
Parameters
string|string[]$keys,... Message keys, or first argument as an array of all the message keys.
Returns
Message
static Message::newFromKey (   $key)
static

Factory function that is just wrapper for the real constructor. It is intended to be used instead of the real constructor, because it allows chaining method calls, while new objects don't.

Since
1.17
Parameters
string|string[]|MessageSpecifier$key
mixed$param,...Parameters as strings.
Returns
Message
static Message::newFromSpecifier (   $value)
static

Transform a MessageSpecifier or a primitive value used interchangeably with specifiers (a message key string, or a key + params array) into a proper Message.

Also accepts a MessageSpecifier inside an array: that's not considered a valid format but is an easy error to make due to how StatusValue stores messages internally. Further array elements are ignored in that case.

Parameters
string | array | MessageSpecifier$value
Returns
Message
Exceptions
InvalidArgumentException
Since
1.27
static Message::numParam (   $num)
static
Since
1.18
Parameters
mixed$num
Returns
array Array with a single "num" key.
Message::numParams ( )

Add parameters that are numeric and will be passed through Language::formatNum before substitution

Since
1.18
Parameters
mixed$param,...Numeric parameters, or a single argument that is an array of numeric parameters.
Returns
Message $this
Message::params ( )

Adds parameters to the parameter list of this message.

Since
1.17
Parameters
mixed$args,...Parameters as strings or arrays from Message::numParam() and the like, or a single array of parameters.
Returns
Message $this
Message::parse ( )

Fully parse the text from wikitext to HTML.

Since
1.17
Returns
string Parsed HTML.
Message::parseAsBlock ( )

Returns the parsed message text which is always surrounded by a block element.

Since
1.17
Returns
string HTML
Message::parseText (   $string)
protected

Wrapper for what ever method we use to parse wikitext.

Since
1.17
Parameters
string$stringWikitext message contents.
Returns
string Wikitext parsed into HTML.
Message::plain ( )

Returns the message text as-is, only parameters are substituted.

Since
1.17
Returns
string Unescaped untransformed message text.
static Message::plaintextParam (   $plaintext)
static
Since
1.25
Parameters
string$plaintext
Returns
string[] Array with a single "plaintext" key.
Message::plaintextParams ( )

Add parameters that are plaintext and will be passed through without the content being evaluated. Plaintext parameters are not valid as arguments to parser functions. This differs from self::rawParams in that the Message class handles escaping to match the output format.

Since
1.25
Parameters
string|string[]$param,... plaintext parameters, or a single argument that is an array of plaintext parameters.
Returns
Message $this
static Message::rawParam (   $raw)
static
Since
1.17
Parameters
mixed$raw
Returns
array Array with a single "raw" key.
Message::rawParams ( )

Add parameters that are substituted after parsing or escaping. In other words the parsing process cannot access the contents of this type of parameter, and you need to make sure it is sanitized beforehand. The parser will see "$n", instead.

Since
1.17
Parameters
mixed$params,...Raw parameters as strings, or a single argument that is an array of raw parameters.
Returns
Message $this
Message::replaceParameters (   $message,
  $type = 'before',
  $format 
)
protected

Substitutes any parameters into the message text.

Since
1.17
Parameters
string$messageThe message text.
string$typeEither "before" or "after".
string$formatOne of the FORMAT_* constants.
Returns
string
Message::serialize ( )
See Also
Serializable::serialize()
Since
1.26
Returns
string

Implements Serializable.

Message::setContext ( IContextSource  $context)

Set the language and the title from a context object

Since
1.19
Parameters
IContextSource$context
Returns
Message $this
Message::setInterfaceMessageFlag (   $interface)

Allows manipulating the interface message flag directly. Can be used to restore the flag after setting a language.

Since
1.20
Parameters
bool$interface
Returns
Message $this
static Message::sizeParam (   $size)
static
Since
1.22
Parameters
int$size
Returns
int[] Array with a single "size" key.
Message::sizeParams ( )

Add parameters that are file sizes and will be passed through Language::formatSize before substitution

Since
1.22
Parameters
int|int[]$param,... Size parameters, or a single argument that is an array of size parameters.
Returns
Message $this
Message::text ( )

Returns the message text. {{-transformation is done.

Since
1.17
Returns
string Unescaped message text.
static Message::timeperiodParam (   $period)
static
Since
1.22
Parameters
int$period
Returns
int[] Array with a single "period" key.
Message::timeperiodParams ( )

Add parameters that are time periods and will be passed through Language::formatTimePeriod before substitution

Since
1.22
Parameters
int|int[]$param,... Time period parameters, or a single argument that is an array of time period parameters.
Returns
Message $this
Message::title (   $title)

Set the Title object to use as context when transforming the message

Since
1.18
Parameters
Title$title
Returns
Message $this
Message::toString (   $format = null)

Returns the message parsed from wikitext to HTML.

Since
1.17
Parameters
string | null$formatOne of the FORMAT_* constants. Null means use whatever was used the last time (this is for B/C and should be avoided).
Returns
string HTML
Message::transformText (   $string)
protected

Wrapper for what ever method we use to {{-transform wikitext.

Since
1.17
Parameters
string$stringWikitext message contents.
Returns
string Wikitext with {{-constructs replaced with their values.
Message::unserialize (   $serialized)
See Also
Serializable::unserialize()
Since
1.26
Parameters
string$serialized

Implements Serializable.

Message::useDatabase (   $useDatabase)

Enable or disable database use.

Since
1.17
Parameters
bool$useDatabase
Returns
Message $this

Member Data Documentation

Message::$listTypeMap
staticprotected
Initial value:
= [
'comma' => 'commaList'
const Message::FORMAT_BLOCK_PARSE = 'block-parse'

Use normal wikitext -> HTML parsing (the result will be wrapped in a block-level HTML tag)

const Message::FORMAT_ESCAPED = 'escaped'

Transform {{..}} constructs, HTML-escape the result

const Message::FORMAT_PARSE = 'parse'

Use normal wikitext -> HTML parsing but strip the block-level wrapper

const Message::FORMAT_PLAIN = 'plain'

Use message text as-is

const Message::FORMAT_TEXT = 'text'

Transform {{..}} constructs but don't transform to HTML


The documentation for this class was generated from the following file: