The Message class provides methods which fulfil two basic services: More...

Inheritance diagram for Message:

Collaboration diagram for Message:

Public Member Functions
	__construct ($key, $params=array(), Language $language=null)
	__toString ()
	Magic method implementation of the above (for PHP >= 5.2.0), so we can do, eg: $foo = Message::get( $key ); $string = "<abbr>$foo</abbr>";.
	bitrateParams ()
	Add parameters that are bitrates and will be passed through Language::formatBitrate before substitution.
	content ()
	Returns the message as a Content object.
	durationParams ()
	Add parameters that are durations of time and will be passed through Language::formatDuration before substitution.
	escaped ()
	Returns the message text.
	exists ()
	Check whether a message key has been defined currently.
	expiryParams ()
	Add parameters that are expiration times and will be passed through Language::formatExpiry before substitution.
	getFormat ()
	Returns the message format.
	getKey ()
	Returns the message key.
	getKeysToTry ()
	getLanguage ()
	Returns the Language of the Message.
	getParams ()
	Returns the message parameters.
	inContentLanguage ()
	Request the message in the wiki's content language, unless it is disabled for this message.
	inLanguage ($lang)
	Request the message in any language that is supported.
	isBlank ()
	Check whether a message does not exist, or is an empty string.
	isDisabled ()
	Check whether a message does not exist, is an empty string, or is "-".
	isMultiKey ()
	numParams ()
	Add parameters that are numeric and will be passed through Language::formatNum before substitution.
	params ()
	Adds parameters to the parameter list of this message.
	parse ()
	Fully parse the text from wikitext to HTML.
	parseAsBlock ()
	Returns the parsed message text which is always surrounded by a block element.
	plain ()
	Returns the message text as-is, only parameters are substituted.
	rawParams ()
	Add parameters that are substituted after parsing or escaping.
	setContext (IContextSource $context)
	Set the language and the title from a context object.
	setInterfaceMessageFlag ($interface)
	Allows manipulating the interface message flag directly.
	sizeParams ()
	Add parameters that are file sizes and will be passed through Language::formatSize before substitution.
	text ()
	Returns the message text.
	timeperiodParams ()
	Add parameters that are time periods and will be passed through Language::formatTimePeriod before substitution.
	title ($title)
	Set the Title object to use as context when transforming the message.
	toString ()
	Returns the message parsed from wikitext to HTML.
	useDatabase ($useDatabase)
	Enable or disable database use.
Static Public Member Functions
static	bitrateParam ($bitrate)
static	durationParam ($duration)
static	expiryParam ($expiry)
static	newFallbackSequence ()
	Factory function accepting multiple message keys and returning a message instance for the first message which is non-empty.
static	newFromKey ($key)
	Factory function that is just wrapper for the real constructor.
