includes/ContentHandler.php

   1 <?php
   2
   3 /**
   4  * A content handler knows how do deal with a specific type of content on a wiki page.
   5  * Content is stored in the database in a serialized form (using a serialization format aka mime type)
   6  * and is be unserialized into it's native PHP represenation (the content model).
   7  *
   8  * Some content types have a flat model, that is, their native represenation is the
   9  * same as their serialized form. Examples would be JavaScript and CSS code. As of now,
  10  * this also applies to wikitext (mediawiki's default content type), but wikitext
  11  * content may be represented by a DOM or AST structure in the future.
  12  *
  13  */
  14 abstract class ContentHandler {
  15
  16     public static function getContentText( Content $content ) {
  17         if ( !$content ) return '';
  18
  19         if ( $content instanceof TextContent ) {
  20             #XXX: or check by model name?
  21             #XXX: or define $content->allowRawData()?
  22             #XXX: or define $content->getDefaultWikiText()?
  23             return $content->getRawData();
  24         }
  25
  26         #XXX: this must not be used for editing, otherwise we may loose data:
  27         #XXX:      e.g. if this returns the "main" text from a multipart page, all attachments would be lost
  28
  29         return null;
  30     }
  31
  32     public static function makeContent( $text, Title $title, $modelName = null, $format = null ) {
  33         if ( !$modelName ) {
  34             $modelName = $title->getContentModelName();
  35         }
  36
  37         $handler = ContentHandler::getForModelName( $modelName );
  38         return $handler->unserialize( $text, $format );
  39     }
  40
  41     public static function getDefaultModelFor( Title $title ) {
  42         global $wgNamespaceContentModels;
  43
  44         # NOTE: this method must not rely on $title->getContentModelName() directly or indirectly,
  45         #       because it is used to initialized the mContentModelName memebr.
  46
  47         $ns = $title->getNamespace();
  48
  49         $ext = false;
  50         $m = null;
  51         $model = null;
  52
  53         if ( !empty( $wgNamespaceContentModels[ $ns ] ) ) {
  54             $model = $wgNamespaceContentModels[ $ns ];
  55         }
  56
  57         # hook can determin default model
  58         if ( !wfRunHooks( 'DefaultModelFor', array( $title, &$model ) ) ) { #FIXME: document new hook!
  59             if ( $model ) return $model;
  60         }
  61
  62         # Could this page contain custom CSS or JavaScript, based on the title?
  63         $isCssOrJsPage = ( NS_MEDIAWIKI == $ns && preg_match( "!\.(css|js)$!u", $title->getText(), $m ) );
  64         if ( $isCssOrJsPage ) $ext = $m[1];
  65
  66         # hook can force js/css
  67         wfRunHooks( 'TitleIsCssOrJsPage', array( $title, &$isCssOrJsPage, &$ext ) ); #FIXME: add $ext to hook interface spec
  68
  69         # Is this a .css subpage of a user page?
  70         $isJsCssSubpage = ( NS_USER == $ns && !$isCssOrJsPage && preg_match( "/\\/.*\\.(js|css)$/", $title->getText(), $m ) );
  71         if ( $isJsCssSubpage ) $ext = $m[1];
  72
  73         # is this wikitext, according to $wgNamespaceContentModels or the DefaultModelFor hook?
  74         $isWikitext = ( $model == CONTENT_MODEL_WIKITEXT || $model === null );
  75         $isWikitext = ( $isWikitext && !$isCssOrJsPage && !$isJsCssSubpage );
  76
  77         # hook can override $isWikitext
  78         wfRunHooks( 'TitleIsWikitextPage', array( $title, &$isWikitext ) );
  79
  80         if ( !$isWikitext ) {
  81
  82             if ( $ext == 'js' )
  83                 return CONTENT_MODEL_JAVASCRIPT;
  84             else if ( $ext == 'css' )
  85                 return CONTENT_MODEL_CSS;
  86
  87             if ( $model )
  88                 return $model;
  89             else
  90                 return CONTENT_MODEL_TEXT;
  91         }
  92
  93         # we established that is must be wikitext
  94         return CONTENT_MODEL_WIKITEXT;
  95     }
  96
  97     public static function getForTitle( Title $title ) {
  98         $modelName = $title->getContentModelName();
  99         return ContentHandler::getForModelName( $modelName );
 100     }
 101
 102     public static function getForContent( Content $content ) {
 103         $modelName = $content->getModelName();
 104         return ContentHandler::getForModelName( $modelName );
 105     }
 106
 107     public static function getForModelName( $modelName ) {
 108         global $wgContentHandlers;
 109
 110         if ( empty( $wgContentHandlers[$modelName] ) ) {
 111             #FIXME: hook here!
 112             throw new MWException( "No handler for model $modelName registered in \$wgContentHandlers" );
 113         }
 114
 115         if ( is_string( $wgContentHandlers[$modelName] ) ) {
 116             $class = $wgContentHandlers[$modelName];
 117             $wgContentHandlers[$modelName] = new $class( $modelName );
 118         }
 119
 120         return $wgContentHandlers[$modelName];
 121     }
 122
 123     # ----------------------------------------------------------------------------------------------------------
 124     public function __construct( $modelName, $formats ) {
 125         $this->mModelName = $modelName;
 126         $this->mSupportedFormats = $formats;
 127     }
 128
 129     public function getModelName() {
 130         # for wikitext: wikitext; in the future: wikiast, wikidom?
 131         # for wikidata: wikidata
 132         return $this->mModelName;
 133     }
 134
 135
 136     public function getSupportedFormats() {
 137         # for wikitext: "text/x-mediawiki-1", "text/x-mediawiki-2", etc
 138         # for wikidata: "application/json", "application/x-php", etc
 139         return $this->mSupportedFormats;
 140     }
 141
 142     public function getDefaultFormat() {
 143         return $this->mSupportedFormats[0];
 144     }
 145
 146     public abstract function serialize( Content $content, $format = null );
 147
 148     public abstract function unserialize( $blob, $format = null );
 149
 150     public abstract function emptyContent();
 151
 152     # public abstract function doPreSaveTransform( $title, $obj ); #TODO...
 153
 154     /**
 155      * Return an Article object suitable for viewing the given object
 156      *
 157      * NOTE: does *not* do special handling for Image and Category pages!
 158      *       Use Article::newFromTitle() for that!
 159      *
 160      * @param type $title
 161      * @return \Article
 162      * @todo Article is being refactored into an action class, keep track of that
 163      */
 164     public function createArticle( Title $title ) {
 165         #XXX: assert that $title->getContentModelName() == $this->getModelname()?
 166         $article = new Article($title);
 167         return $article;
 168     }
 169
 170     /**
 171      * Return an EditPage object suitable for editing the given object
 172      *
 173      * @param type $article
 174      * @return \EditPage
 175      */
 176     public function createEditPage( Article $article ) {
 177         #XXX: assert that $article->getContentObject()->getModelName() == $this->getModelname()?
 178         $editPage = new EditPage( $article );
 179         return $editPage;
 180     }
 181
 182     /**
 183      * Return an ExternalEdit object suitable for editing the given object
 184      *
 185      * @param type $article
 186      * @return \ExternalEdit
 187      */
 188     public function createExternalEdit( IContextSource $context ) {
 189         #XXX: assert that $article->getContentObject()->getModelName() == $this->getModelname()?
 190         $externalEdit = new ExternalEdit( $context );
 191         return $externalEdit;
 192     }
 193
 194     /**
 195     public function updatePage( $title, $obj ) {
 196     }
 197     **/
 198
 199     public function getDiffEngine( Article $article ) {
 200         $de = new DifferenceEngine( $article->getContext() );
 201         return $de;
 202     }
 203
 204     /**
 205      * attempts to merge differences between three versions.
 206      * Returns a new Content object for a clean merge and false for failure or a conflict.
 207      *
 208      * This default implementation always returns false.
 209      *
 210      * @param $oldContent String
 211      * @param $myContent String
 212      * @param $yourContent String
 213      * @return Content|Bool
 214      */
 215     public function merge3( Content $oldContent, Content $myContent, Content $yourContent ) {
 216         return false;
 217     }
 218
 219     #TODO: cover patch/undo just like merge3.
 220
 221     #TODO: how to handle extra message for JS/CSS previews??
 222     #TODO: Article::showCssOrJsPage ---> specialized classes!
 223
 224     #XXX: ImagePage and CategoryPage... wrappers that use ContentHandler? or ContentHandler creates wrappers?
 225 }
 226
 227
 228 abstract class TextContentHandler extends ContentHandler {
 229
 230     public function __construct( $modelName, $formats ) {
 231         parent::__construct( $modelName, $formats );
 232     }
 233
 234     public function serialize( Content $content, $format = null ) {
 235         #FIXME: assert format
 236         return $content->getRawData();
 237     }
 238
 239     /**
 240      * attempts to merge differences between three versions.
 241      * Returns a new Content object for a clean merge and false for failure or a conflict.
 242      *
 243      * This text-based implementation uses wfMerge().
 244      *
 245      * @param $oldContent String
 246      * @param $myContent String
 247      * @param $yourContent String
 248      * @return Content|Bool
 249      */
 250     public function merge3( Content $oldContent, Content $myContent, Content $yourContent ) {
 251         $format = $this->getDefaultFormat();
 252
 253         $old = $this->serialize( $oldContent, $format );
 254         $mine = $this->serialize( $myContent, $format );
 255         $yours = $this->serialize( $yourContent, $format );
 256
 257         $ok = wfMerge( $old, $mine, $yours, $result );
 258
 259         if ( !$ok ) return false;
 260         if ( !$result ) return $this->emptyContent();
 261
 262         $mergedContent = $this->unserialize( $result, $format );
 263         return $mergedContent;
 264     }
 265
 266
 267 }
 268 class WikitextContentHandler extends TextContentHandler {
 269
 270     public function __construct( $modelName = CONTENT_MODEL_WIKITEXT ) {
 271         parent::__construct( $modelName, array( 'application/x-wikitext' ) ); #FIXME: mime
 272     }
 273
 274     public function unserialize( $text, $format = null ) {
 275         #FIXME: assert format
 276         return new WikitextContent($text);
 277     }
 278
 279     public function emptyContent() {
 280         return new WikitextContent("");
 281     }
 282
 283 }
 284
 285 class JavaScriptContentHandler extends TextContentHandler {
 286
 287     public function __construct( $modelName = CONTENT_MODEL_WIKITEXT ) {
 288         parent::__construct( $modelName, array( 'text/javascript' ) );
 289     }
 290
 291     public function unserialize( $text, $format = null ) {
 292         return new JavaScriptContent($text);
 293     }
 294
 295     public function emptyContent() {
 296         return new JavaScriptContent("");
 297     }
 298 }
 299
 300 class CssContentHandler extends TextContentHandler {
 301
 302     public function __construct( $modelName = CONTENT_MODEL_WIKITEXT ) {
 303         parent::__construct( $modelName, array( 'text/css' ) );
 304     }
 305
 306     public function unserialize( $text, $format = null ) {
 307         return new CssContent($text);
 308     }
 309
 310     public function emptyContent() {
 311         return new CssContent("");
 312     }
 313
 314 }