Message Class Reference

The Message class provides methods which fullfil two basic services:

More...

Collaboration diagram for Message:
Collaboration graph
[legend]

List of all members.

Public Member Functions

 __construct ($key, $params=array())
 Constructor.
 __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>";.
 content ()
 Returns the message as a Content object.
 escaped ()
 Returns the message text.
 exists ()
 Check whether a message key has been defined currently.
 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 "-".
 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 subsituted.
 rawParams ()
 Add parameters that are substituted after parsing or escaping.
 setContext (IContextSource $context)
 Set the language and the title from a context object.
 setInterfaceMessageFlag ($value)
 Allows manipulating the interface message flag directly.
 text ()
 Returns the message text.
 title ($title)
 Set the Title object to use as context when transforming the message.
 toString ()
 Returns the message parsed from wikitext to HTML.
 useDatabase ($value)
 Enable or disable database use.

Static Public Member Functions

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 ($value)
static rawParam ($value)

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 paramaters into the message text.
 transformText ($string)
 Wrapper for what ever method we use to {{-transform wikitext.

Protected Attributes

 $content = null
 Content object representing the message.
 $format = 'parse'
 Format for the message.
 $interface = true
 In which language to get this message.
 $key
 The message key.
Language $language = null
 In which language to get this message.
string $message
 $parameters = array()
 List of parameters which will be substituted into the message.
 $title = null
 Title object to use as context.
 $useDatabase = true
 Whether database can be used.

Detailed Description

The Message class provides methods which fullfil two basic services:

First implemented with MediaWiki 1.17, the Message class is intented 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', 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() 
)

Constructor.

Since:
1.17
Parameters:
$key,: message key, or array of message keys to try and use the first non-empty message for
$params Array message parameters
Returns:
Message: $this

Definition at line 220 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 480 of file Message.php.

Message::content (  ) 

Returns the message as a Content object.

Returns:
Content

Definition at line 415 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 530 of file Message.php.

Message::exists (  ) 

Check whether a message key has been defined currently.

Since:
1.17
Returns:
Bool: true if it is and false if not.

Definition at line 540 of file Message.php.

Message::extractParam ( $  param  )  [protected]

Extracts the parameter type and preprocessed the value if needed.

Since:
1.18
Parameters:
$param String|Array: Parameter as defined in this class.
Returns:
Tuple(type, value)
Exceptions:
MWException 

Definition at line 609 of file Message.php.

Message::fetchMessage (  )  [protected]

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

Since:
1.17
Exceptions:
MWException 
Returns:
string

Definition at line 649 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 365 of file Message.php.

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:
$lang Mixed: language code or Language object.
Exceptions:
MWException 
Returns:
Message: $this

Definition at line 341 of file Message.php.

Message::isBlank (  ) 

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

Since:
1.18
Returns:
Bool: true if is is and false if not
Todo:
FIXME: Merge with isDisabled()?

Definition at line 550 of file Message.php.

Message::isDisabled (  ) 

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

Since:
1.18
Returns:
Bool: true if it is and false if not

Definition at line 560 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:
Varargs,: message keys (or first arg as an array of all the message keys)
Returns:
Message: $this

Definition at line 250 of file Message.php.

static Message::newFromKey ( $  key  )  [static]

Factory function that is just wrapper for the real constructor.

It is intented to be used instead of the real constructor, because it allows chaining method calls, while new objects don't.

Since:
1.17
Parameters:
$key String: message key
Varargs,: parameters as Strings
Returns:
Message: $this

Definition at line 236 of file Message.php.

static Message::numParam ( $  value  )  [static]
Since:
1.18
Parameters:
$value 
Returns:
array

Definition at line 579 of file Message.php.

Message::numParams (  ) 

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

Since:
1.18
Parameters:
Varargs,: numeric parameters (or single argument that is array of numeric parameters)
Returns:
Message: $this

Definition at line 307 of file Message.php.

Message::params (  ) 

Adds parameters to the parameter list of this message.

Since:
1.17
Parameters:
Varargs,: parameters as Strings, or a single argument that is an array of Strings
Returns:
Message: $this

Definition at line 270 of file Message.php.

Message::parse (  ) 

Fully parse the text from wikitext to HTML.

Since:
1.17
Returns:
String parsed HTML

Definition at line 489 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 519 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 629 of file Message.php.

Message::plain (  ) 

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

Since:
1.17
Returns:
String: Unescaped untransformed message text.

Definition at line 509 of file Message.php.

static Message::rawParam ( $  value  )  [static]
Since:
1.17
Parameters:
$value 
Returns:
array

Definition at line 570 of file Message.php.

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:
Varargs,: raw parameters as Strings (or single argument that is an array of raw parameters)
Returns:
Message: $this

Definition at line 289 of file Message.php.

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

Substitutes any paramaters into the message text.

Since:
1.17
Parameters:
$message String: the message text
$type String: either before or after
Returns:
String

Definition at line 590 of file Message.php.

Message::setContext ( IContextSource $  context  ) 

Set the language and the title from a context object.

Since:
1.19
Parameters:
$context IContextSource
Returns:
Message: $this

Definition at line 324 of file Message.php.

Message::setInterfaceMessageFlag ( $  value  ) 

Allows manipulating the interface message flag directly.

Can be used to restore the flag after setting a language.

Parameters:
$value bool
Returns:
Message: $this
Since:
1.20

Definition at line 384 of file Message.php.

Message::text (  ) 

Returns the message text.

{{-transformation is done.

Since:
1.17
Returns:
String: Unescaped message text.

Definition at line 499 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 object
Returns:
Message: $this

Definition at line 406 of file Message.php.

Message::toString (  ) 

Returns the message parsed from wikitext to HTML.

Since:
1.17
Returns:
String: HTML

Definition at line 428 of file Message.php.

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 639 of file Message.php.

Message::useDatabase ( $  value  ) 

Enable or disable database use.

Since:
1.17
Parameters:
$value Boolean
Returns:
Message: $this

Definition at line 395 of file Message.php.

Member Data Documentation

Message::$content = null [protected]

Content object representing the message.

Definition at line 207 of file Message.php.

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

Format for the message.

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

Definition at line 192 of file Message.php.

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 164 of file Message.php.

Message::$key [protected]

The message key.

Definition at line 176 of file Message.php.

Language Message::$language = null [protected]

In which language to get this message.

Overrides the $interface variable.

Definition at line 171 of file Message.php.

string Message::$message [protected]

Definition at line 211 of file Message.php.

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

List of parameters which will be substituted into the message.

Definition at line 181 of file Message.php.

Message::$title = null [protected]

Title object to use as context.

Definition at line 202 of file Message.php.

Message::$useDatabase = true [protected]

Whether database can be used.

Definition at line 197 of file Message.php.

The documentation for this class was generated from the following file:
Generated on Wed Oct 10 00:01:32 2012 for MediaWiki by  doxygen 1.6.3