859b9d400d3dbb0745ff853f976beef557b0c89d
4 * OBS!!! *EXPERIMENTAL* This class is still under discussion.
6 * This class provides methods for fetching interface messages and
7 * processing them into variety of formats that are needed in MediaWiki.
9 * It is intented to replace the old wfMsg* functions that over time grew
13 * Fetching a message text for interface message
14 * $button = Xml::button( Message::key( 'submit' ).text() );
15 * Messages can have parameters:
16 * Message::key( 'welcome-to' )->param( $wgSitename ).text(); // {{GRAMMAR}} and friends work correctly
17 * Message::key( 'are-friends' )->params( $user, $friend );
18 * Message::key( 'bad-message' )->rawParam( '<script>...</script>' ).escaped()
19 * Sometimes the message text ends up in the database, so content language is needed.
20 * Message::key( 'file-log' )->params( $user, $filename )->inContentLanguage()->text()
21 * Checking if message exists:
22 * Message::key( 'mysterious-message' )->exists()
23 * If you want to use a different language:
24 * Message::key( 'email-header' )->language( $user->getOption( 'language' ) )->plain()
27 * Comparison with old wfMsg* functions:
30 * Would correspond to wfMsgExt( 'key', array( 'parseinline' ), 'apple' );
31 * $parsed = Message::key( 'key' )->param( 'apple' )->parse();
32 * Parseinline is used because it is more useful when pre-building html.
33 * In normal use it is better to use OutputPage::(add|wrap)WikiMsg.
35 * Places where html cannot be used. {{-transformation is done.
36 * Would correspond to wfMsgExt( 'key', array( 'parsemag' ), 'apple', 'pear' );
37 * $plain = Message::key( 'key' )->params( 'apple', 'pear' )->text();
39 * Shortcut for escaping the message too, similar to wfMsgHTML, but
40 * parameters are not replaced after escaping by default.
41 * $escaped = Message::key( 'key' )->rawParam( 'apple' )->escaped();
44 * * test, can we have tests?
45 * * sort out the details marked with fixme
46 * * should we have _m() or similar global wrapper?
52 * In which language to get this message. True, which is the default,
53 * means the current interface language, false content language.
55 protected $interface = true;
57 * In which language to get this message. Overrides the $interface
60 protected $language = null;
67 * List of parameters which will be substituted into the message.
69 protected $parameters = array();
73 * @param $key String: message key
74 * @return Message: $this
76 public function __construct( $key ) {
81 * Factory function that is just wrapper for the real constructor. It is
82 * intented to be used instead of the real constructor, because it allows
83 * chaining method calls, while new objects don't.
84 * //FIXME: key or get or something else?
85 * @param $key String: message key
86 * @return Message: $this
88 public function key( $key ) {
89 return new Message( $key );
93 * Adds parameters to the parameter list of this message.
94 * @param $value String: parameter
95 * @return Message: $this
97 public function param( $value ) {
98 $this->parameters
[] = $value;
103 * Adds parameters to the parameter list of this message.
104 * @params Vargars: parameters
105 * @return Message: $this
107 public function params( /*...*/ ) {
108 $this->paramList( func_get_args() );
113 * Adds a list of parameters to the parameter list of this message.
114 * @param $value Array: list of parameters, array keys will be ignored.
115 * @return Message: $this
117 public function paramList( array $values ) {
118 $this->parameters +
= array_values( $values );
123 * Adds a parameters that is substituted after parsing or escaping.
124 * In other words the parsing process cannot access the contents
125 * of this type parameter, and you need to make sure it is
126 * sanitized beforehand.
127 * @param $value String: raw parameter
128 * @return Message: $this
130 public function rawParam( $value ) {
131 $this->parameters
[] = array( 'raw' => $value );
136 * Request the message in any language that is supported.
137 * As a side effect interface message status is unconditionally
139 * @param $lang Mixed: langauge code or language object.
140 * @return Message: $this
142 public function language( Language
$lang ) {
143 if ( is_string( $lang ) ) {
144 $this->language
= Language
::factory( $lang );
146 $this->language
= $lang;
148 $this->interface = false;
153 * Request the message in the wiki's content language.
154 * @return Message: $this
156 public function inContentLanguage() {
157 $this->interface = false;
158 $this->language
= null;
163 * Returns the message parsed from wikitext to HTML.
164 * @return String: HTML
166 public function parse() {
167 $string = $this->parseAsBlock( $string );
169 if( preg_match( '/^<p>(.*)\n?<\/p>\n?$/sU', $string, $m ) ) {
176 * Returns the message text. {{-transformation is done.
177 * @return String: Unescaped message text.
179 public function text() {
180 $string = $this->getMessageText();
181 $string = $this->replaceParameters( 'before' );
182 $string = $this->transformText( $string );
183 $string = $this->replaceParameters( 'after' );
188 * Returns the message text as-is, only parameters are subsituted.
189 * @return String: Unescaped untransformed message text.
191 public function plain() {
192 $string = $this->getMessageText();
193 $string = $this->replaceParameters( 'before' );
194 $string = $this->replaceParameters( 'after' );
199 * Returns the parsed message text which is always surrounded by a block element.
200 * @return String: HTML
202 public function parseAsBlock() {
203 $string = $this->getMessageText();
204 $string = $this->replaceParameters( 'before' );
205 $string = $this->parseText( $string );
206 $string = $this->replaceParameters( 'after' );
211 * Returns the message text. {{-transformation is done and the result
212 * is excaped excluding any raw parameters.
213 * @return String: Escaped message text.
215 public function escaped() {
216 $string = $this->getMessageText();
217 $string = $this->replaceParameters( 'before' );
218 $string = $this->transformText( $string );
219 $string = htmlspecialchars( $string );
220 $string = $this->replaceParameters( 'after' );
225 * Check whether a message key has been defined currently.
226 * @return Bool: true if it is and false if not.
228 public function exists() {
229 return !wfEmptyMsg( $this->key
, $this->getMessageText() );
233 * Substitutes any paramaters into the message text.
234 * @param $type String: either before or after
237 protected function replaceParameters( $type = 'before' ) {
238 $replacementKeys = array();
239 foreach( $args as $n => $param ) {
240 if ( $type === 'before' && !isset( $param['raw'] ) ) {
241 $replacementKeys['$' . ($n +
1)] = $param;
242 } elseif ( $type === 'after' && isset( $param['raw'] ) ) {
243 $replacementKeys['$' . ($n +
1)] = $param['raw'];
246 $message = strtr( $message, $replacementKeys );
251 * Wrapper for what ever method we use to parse wikitext.
252 * @param $string String: Wikitext message contents
253 * @return Wikitext parsed into HTML
255 protected function parseText( $string ) {
257 if ( $this->language
!== null ) {
258 // FIXME: remove this limitation
259 throw new MWException( 'Can only parse in interface or content language' );
261 return $wgOut->parse( $string, /*linestart*/true, $this->interface() );
265 * Wrapper for what ever method we use to {{-transform wikitext.
266 * @param $string String: Wikitext message contents
267 * @return Wikitext with {{-constructs replaced with their values.
269 protected function transformText( $string ) {
270 global $wgMessageCache;
271 return $wgMessageCache->transform( $string, $this->interface, $this->language
);
275 * Wrapper for what ever method we use to get message contents
276 * @return Unmodified message contents
278 protected function getMessageText() {
279 global $wgMessageCache;
280 return $wgMessageCache->get( $this->key
, /*DB*/true, $this->language
);