Use integers for content_model and content_format.
[lhc/web/wiklou.git] / includes / Content.php
1 <?php
2
3 /**
4 * A content object represents page content, e.g. the text to show on a page.
5 * Content objects have no knowledge about how they relate to Wiki pages.
6 *
7 * @since 1.WD
8 */
9 abstract class Content {
10
11 /**
12 * Name of the content model this Content object represents.
13 * Use with CONTENT_MODEL_XXX constants
14 *
15 * @var String $model_id
16 */
17 protected $model_id;
18
19 /**
20 * @return String a string representing the content in a way useful for building a full text search index.
21 * If no useful representation exists, this method returns an empty string.
22 */
23 public abstract function getTextForSearchIndex( );
24
25 /**
26 * @return String the wikitext to include when another page includes this content, or false if the content is not
27 * includable in a wikitext page.
28 *
29 * @TODO: allow native handling, bypassing wikitext representation, like for includable special pages.
30 * @TODO: use in parser, etc!
31 */
32 public abstract function getWikitextForTransclusion( );
33
34 /**
35 * Returns a textual representation of the content suitable for use in edit summaries and log messages.
36 *
37 * @param int $maxlength maximum length of the summary text
38 * @return String the summary text
39 */
40 public abstract function getTextForSummary( $maxlength = 250 );
41
42 /**
43 * Returns native represenation of the data. Interpretation depends on the data model used,
44 * as given by getDataModel().
45 *
46 * @return mixed the native representation of the content. Could be a string, a nested array
47 * structure, an object, a binary blob... anything, really.
48 *
49 * @NOTE: review all calls carefully, caller must be aware of content model!
50 */
51 public abstract function getNativeData( );
52
53 /**
54 * returns the content's nominal size in bogo-bytes.
55 *
56 * @return int
57 */
58 public abstract function getSize( );
59
60 /**
61 * @param int $model_id
62 */
63 public function __construct( $model_id = null ) {
64 $this->model_id = $model_id;
65 }
66
67 /**
68 * Returns the id of the content model used by this content objects.
69 * Corresponds to the CONTENT_MODEL_XXX constants.
70 *
71 * @return int the model id
72 */
73 public function getModel() {
74 return $this->model_id;
75 }
76
77 /**
78 * Throws an MWException if $model_id is not the id of the content model
79 * supported by this Content object.
80 *
81 * @param int $model_id the model to check
82 */
83 protected function checkModelID( $model_id ) {
84 if ( $model_id !== $this->model_id ) {
85 $model_name = ContentHandler::getContentModelName( $model_id );
86 $own_model_name = ContentHandler::getContentModelName( $this->model_id );
87
88 throw new MWException( "Bad content model: expected {$this->model_id} ($own_model_name) but got found $model_id ($model_name)." );
89 }
90 }
91
92 /**
93 * Conveniance method that returns the ContentHandler singleton for handling the content
94 * model this Content object uses.
95 *
96 * Shorthand for ContentHandler::getForContent( $this )
97 *
98 * @return ContentHandler
99 */
100 public function getContentHandler() {
101 return ContentHandler::getForContent( $this );
102 }
103
104 /**
105 * Conveniance method that returns the default serialization format for the content model
106 * model this Content object uses.
107 *
108 * Shorthand for $this->getContentHandler()->getDefaultFormat()
109 *
110 * @return ContentHandler
111 */
112 public function getDefaultFormat() {
113 return $this->getContentHandler()->getDefaultFormat();
114 }
115
116 /**
117 * Conveniance method that returns the list of serialization formats supported
118 * for the content model model this Content object uses.
119 *
120 * Shorthand for $this->getContentHandler()->getSupportedFormats()
121 *
122 * @return array of supported serialization formats
123 */
124 public function getSupportedFormats() {
125 return $this->getContentHandler()->getSupportedFormats();
126 }
127
128 /**
129 * Returns true if $format is a supported serialization format for this Content object,
130 * false if it isn't.
131 *
132 * Note that this will always return true if $format is null, because null stands for the
133 * default serialization.
134 *
135 * Shorthand for $this->getContentHandler()->isSupportedFormat( $format )
136 *
137 * @param String $format the format to check
138 * @return bool whether the format is supported
139 */
140 public function isSupportedFormat( $format ) {
141 if ( !$format ) {
142 return true; // this means "use the default"
143 }
144
145 return $this->getContentHandler()->isSupportedFormat( $format );
146 }
147
148 /**
149 * Throws an MWException if $this->isSupportedFormat( $format ) doesn't return true.
150 *
151 * @param $format
152 * @throws MWException
153 */
154 protected function checkFormat( $format ) {
155 if ( !$this->isSupportedFormat( $format ) ) {
156 throw new MWException( "Format $format is not supported for content model " . $this->getModel() );
157 }
158 }
159
160 /**
161 * Conveniance method for serializing this Content object.
162 *
163 * Shorthand for $this->getContentHandler()->serializeContent( $this, $format )
164 *
165 * @param null|String $format the desired serialization format (or null for the default format).
166 * @return String serialized form of this Content object
167 */
168 public function serialize( $format = null ) {
169 return $this->getContentHandler()->serializeContent( $this, $format );
170 }
171
172 /**
173 * Returns true if this Content object represents empty content.
174 *
175 * @return bool whether this Content object is empty
176 */
177 public function isEmpty() {
178 return $this->getSize() == 0;
179 }
180
181 /**
182 * Returns true if this Content objects is conceptually equivalent to the given Content object.
183 *
184 * Will returns false if $that is null.
185 * Will return true if $that === $this.
186 * Will return false if $that->getModleName() != $this->getModel().
187 * Will return false if $that->getNativeData() is not equal to $this->getNativeData(),
188 * where the meaning of "equal" depends on the actual data model.
189 *
190 * Implementations should be careful to make equals() transitive and reflexive:
191 *
192 * * $a->equals( $b ) <=> $b->equals( $b )
193 * * $a->equals( $b ) && $b->equals( $c ) ==> $a->equals( $c )
194 *
195 * @param Content $that the Content object to compare to
196 * @return bool true if this Content object is euqual to $that, false otherwise.
197 */
198 public function equals( Content $that = null ) {
199 if ( is_null( $that ) ){
200 return false;
201 }
202
203 if ( $that === $this ) {
204 return true;
205 }
206
207 if ( $that->getModel() !== $this->getModel() ) {
208 return false;
209 }
210
211 return $this->getNativeData() === $that->getNativeData();
212 }
213
214 /**
215 * Return a copy of this Content object. The following must be true for the object returned
216 * if $copy = $original->copy()
217 *
218 * * get_class($original) === get_class($copy)
219 * * $original->getModel() === $copy->getModel()
220 * * $original->equals( $copy )
221 *
222 * If and only if the Content object is imutable, the copy() method can and should
223 * return $this. That is, $copy === $original may be true, but only for imutable content
224 * objects.
225 *
226 * @return Content. A copy of this object
227 */
228 public abstract function copy( );
229
230 /**
231 * Returns true if this content is countable as a "real" wiki page, provided
232 * that it's also in a countable location (e.g. a current revision in the main namespace).
233 *
234 * @param $hasLinks Bool: if it is known whether this content contains links, provide this information here,
235 * to avoid redundant parsing to find out.
236 * @return boolean
237 */
238 public abstract function isCountable( $hasLinks = null ) ;
239
240 /**
241 * @param IContextSource $context
242 * @param null $revId
243 * @param null|ParserOptions $options
244 * @param Boolean $generateHtml whether to generate Html (default: true). If false,
245 * the result of calling getText() on the ParserOutput object returned by
246 * this method is undefined.
247 *
248 * @return ParserOutput
249 */
250 public abstract function getParserOutput( IContextSource $context, $revId = null, ParserOptions $options = NULL, $generateHtml = true );
251
252 /**
253 * Construct the redirect destination from this content and return an
254 * array of Titles, or null if this content doesn't represent a redirect.
255 * The last element in the array is the final destination after all redirects
256 * have been resolved (up to $wgMaxRedirects times).
257 *
258 * @return Array of Titles, with the destination last
259 */
260 public function getRedirectChain() {
261 return null;
262 }
263
264 /**
265 * Construct the redirect destination from this content and return an
266 * array of Titles, or null if this content doesn't represent a redirect.
267 * This will only return the immediate redirect target, useful for
268 * the redirect table and other checks that don't need full recursion.
269 *
270 * @return Title: The corresponding Title
271 */
272 public function getRedirectTarget() {
273 return null;
274 }
275
276 /**
277 * Construct the redirect destination from this content and return the
278 * Title, or null if this content doesn't represent a redirect.
279 * This will recurse down $wgMaxRedirects times or until a non-redirect target is hit
280 * in order to provide (hopefully) the Title of the final destination instead of another redirect.
281 *
282 * @return Title
283 */
284 public function getUltimateRedirectTarget() {
285 return null;
286 }
287
288 public function isRedirect() {
289 return $this->getRedirectTarget() != null;
290 }
291
292 /**
293 * Returns the section with the given id.
294 *
295 * The default implementation returns null.
296 *
297 * @param String $sectionId the section's id, given as a numeric string. The id "0" retrieves the section before
298 * the first heading, "1" the text between the first heading (inluded) and the second heading (excluded), etc.
299 * @return Content|Boolean|null the section, or false if no such section exist, or null if sections are not supported
300 */
301 public function getSection( $sectionId ) {
302 return null;
303 }
304
305 /**
306 * Replaces a section of the content and returns a Content object with the section replaced.
307 *
308 * @param $section empty/null/false or a section number (0, 1, 2, T1, T2...), or "new"
309 * @param $with Content: new content of the section
310 * @param $sectionTitle String: new section's subject, only if $section is 'new'
311 * @return string Complete article text, or null if error
312 */
313 public function replaceSection( $section, Content $with, $sectionTitle = '' ) {
314 return null;
315 }
316
317 /**
318 * Returns a Content object with pre-save transformations applied (or this object if no transformations apply).
319 *
320 * @param Title $title
321 * @param User $user
322 * @param null|ParserOptions $popts
323 * @return Content
324 */
325 public function preSaveTransform( Title $title, User $user, ParserOptions $popts ) {
326 return $this;
327 }
328
329 /**
330 * Returns a new WikitextContent object with the given section heading prepended, if supported.
331 * The default implementation just returns this Content object unmodified, ignoring the section header.
332 *
333 * @param $header String
334 * @return Content
335 */
336 public function addSectionHeader( $header ) {
337 return $this;
338 }
339
340 /**
341 * Returns a Content object with preload transformations applied (or this object if no transformations apply).
342 *
343 * @param Title $title
344 * @param null|ParserOptions $popts
345 * @return Content
346 */
347 public function preloadTransform( Title $title, ParserOptions $popts ) {
348 return $this;
349 }
350
351 # TODO: handle ImagePage and CategoryPage
352 # TODO: make sure we cover lucene search / wikisearch.
353 # TODO: make sure ReplaceTemplates still works
354 # FUTURE: nice&sane integration of GeSHi syntax highlighting
355 # [11:59] <vvv> Hooks are ugly; make CodeHighlighter interface and a config to set the class which handles syntax highlighting
356 # [12:00] <vvv> And default it to a DummyHighlighter
357
358 # TODO: make sure we cover the external editor interface (does anyone actually use that?!)
359
360 # TODO: tie into API to provide contentModel for Revisions
361 # TODO: tie into API to provide serialized version and contentFormat for Revisions
362 # TODO: tie into API edit interface
363 # FUTURE: make EditForm plugin for EditPage
364 }
365 # FUTURE: special type for redirects?!
366 # FUTURE: MultipartMultipart < WikipageContent (Main + Links + X)
367 # FUTURE: LinksContent < LanguageLinksContent, CategoriesContent
368
369 /**
370 * Content object implementation for representing flat text.
371 *
372 * TextContent instances are imutable
373 */
374 abstract class TextContent extends Content {
375
376 public function __construct( $text, $model_id = null ) {
377 parent::__construct( $model_id );
378
379 $this->mText = $text;
380 }
381
382 public function copy() {
383 return $this; #NOTE: this is ok since TextContent are imutable.
384 }
385
386 public function getTextForSummary( $maxlength = 250 ) {
387 global $wgContLang;
388
389 $text = $this->getNativeData();
390
391 $truncatedtext = $wgContLang->truncate(
392 preg_replace( "/[\n\r]/", ' ', $text ),
393 max( 0, $maxlength ) );
394
395 return $truncatedtext;
396 }
397
398 /**
399 * returns the text's size in bytes.
400 *
401 * @return int the size
402 */
403 public function getSize( ) {
404 $text = $this->getNativeData( );
405 return strlen( $text );
406 }
407
408 /**
409 * Returns true if this content is not a redirect, and $wgArticleCountMethod is "any".
410 *
411 * @param $hasLinks Bool: if it is known whether this content contains links, provide this information here,
412 * to avoid redundant parsing to find out.
413 *
414 * @return bool true if the content is countable
415 */
416 public function isCountable( $hasLinks = null ) {
417 global $wgArticleCountMethod;
418
419 if ( $this->isRedirect( ) ) {
420 return false;
421 }
422
423 if ( $wgArticleCountMethod === 'any' ) {
424 return true;
425 }
426
427 return false;
428 }
429
430 /**
431 * Returns the text represented by this Content object, as a string.
432 *
433 * @return String the raw text
434 */
435 public function getNativeData( ) {
436 $text = $this->mText;
437 return $text;
438 }
439
440 /**
441 * Returns the text represented by this Content object, as a string.
442 *
443 * @return String the raw text
444 */
445 public function getTextForSearchIndex( ) {
446 return $this->getNativeData();
447 }
448
449 /**
450 * Returns the text represented by this Content object, as a string.
451 *
452 * @return String the raw text
453 */
454 public function getWikitextForTransclusion( ) {
455 return $this->getNativeData();
456 }
457
458 /**
459 * Returns a generic ParserOutput object, wrapping the HTML returned by getHtml().
460 *
461 * @return ParserOutput representing the HTML form of the text
462 */
463 public function getParserOutput( IContextSource $context, $revId = null, ParserOptions $options = null, $generateHtml = true ) {
464 # generic implementation, relying on $this->getHtml()
465
466 if ( $generateHtml ) $html = $this->getHtml( $options );
467 else $html = '';
468
469 $po = new ParserOutput( $html );
470
471 return $po;
472 }
473
474 protected abstract function getHtml( );
475
476 }
477
478 class WikitextContent extends TextContent {
479
480 public function __construct( $text ) {
481 parent::__construct($text, CONTENT_MODEL_WIKITEXT);
482 }
483
484 protected function getHtml( ) {
485 throw new MWException( "getHtml() not implemented for wikitext. Use getParserOutput()->getText()." );
486 }
487
488 /**
489 * Returns a ParserOutput object resulting from parsing the content's text using $wgParser.
490 *
491 * @since WikiData1
492 *
493 * @param IContextSource|null $context
494 * @param null $revId
495 * @param null|ParserOptions $options
496 * @param bool $generateHtml
497 *
498 * @return ParserOutput representing the HTML form of the text
499 */
500 public function getParserOutput( IContextSource $context, $revId = null, ParserOptions $options = null, $generateHtml = true ) {
501 global $wgParser;
502
503 if ( !$options ) {
504 $options = ParserOptions::newFromUserAndLang( $context->getUser(), $context->getLanguage() );
505 }
506
507 $po = $wgParser->parse( $this->mText, $context->getTitle(), $options, true, true, $revId );
508
509 return $po;
510 }
511
512 /**
513 * Returns the section with the given id.
514 *
515 * @param String $sectionId the section's id
516 * @return Content|false|null the section, or false if no such section exist, or null if sections are not supported
517 */
518 public function getSection( $section ) {
519 global $wgParser;
520
521 $text = $this->getNativeData();
522 $sect = $wgParser->getSection( $text, $section, false );
523
524 return new WikitextContent( $sect );
525 }
526
527 /**
528 * Replaces a section in the wikitext
529 *
530 * @param $section empty/null/false or a section number (0, 1, 2, T1, T2...), or "new"
531 * @param $with Content: new content of the section
532 * @param $sectionTitle String: new section's subject, only if $section is 'new'
533 * @return Content Complete article content, or null if error
534 */
535 public function replaceSection( $section, Content $with, $sectionTitle = '' ) {
536 wfProfileIn( __METHOD__ );
537
538 $myModelId = $this->getModel();
539 $sectionModelId = $with->getModel();
540
541 if ( $sectionModelId != $myModelId ) {
542 $myModelName = ContentHandler::getContentModelName( $myModelId );
543 $sectionModelName = ContentHandler::getContentModelName( $sectionModelId );
544
545 throw new MWException( "Incompatible content model for section: document uses $myModelId ($myModelName), "
546 . "section uses $sectionModelId ($sectionModelName)." );
547 }
548
549 $oldtext = $this->getNativeData();
550 $text = $with->getNativeData();
551
552 if ( $section === '' ) {
553 return $with; #XXX: copy first?
554 } if ( $section == 'new' ) {
555 # Inserting a new section
556 $subject = $sectionTitle ? wfMsgForContent( 'newsectionheaderdefaultlevel', $sectionTitle ) . "\n\n" : '';
557 if ( wfRunHooks( 'PlaceNewSection', array( $this, $oldtext, $subject, &$text ) ) ) {
558 $text = strlen( trim( $oldtext ) ) > 0
559 ? "{$oldtext}\n\n{$subject}{$text}"
560 : "{$subject}{$text}";
561 }
562 } else {
563 # Replacing an existing section; roll out the big guns
564 global $wgParser;
565
566 $text = $wgParser->replaceSection( $oldtext, $section, $text );
567 }
568
569 $newContent = new WikitextContent( $text );
570
571 wfProfileOut( __METHOD__ );
572 return $newContent;
573 }
574
575 /**
576 * Returns a new WikitextContent object with the given section heading prepended.
577 *
578 * @param $header String
579 * @return Content
580 */
581 public function addSectionHeader( $header ) {
582 $text = wfMsgForContent( 'newsectionheaderdefaultlevel', $header ) . "\n\n" . $this->getNativeData();
583
584 return new WikitextContent( $text );
585 }
586
587 /**
588 * Returns a Content object with pre-save transformations applied (or this object if no transformations apply).
589 *
590 * @param Title $title
591 * @param User $user
592 * @param ParserOptions $popts
593 * @return Content
594 */
595 public function preSaveTransform( Title $title, User $user, ParserOptions $popts ) {
596 global $wgParser, $wgConteLang;
597
598 $text = $this->getNativeData();
599 $pst = $wgParser->preSaveTransform( $text, $title, $user, $popts );
600
601 return new WikitextContent( $pst );
602 }
603
604 /**
605 * Returns a Content object with preload transformations applied (or this object if no transformations apply).
606 *
607 * @param Title $title
608 * @param ParserOptions $popts
609 * @return Content
610 */
611 public function preloadTransform( Title $title, ParserOptions $popts ) {
612 global $wgParser, $wgConteLang;
613
614 $text = $this->getNativeData();
615 $plt = $wgParser->getPreloadText( $text, $title, $popts );
616
617 return new WikitextContent( $plt );
618 }
619
620 public function getRedirectChain() {
621 $text = $this->getNativeData();
622 return Title::newFromRedirectArray( $text );
623 }
624
625 public function getRedirectTarget() {
626 $text = $this->getNativeData();
627 return Title::newFromRedirect( $text );
628 }
629
630 public function getUltimateRedirectTarget() {
631 $text = $this->getNativeData();
632 return Title::newFromRedirectRecurse( $text );
633 }
634
635 /**
636 * Returns true if this content is not a redirect, and this content's text is countable according to
637 * the criteria defiend by $wgArticleCountMethod.
638 *
639 * @param Bool $hasLinks if it is known whether this content contains links, provide this information here,
640 * to avoid redundant parsing to find out.
641 * @param IContextSource $context context for parsing if necessary
642 *
643 * @return bool true if the content is countable
644 */
645 public function isCountable( $hasLinks = null, IContextSource $context = null ) {
646 global $wgArticleCountMethod, $wgRequest;
647
648 if ( $this->isRedirect( ) ) {
649 return false;
650 }
651
652 $text = $this->getNativeData();
653
654 switch ( $wgArticleCountMethod ) {
655 case 'any':
656 return true;
657 case 'comma':
658 return strpos( $text, ',' ) !== false;
659 case 'link':
660 if ( $hasLinks === null ) { # not known, find out
661 if ( !$context ) { # make dummy context
662 //XXX: caller of this method often knows the title, but not a context...
663 $context = new RequestContext( $wgRequest );
664 }
665
666 $po = $this->getParserOutput( $context, null, null, false );
667 $links = $po->getLinks();
668 $hasLinks = !empty( $links );
669 }
670
671 return $hasLinks;
672 }
673 }
674
675 public function getTextForSummary( $maxlength = 250 ) {
676 $truncatedtext = parent::getTextForSummary( $maxlength );
677
678 #clean up unfinished links
679 #XXX: make this optional? wasn't there in autosummary, but required for deletion summary.
680 $truncatedtext = preg_replace( '/\[\[([^\]]*)\]?$/', '$1', $truncatedtext );
681
682 return $truncatedtext;
683 }
684
685 }
686
687 class MessageContent extends TextContent {
688 public function __construct( $msg_key, $params = null, $options = null ) {
689 parent::__construct(null, CONTENT_MODEL_WIKITEXT); #XXX: messages may be wikitext, html or plain text! and maybe even something else entirely.
690
691 $this->mMessageKey = $msg_key;
692
693 $this->mParameters = $params;
694
695 if ( is_null( $options ) ) {
696 $options = array();
697 }
698 elseif ( is_string( $options ) ) {
699 $options = array( $options );
700 }
701
702 $this->mOptions = $options;
703
704 $this->mHtmlOptions = null;
705 }
706
707 /**
708 * Returns the message as rendered HTML, using the options supplied to the constructor plus "parse".
709 */
710 protected function getHtml( ) {
711 $opt = array_merge( $this->mOptions, array('parse') );
712
713 return wfMsgExt( $this->mMessageKey, $this->mParameters, $opt );
714 }
715
716
717 /**
718 * Returns the message as raw text, using the options supplied to the constructor minus "parse" and "parseinline".
719 */
720 public function getNativeData( ) {
721 $opt = array_diff( $this->mOptions, array('parse', 'parseinline') );
722
723 return wfMsgExt( $this->mMessageKey, $this->mParameters, $opt );
724 }
725
726 }
727
728
729 class JavaScriptContent extends TextContent {
730 public function __construct( $text ) {
731 parent::__construct($text, CONTENT_MODEL_JAVASCRIPT);
732 }
733
734 protected function getHtml( ) {
735 $html = "";
736 $html .= "<pre class=\"mw-code mw-js\" dir=\"ltr\">\n";
737 $html .= htmlspecialchars( $this->getNativeData() );
738 $html .= "\n</pre>\n";
739
740 return $html;
741 }
742
743 }
744
745 class CssContent extends TextContent {
746 public function __construct( $text ) {
747 parent::__construct($text, CONTENT_MODEL_CSS);
748 }
749
750 protected function getHtml( ) {
751 $html = "";
752 $html .= "<pre class=\"mw-code mw-css\" dir=\"ltr\">\n";
753 $html .= htmlspecialchars( $this->getNativeData() );
754 $html .= "\n</pre>\n";
755
756 return $html;
757 }
758 }