static	numParam ($num)
static	rawParam ($raw)
static	sizeParam ($size)
static	timeperiodParam ($period)
Protected Member Functions
	extractParam ($param)
	Extracts the parameter type and preprocessed the value if needed.
	fetchMessage ()
	Wrapper for what ever method we use to get message contents.
	parseText ($string)
	Wrapper for what ever method we use to parse wikitext.
	replaceParameters ($message, $type= 'before')
	Substitutes any parameters into the message text.
	transformText ($string)
	Wrapper for what ever method we use to {{-transform wikitext.
Protected Attributes
Content	$content = null
	Content object representing the message.
string	$format = 'parse'
	Format for the message.
bool	$interface = true
	In which language to get this message.
string	$key
	The message key.
string[]	$keysToTry
	List of keys to try when fetching the message.
Language	$language = null
	In which language to get this message.
string	$message
array	$parameters = array()
	List of parameters which will be substituted into the message.
Title	$title = null
	Title object to use as context.
bool	$useDatabase = true
	Whether database can be used.

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:

Message->inContentLanguage()
Message->inLanguage()

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', array( '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', array( '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

Definition at line 159 of file Message.php.

Constructor & Destructor Documentation

Message::__construct	(	$	key,
		$	params = `array()`,
		Language $	language = `null`
	)

Since:: 1.17

Parameters:

	string\|string[]	$key Message key or array of message keys to try and use the first non-empty message for.
array	$params	Message parameters.
Language	$language	Optional language of the message, defaults to $wgLang.

Exceptions:

InvalidArgumentException

Definition at line 226 of file Message.php.

Member Function Documentation

Message::__toString ( )

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

Since:: 1.18

Returns:: string

Definition at line 714 of file Message.php.

References format, key, and toString().

static Message::bitrateParam ( $ bitrate ) [static]

Since:: 1.22

Parameters:

int $bitrate

Returns:: int[] Array with a single "bitrate" key.

Definition at line 905 of file Message.php.

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

Definition at line 522 of file Message.php.

Message::content ( )

Returns the message as a Content object.

Returns:: Content

Definition at line 648 of file Message.php.

References $title, and title().

static Message::durationParam ( $ duration ) [static]

Since:: 1.22

Parameters:

int $duration

Returns:: int[] Array with a single "duration" key.

Definition at line 861 of file Message.php.

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

Definition at line 434 of file Message.php.

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.

Definition at line 791 of file Message.php.

Message::exists ( )

Check whether a message key has been defined currently.

Since:: 1.17

Returns:: bool

Definition at line 803 of file Message.php.

static Message::expiryParam ( $ expiry ) [static]

Since:: 1.22

Parameters:

string $expiry

Returns:: string[] Array with a single "expiry" key.

Definition at line 872 of file Message.php.

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

Definition at line 456 of file Message.php.

Message::extractParam ( $ param ) [protected]

Extracts the parameter type and preprocessed the value if needed.

Since:: 1.18

Parameters:

mixed $param Parameter as defined in this class.

Returns:: array Array with the parameter type (either "before" or "after") and the value.

Definition at line 940 of file Message.php.

References $e, array(), getKey(), language, and wfDebugLog().

Message::fetchMessage ( ) [protected]

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

Since:: 1.17

Returns:: string

Exceptions:

MWException If message key array is empty.

Reimplemented in RawMessage.

Definition at line 1024 of file Message.php.

Message::getFormat ( )

Returns the message format.

Since:: 1.21

Returns:: string

Definition at line 298 of file Message.php.

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 ahs been fetched, this method will return the key that was actually used to fetch the message.

Since:: 1.21

Returns:: string

Definition at line 276 of file Message.php.

Referenced by extractParam().

Message::getKeysToTry ( )

Since:: 1.24

Returns:: string[] The list of keys to try when fetching the message text, in order of preference.

Definition at line 261 of file Message.php.

Message::getLanguage ( )

Returns the Language of the Message.

Since:: 1.23

Returns:: Language

Definition at line 309 of file Message.php.

Message::getParams ( )

Returns the message parameters.

Since:: 1.21

Returns:: array

Definition at line 287 of file Message.php.

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

Definition at line 589 of file Message.php.

References $wgContLang, array(), global, inLanguage(), and key.

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 $lang Language code or Language object.

Returns:: Message $this

Exceptions:

MWException

Definition at line 562 of file Message.php.

Referenced by inContentLanguage(), and setContext().

Message::isBlank ( )

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

Since:: 1.18

Todo:: FIXME: Merge with isDisabled()?

Returns:: bool

Definition at line 815 of file Message.php.

Message::isDisabled ( )

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

Since:: 1.18

Returns:: bool

Definition at line 827 of file Message.php.

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.

Definition at line 251 of file Message.php.

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

Definition at line 343 of file Message.php.

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[]	$key Message key or array of keys.
mixed	$param,...	Parameters as strings.

Returns:: Message

Definition at line 325 of file Message.php.

static Message::numParam ( $ num ) [static]

Since:: 1.18

Parameters:

mixed $num

Returns:: array Array with a single "num" key.

Definition at line 850 of file Message.php.

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

Definition at line 412 of file Message.php.

Message::params ( )

Adds parameters to the parameter list of this message.

Since:: 1.17

Parameters:

mixed $params,... Parameters as strings, or a single argument that is an array of strings.

Returns:: Message $this

Definition at line 367 of file Message.php.

Message::parse ( )

Fully parse the text from wikitext to HTML.

Since:: 1.17

Returns:: string Parsed HTML.

Definition at line 742 of file Message.php.

Message::parseAsBlock ( )

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

Since:: 1.17

Returns:: string HTML

Definition at line 778 of file Message.php.

Message::parseText ( $ string ) [protected]

Wrapper for what ever method we use to parse wikitext.

Since:: 1.17

Parameters:

string $string Wikitext message contents.

Returns:: string Wikitext parsed into HTML.

Definition at line 986 of file Message.php.

References $out, language, MessageCache\singleton(), and title().

Message::plain ( )

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

Since:: 1.17

Returns:: string Unescaped untransformed message text.

Definition at line 766 of file Message.php.

static Message::rawParam ( $ raw ) [static]

Since:: 1.17

Parameters:

mixed $raw

Returns:: array Array with a single "raw" key.

Definition at line 839 of file Message.php.

Referenced by NewUsersLogFormatter\getMessageParameters(), PatrolLogFormatter\getMessageParameters(), and MoveLogFormatter\getMessageParameters().

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

Definition at line 390 of file Message.php.

Message::replaceParameters	(	$	message,
		$	type = `'before'`
	)		`[protected]`

Substitutes any parameters into the message text.

Since:: 1.17

Parameters:

string	$message	The message text.
string	$type	Either "before" or "after".

Returns:: string

Definition at line 919 of file Message.php.

Message::setContext ( IContextSource $ context )

Set the language and the title from a context object.

Since:: 1.19

Parameters:

IContextSource $context

Returns:: Message $this

Definition at line 542 of file Message.php.

References IContextSource\getLanguage(), IContextSource\getTitle(), inLanguage(), title(), and true.

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

Definition at line 610 of file Message.php.

static Message::sizeParam ( $ size ) [static]

Since:: 1.22

Parameters:

int $size

Returns:: int[] Array with a single "size" key.

Definition at line 894 of file Message.php.

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

Definition at line 500 of file Message.php.

Message::text ( )

Returns the message text.

{{-transformation is done.

Since:: 1.17

Returns:: string Unescaped message text.

Definition at line 754 of file Message.php.

static Message::timeperiodParam ( $ period ) [static]

Since:: 1.22

Parameters:

number $period

Returns:: number[] Array with a single "period" key.

Definition at line 883 of file Message.php.

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

Definition at line 478 of file Message.php.

Message::title ( $ title )

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

Since:: 1.18

Parameters:

Title $title

Returns:: Message $this

Definition at line 638 of file Message.php.

Referenced by content(), parseText(), setContext(), and transformText().

Message::toString ( )

Returns the message parsed from wikitext to HTML.

Since:: 1.17

Returns:: string HTML

Definition at line 663 of file Message.php.

Referenced by __toString().

Message::transformText ( $ string ) [protected]

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

Since:: 1.17

Parameters:

string $string Wikitext message contents.

Returns:: string Wikitext with {{-constructs replaced with their values.

Definition at line 1007 of file Message.php.

References language, MessageCache\singleton(), and title().

Message::useDatabase ( $ useDatabase )

Enable or disable database use.

Since:: 1.17

Parameters:

bool $useDatabase

Returns:: Message $this

Definition at line 624 of file Message.php.

References $useDatabase.

Member Data Documentation

Content Message::$content = null [protected]

Content object representing the message.

Definition at line 210 of file Message.php.

string Message::$format = 'parse' [protected]

Format for the message.

Supported formats are: * text (transform) * escaped (transform+htmlspecialchars) * block-parse * parse (default) * plain

Definition at line 198 of file Message.php.

bool Message::$interface = true [protected]

In which language to get this message.

True, which is the default, means the current interface language, false content language.

Definition at line 166 of file Message.php.

string Message::$key [protected]

The message key.

If $keysToTry has more than one element, this may change to one of the keys to try when fetching the message text.

Definition at line 178 of file Message.php.

string [] Message::$keysToTry [protected]

List of keys to try when fetching the message.

Definition at line 182 of file Message.php.

Language Message::$language = null [protected]

In which language to get this message.

Overrides the $interface variable.

Definition at line 173 of file Message.php.

string Message::$message [protected]

Definition at line 214 of file Message.php.

array Message::$parameters = array() [protected]

List of parameters which will be substituted into the message.

Definition at line 186 of file Message.php.

Title Message::$title = null [protected]

Title object to use as context.

Definition at line 206 of file Message.php.

Referenced by content().

bool Message::$useDatabase = true [protected]

Whether database can be used.

Definition at line 202 of file Message.php.

Referenced by useDatabase().

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

includes/Message.php

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Global function wrapper:

Changing language:

Comparison with old wfMsg* functions:

Appendix:

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation