Introduce ContentAlterParserOutput hook

This hook is the counterpart of ContentGetParserOutput: it gives
high-level access to the parsing of a content object (as opposed
to lower-level parser hooks like ParserBefore*/ParserAfter* which
are called for all kinds of non-content input like interface
messages and don't have the necessary context to know what kind of
input is being parsed), but it is called when the parsing has
already finished.

The intention is to provide a convenient location for ParserOutput
modifications which depend on some global property of the parsed
content, but need to happen before LinksUpdate. Currently there are
no hooks between parsing (initiated by WikiPage::doEditUpdates()
calling WikiPage::prepareContentForEdit()) and updating the link
tables (initiated by the same method calling
Content::getSecondaryDataUpdates()), so any hook an extension would
try to use would face one of the following problems:
* the parsing output is not available yet
* LinksUpdate has run already, modifying list properties is unsafe
* there is not enough context to tell what's being parsed

A typical use of this hook would be to add tracking categories when
something is missing from the text (e.g. there are no references).
For the concrete use case, see I43ed79b6a54cd31820ecae8139e29c5880f5dd1b

Alternative approaches that have been suggested and do not require
a new hook but are not robust / do not rely on a clear contract:
* use ParserAfterTidy or a similar hook, assume that the input
  being parsed is the main page content iff limit reporting is
  enabled
* use ParserAfterTidy or a similar hook, assume that the input
  being parsed is the main page content iff
  ParserOptions::getInterfaceMessage() is false (this would yield
  some false positives, but in those cases adding a tracking
  category would probably have no effect)

Change-Id: I685b285fcc772382993116f7822a832eeecc0681

diff --git a/RELEASE-NOTES-1.25 b/RELEASE-NOTES-1.25
index 22033cf..2a6d951 100644 (file)
--- a/RELEASE-NOTES-1.25
+++ b/RELEASE-NOTES-1.25
@@ -13,6 +13,8 @@ production.
 === New features in 1.25 ===
 * (bug 58139) ResourceLoaderFileModule now supports language fallback
   for 'languageScripts'.
+* Added a new hook, "ContentAlterParserOutput", to allow extensions to modify the
+  parser output for a content object before links update.
 
 === Bug fixes in 1.25 ===
 

diff --git a/docs/hooks.txt b/docs/hooks.txt
index 51da2d4..d862983 100644 (file)
--- a/docs/hooks.txt
+++ b/docs/hooks.txt
@@ -912,6 +912,15 @@ generation of HTML may be skipped, but other information should still be present
 ParserOutput object.
 &$output: ParserOutput, to manipulate or replace
 
+'ContentAlterParserOutput': Modify parser output for a given content object.
+Called by Content::getParserOutput after parsing has finished. Can be used
+for changes that depend on the result of the parsing but have to be done
+before LinksUpdate is called (such as adding tracking categories based on
+the rendered HTML).
+$content: The Content to render
+$title: Title of the page, as context
+$parserOutput: ParserOutput to manipulate
+
 'ConvertContent': Called by AbstractContent::convert when a conversion to another
 content model is requested.
 $content: The Content object to be converted.

diff --git a/includes/content/AbstractContent.php b/includes/content/AbstractContent.php
index 9d257a6..cb39fac 100644 (file)
--- a/includes/content/AbstractContent.php
+++ b/includes/content/AbstractContent.php
@@ -491,6 +491,8 @@ abstract class AbstractContent implements Content {
                        $options->setRedirectTarget( $oldRedir );
                }
 
+               wfRunHooks( 'ContentAlterParserOutput', array( $this, $title, $po ) );
+
                return $po;
        }