Merge "Add .pipeline/ with dev image variant"

[lhc/web/wiklou.git] / includes / diff / SlotDiffRenderer.php

diff --git a/includes/diff/SlotDiffRenderer.php b/includes/diff/SlotDiffRenderer.php
index f20b416..c58502b 100644 (file)
--- a/includes/diff/SlotDiffRenderer.php
+++ b/includes/diff/SlotDiffRenderer.php
@@ -20,17 +20,18 @@
  * @file
  * @ingroup DifferenceEngine
  */
+use Wikimedia\Assert\Assert;
 
 /**
  * Renders a diff for a single slot (that is, a diff between two content objects).
  *
- * Callers should obtain this class by invoking ContentHandler::getSlotDiffRendererClass
+ * Callers should obtain instances of this class by invoking ContentHandler::getSlotDiffRenderer
  * on the content handler of the new content object (ie. the one shown on the right side
  * of the diff), or of the old one if the new one does not exist.
  *
  * The default implementation just does a text diff on the native text representation.
  * Content handler extensions can subclass this to provide a more appropriate diff method by
- * overriding ContentHandler::getSlotDiffRendererClass. Other extensions that want to interfere
+ * overriding ContentHandler::getSlotDiffRendererInternal. Other extensions that want to interfere
  * with diff generation in some way can use the GetSlotDiffRenderer hook.
  *
  * @ingroup DifferenceEngine
@@ -43,7 +44,7 @@ abstract class SlotDiffRenderer {
         * must have the same content model that was used to obtain this diff renderer.
         * @param Content|null $oldContent
         * @param Content|null $newContent
-        * @return string
+        * @return string HTML, one or more <tr> tags.
         */
        abstract public function getDiff( Content $oldContent = null, Content $newContent = null );
 
@@ -62,4 +63,35 @@ abstract class SlotDiffRenderer {
                return [];
        }
 
+       /**
+        * Helper method to normalize the input of getDiff().
+        * Verifies that at least one of $oldContent and $newContent is not null, verifies that
+        * they are instances of one of the allowed classes (if provided), and replaces null with
+        * empty content.
+        * @param Content|null &$oldContent
+        * @param Content|null &$newContent
+        * @param string|array|null $allowedClasses
+        */
+       protected function normalizeContents(
+               Content &$oldContent = null, Content &$newContent = null, $allowedClasses = null
+       ) {
+               if ( !$oldContent && !$newContent ) {
+                       throw new InvalidArgumentException( '$oldContent and $newContent cannot both be null' );
+               }
+
+               if ( $allowedClasses ) {
+                       if ( is_array( $allowedClasses ) ) {
+                               $allowedClasses = implode( '|', $allowedClasses );
+                       }
+                       Assert::parameterType( $allowedClasses . '|null', $oldContent, '$oldContent' );
+                       Assert::parameterType( $allowedClasses . '|null', $newContent, '$newContent' );
+               }
+
+               if ( !$oldContent ) {
+                       $oldContent = $newContent->getContentHandler()->makeEmptyContent();
+               } elseif ( !$newContent ) {
+                       $newContent = $oldContent->getContentHandler()->makeEmptyContent();
+               }
+       }
+
 }