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