* type), but wikitext content may be represented by a DOM or AST structure in
* the future.
*
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ * http://www.gnu.org/copyleft/gpl.html
+ *
* @since 1.21
+ *
+ * @file
+ * @ingroup Content
+ *
+ * @author Daniel Kinzler
*/
abstract class ContentHandler {
+ /**
+ * Switch for enabling deprecation warnings. Used by ContentHandler::deprecated()
+ * and ContentHandler::runLegacyHooks().
+ *
+ * Once the ContentHandler code has settled in a bit, this should be set to true to
+ * make extensions etc. show warnings when using deprecated functions and hooks.
+ */
+ protected static $enableDeprecationWarnings = false;
+
/**
* Convenience function for getting flat text from a Content object. This
* should only be used in the context of backwards compatibility with code
* - otherwise, the behaviour is undefined.
*
* @since 1.21
- * @deprecated since 1.21. Always try to use the content object.
*
* @static
* @param $content Content|null
wfRunHooks( 'ContentHandlerForModelID', array( $modelId, &$handler ) );
if ( $handler === null ) {
- throw new MWException( "No handler for model #$modelId registered in \$wgContentHandlers" );
+ throw new MWException( "No handler for model '$modelId'' registered in \$wgContentHandlers" );
}
if ( !( $handler instanceof ContentHandler ) ) {
/**
* Returns true for content models that support caching using the
- * ParserCache mechanism. See WikiPage::isParserCacheUser().
+ * ParserCache mechanism. See WikiPage::isParserCacheUsed().
*
* @since 1.21
*
* @return bool
*/
public function isParserCacheSupported() {
- return true;
+ return false;
}
/**
return false;
}
+ /**
+ * Logs a deprecation warning, visible if $wgDevelopmentWarnings, but only if
+ * self::$enableDeprecationWarnings is set to true.
+ *
+ * @param String $func The name of the deprecated function
+ * @param string $version The version since the method is deprecated. Usually 1.21
+ * for ContentHandler related stuff.
+ * @param String|bool $component: Component to which the function belongs.
+ * If false, it is assumed the function is in MediaWiki core.
+ *
+ * @see ContentHandler::$enableDeprecationWarnings
+ * @see wfDeprecated
+ */
+ public static function deprecated( $func, $version, $component = false ) {
+ if ( self::$enableDeprecationWarnings ) {
+ wfDeprecated( $func, $version, $component, 3 );
+ }
+ }
+
/**
* Call a legacy hook that uses text instead of Content objects.
* Will log a warning when a matching hook function is registered.
*
* @param $event String: event name
* @param $args Array: parameters passed to hook functions
- * @param $warn bool: whether to log a warning (default: true). Should generally be true,
- * may be set to false for testing.
+ * @param $warn bool: whether to log a warning.
+ * Default to self::$enableDeprecationWarnings.
+ * May be set to false for testing.
*
* @return Boolean True if no handler aborted the hook
+ *
+ * @see ContentHandler::$enableDeprecationWarnings
*/
- public static function runLegacyHooks( $event, $args = array(), $warn = true ) {
+ public static function runLegacyHooks( $event, $args = array(),
+ $warn = null ) {
+
+ if ( $warn === null ) {
+ $warn = self::$enableDeprecationWarnings;
+ }
+
if ( !Hooks::isRegistered( $event ) ) {
return true; // nothing to do here
}
if ( $warn ) {
- wfWarn( "Using obsolete hook $event" );
+ // Log information about which handlers are registered for the legacy hook,
+ // so we can find and fix them.
+
+ $handlers = Hooks::getHandlers( $event );
+ $handlerInfo = array();
+
+ wfSuppressWarnings();
+
+ foreach ( $handlers as $handler ) {
+ $info = '';
+
+ if ( is_array( $handler ) ) {
+ if ( is_object( $handler[0] ) ) {
+ $info = get_class( $handler[0] );
+ } else {
+ $info = $handler[0];
+ }
+
+ if ( isset( $handler[1] ) ) {
+ $info .= '::' . $handler[1];
+ }
+ } else if ( is_object( $handler ) ) {
+ $info = get_class( $handler[0] );
+ $info .= '::on' . $event;
+ } else {
+ $info = $handler;
+ }
+
+ $handlerInfo[] = $info;
+ }
+
+ wfRestoreWarnings();
+
+ wfWarn( "Using obsolete hook $event via ContentHandler::runLegacyHooks()! Handlers: " . implode(', ', $handlerInfo), 2 );
}
// convert Content objects to text
/**
* @since 1.21
*/
-abstract class TextContentHandler extends ContentHandler {
+class TextContentHandler extends ContentHandler {
- public function __construct( $modelId, $formats ) {
+ public function __construct( $modelId = CONTENT_MODEL_TEXT, $formats = array( CONTENT_FORMAT_TEXT ) ) {
parent::__construct( $modelId, $formats );
}
return $mergedContent;
}
+ /**
+ * Unserializes a Content object of the type supported by this ContentHandler.
+ *
+ * @since 1.21
+ *
+ * @param $text string serialized form of the content
+ * @param $format null|String the format used for serialization
+ *
+ * @return Content the TextContent object wrapping $text
+ */
+ public function unserializeContent( $text, $format = null ) {
+ $this->checkFormat( $format );
+
+ return new TextContent( $text );
+ }
+
+ /**
+ * Creates an empty TextContent object.
+ *
+ * @since 1.21
+ *
+ * @return Content
+ */
+ public function makeEmptyContent() {
+ return new TextContent( '' );
+ }
}
/**
public function supportsSections() {
return true;
}
+
+ /**
+ * Returns true, because wikitext supports caching using the
+ * ParserCache mechanism.
+ *
+ * @since 1.21
+ * @return bool
+ */
+ public function isParserCacheSupported() {
+ return true;
+ }
}
# XXX: make ScriptContentHandler base class, do highlighting stuff there?