Rename HTMLForm::[get|set|add]*Text() methods

Rename HTMLForm::[get|set|add][Pre|Post|Header|Footer]Text() to
HTMLForm::[get|set|add][Pre|Post|Header|Footer]Html() and
deprecate the old methods. Their arguments are rendered as raw
HTML so the old name was misleading.

Some of these are marked as stable to override and theoretically
the renaming could cause problems if callers are updated to the
new name while the overriding class is still using the old name,
but the only case known to codesearch is OOUIHTMLForm which is
also updated here.

Bug: T290771
Change-Id: I2c269eb6ab2b320fa2eef4ee8a226e96ad05fbe2

4 files changed, 213 insertions, 49 deletions

diff --git a/RELEASE-NOTES-1.38 b/RELEASE-NOTES-1.38
index 8784f5f33c8f..9a721ae03eae 100644
--- a/RELEASE-NOTES-1.38
+++ b/RELEASE-NOTES-1.38
@@ -399,6 +399,12 @@ because of Phabricator reports.
   `updateAriaExpanded` in checkboxHack.js have been deprecated.
   `bindToggleOnSpaceEnter` has also been deprecated in favor of
   `bindToggleOnEnter`.
+* The HTMLForm methods getPreText, setPreText, addPreText, getPostText,
+  setPostText, addPostText, getHeaderText, setHeaderText, addHeaderText,
+  getFooterText, setFooterText and addFooterText have been renamed to
+  getPreHtml, setPreHtml, addPreHtml, getPostHtml, setPostHtml, addPostHtml,
+  getHeaderHtml, setHeaderHtml, addHeaderHtml, getFooterHtml, setFooterHtml
+  and addFooterHtml respectively.
 * …
 
 === Other changes in 1.38 ===
diff --git a/includes/htmlform/HTMLForm.php b/includes/htmlform/HTMLForm.php
index d393a687b62c..738d661fc7b1 100644
--- a/includes/htmlform/HTMLForm.php
+++ b/includes/htmlform/HTMLForm.php
@@ -780,25 +780,60 @@ class HTMLForm extends ContextSource {
 	 * @param string $msg Complete text of message to display
 	 *
 	 * @return HTMLForm $this for chaining calls (since 1.20)
+	 * @deprecated since 1.38, use setPreHtml() instead
 	 */
 	public function setIntro( $msg ) {
-		$this->setPreText( $msg );
+		return $this->setPreHtml( $msg );
+	}
+
+	/**
+	 * Set the introductory message HTML, overwriting any existing message.
+	 *
+	 * @param string $html Complete HTML of message to display
+	 *
+	 * @since 1.38
+	 * @return $this for chaining calls
+	 */
+	public function setPreHtml( $html ) {
+		$this->mPre = $html;
 
 		return $this;
 	}
 
 	/**
+	 * Add HTML to introductory message.
+	 *
+	 * @param string $html Complete HTML of message to display
+	 *
+	 * @since 1.38
+	 * @return $this for chaining calls
+	 */
+	public function addPreHtml( $html ) {
+		$this->mPre .= $html;
+
+		return $this;
+	}
+
+	/**
+	 * Get the introductory message HTML.
+	 *
+	 * @since 1.38
+	 * @return string
+	 */
+	public function getPreHtml() {
+		return $this->mPre;
+	}
+
+	/**
 	 * Set the introductory message HTML, overwriting any existing message.
-	 * @since 1.19
 	 *
 	 * @param string $msg Complete HTML of message to display
 	 *
 	 * @return HTMLForm $this for chaining calls (since 1.20)
+	 * @deprecated since 1.38, use setPreHtml() instead
 	 */
 	public function setPreText( $msg ) {
-		$this->mPre = $msg;
-
-		return $this;
+		return $this->setPreHtml( $msg );
 	}
 
 	/**
@@ -807,73 +842,73 @@ class HTMLForm extends ContextSource {
 	 * @param string $msg Complete HTML of message to display
 	 *
 	 * @return HTMLForm $this for chaining calls (since 1.20)
+	 * @deprecated since 1.38, use addPreHtml() instead
 	 */
 	public function addPreText( $msg ) {
-		$this->mPre .= $msg;
-
-		return $this;
+		return $this->addPreHtml( $msg );
 	}
 
 	/**
 	 * Get the introductory message HTML.
 	 *
 	 * @since 1.32
-	 *
 	 * @return string
+	 * @deprecated since 1.38, use getPreHtml() instead
 	 */
 	public function getPreText() {
-		return $this->mPre;
+		return $this->getPreHtml();
 	}
 
 	/**
 	 * Add HTML to the header, inside the form.
 	 *
-	 * @param string $msg Additional HTML to display in header
+	 * @param string $html Additional HTML to display in header
 	 * @param string|null $section The section to add the header to
 	 *
-	 * @return HTMLForm $this for chaining calls (since 1.20)
+	 * @since 1.38
+	 * @return $this for chaining calls
 	 */
-	public function addHeaderText( $msg, $section = null ) {
+	public function addHeaderHtml( $html, $section = null ) {
 		if ( $section === null ) {
-			$this->mHeader .= $msg;
+			$this->mHeader .= $html;
 		} else {
 			if ( !isset( $this->mSectionHeaders[$section] ) ) {
 				$this->mSectionHeaders[$section] = '';
 			}
-			$this->mSectionHeaders[$section] .= $msg;
+			$this->mSectionHeaders[$section] .= $html;
 		}
 
 		return $this;
 	}
 
 	/**
-	 * Set header text, inside the form.
-	 * @since 1.19
+	 * Set header HTML, inside the form.
 	 *
-	 * @param string $msg Complete HTML of header to display
+	 * @param string $html Complete HTML of header to display
 	 * @param string|null $section The section to add the header to
 	 *
-	 * @return HTMLForm $this for chaining calls (since 1.20)
+	 * @since 1.38
+	 * @return $this for chaining calls
 	 */
-	public function setHeaderText( $msg, $section = null ) {
+	public function setHeaderHtml( $html, $section = null ) {
 		if ( $section === null ) {
-			$this->mHeader = $msg;
+			$this->mHeader = $html;
 		} else {
-			$this->mSectionHeaders[$section] = $msg;
+			$this->mSectionHeaders[$section] = $html;
 		}
 
 		return $this;
 	}
 
 	/**
-	 * Get header text.
+	 * Get header HTML.
 	 * @stable to override
 	 *
 	 * @param string|null $section The section to get the header text for
-	 * @since 1.26
+	 * @since 1.38
 	 * @return string HTML
 	 */
-	public function getHeaderText( $section = null ) {
+	public function getHeaderHtml( $section = null ) {
 		if ( $section === null ) {
 			return $this->mHeader;
 		} else {
@@ -882,53 +917,94 @@ class HTMLForm extends ContextSource {
 	}
 
 	/**
-	 * Add footer text, inside the form.
+	 * Add HTML to the header, inside the form.
 	 *
-	 * @param string $msg Complete text of message to display
-	 * @param string|null $section The section to add the footer text to
+	 * @param string $msg Additional HTML to display in header
+	 * @param string|null $section The section to add the header to
 	 *
 	 * @return HTMLForm $this for chaining calls (since 1.20)
+	 * @deprecated since 1.38, use addHeaderHtml() instead
 	 */
-	public function addFooterText( $msg, $section = null ) {
+	public function addHeaderText( $msg, $section = null ) {
+		return $this->addHeaderHtml( $msg, $section );
+	}
+
+	/**
+	 * Set header text, inside the form.
+	 *
+	 * @param string $msg Complete HTML of header to display
+	 * @param string|null $section The section to add the header to
+	 *
+	 * @since 1.19
+	 * @return HTMLForm $this for chaining calls (since 1.20)
+	 * @deprecated since 1.38, use setHeaderHtml() instead
+	 */
+	public function setHeaderText( $msg, $section = null ) {
+		return $this->setHeaderHtml( $msg, $section );
+	}
+
+	/**
+	 * Get header text.
+	 * @stable to override
+	 *
+	 * @param string|null $section The section to get the header text for
+	 * @since 1.26
+	 * @return string HTML
+	 * @deprecated since 1.38, use getHeaderHtml() instead
+	 */
+	public function getHeaderText( $section = null ) {
+		return $this->getHeaderHtml( $section );
+	}
+
+	/**
+	 * Add footer HTML, inside the form.
+	 *
+	 * @param string $html Complete text of message to display
+	 * @param string|null $section The section to add the footer text to
+	 *
+	 * @since 1.38
+	 * @return $this for chaining calls
+	 */
+	public function addFooterHtml( $html, $section = null ) {
 		if ( $section === null ) {
-			$this->mFooter .= $msg;
+			$this->mFooter .= $html;
 		} else {
 			if ( !isset( $this->mSectionFooters[$section] ) ) {
 				$this->mSectionFooters[$section] = '';
 			}
-			$this->mSectionFooters[$section] .= $msg;
+			$this->mSectionFooters[$section] .= $html;
 		}
 
 		return $this;
 	}
 
 	/**
-	 * Set footer text, inside the form.
-	 * @since 1.19
+	 * Set footer HTML, inside the form.
 	 *
-	 * @param string $msg Complete text of message to display
+	 * @param string $html Complete text of message to display
 	 * @param string|null $section The section to add the footer text to
 	 *
-	 * @return HTMLForm $this for chaining calls (since 1.20)
+	 * @since 1.38
+	 * @return $this for chaining calls
 	 */
-	public function setFooterText( $msg, $section = null ) {
+	public function setFooterHtml( $html, $section = null ) {
 		if ( $section === null ) {
-			$this->mFooter = $msg;
+			$this->mFooter = $html;
 		} else {
-			$this->mSectionFooters[$section] = $msg;
+			$this->mSectionFooters[$section] = $html;
 		}
 
 		return $this;
 	}
 
 	/**
-	 * Get footer text.
+	 * Get footer HTML.
 	 *
 	 * @param string|null $section The section to get the footer text for
-	 * @since 1.26
+	 * @since 1.38
 	 * @return string
 	 */
-	public function getFooterText( $section = null ) {
+	public function getFooterHtml( $section = null ) {
 		if ( $section === null ) {
 			return $this->mFooter;
 		} else {
@@ -937,29 +1013,104 @@ class HTMLForm extends ContextSource {
 	}
 
 	/**
-	 * Add text to the end of the display.
+	 * Add footer text, inside the form.
 	 *
 	 * @param string $msg Complete text of message to display
+	 * @param string|null $section The section to add the footer text to
 	 *
 	 * @return HTMLForm $this for chaining calls (since 1.20)
+	 * @deprecated since 1.38, use addFooterHtml() instead
 	 */
-	public function addPostText( $msg ) {
-		$this->mPost .= $msg;
+	public function addFooterText( $msg, $section = null ) {
+		return $this->addFooterHtml( $msg, $section );
+	}
+
+	/**
+	 * Set footer text, inside the form.
+	 * @since 1.19
+	 *
+	 * @param string $msg Complete text of message to display
+	 * @param string|null $section The section to add the footer text to
+	 *
+	 * @return HTMLForm $this for chaining calls (since 1.20)
+	 * @deprecated since 1.38, use setFooterHtml() instead
+	 */
+	public function setFooterText( $msg, $section = null ) {
+		return $this->setFooterHtml( $msg, $section );
+	}
+
+	/**
+	 * Get footer text.
+	 *
+	 * @param string|null $section The section to get the footer text for
+	 * @since 1.26
+	 * @return string
+	 * @deprecated since 1.38, use getFooterHtml() instead
+	 */
+	public function getFooterText( $section = null ) {
+		return $this->getFooterHtml( $section );
+	}
+
+	/**
+	 * Add HTML to the end of the display.
+	 *
+	 * @param string $html Complete text of message to display
+	 *
+	 * @since 1.38
+	 * @return $this for chaining calls
+	 */
+	public function addPostHtml( $html ) {
+		$this->mPost .= $html;
+
+		return $this;
+	}
+
+	/**
+	 * Set HTML at the end of the display.
+	 *
+	 * @param string $html Complete text of message to display
+	 *
+	 * @since 1.38
+	 * @return $this for chaining calls
+	 */
+	public function setPostHtml( $html ) {
+		$this->mPost = $html;
 
 		return $this;
 	}
 
 	/**
+	 * Get HTML at the end of the display.
+	 *
+	 * @since 1.38
+	 * @return string HTML
+	 */
+	public function getPostHtml() {
+		return $this->mPost;
+	}
+
+	/**
+	 * Add text to the end of the display.
+	 *
+	 * @param string $msg Complete text of message to display
+	 *
+	 * @return HTMLForm $this for chaining calls (since 1.20)
+	 * @deprecated since 1.38, use addPostHtml() instead
+	 */
+	public function addPostText( $msg ) {
+		return $this->addPostHtml( $msg );
+	}
+
+	/**
 	 * Set text at the end of the display.
 	 *
 	 * @param string $msg Complete text of message to display
 	 *
 	 * @return HTMLForm $this for chaining calls (since 1.20)
+	 * @deprecated since 1.38, use setPostHtml() instead
 	 */
 	public function setPostText( $msg ) {
-		$this->mPost = $msg;
-
-		return $this;
+		return $this->setPostHtml( $msg );
 	}
 
 	/**
diff --git a/includes/htmlform/OOUIHTMLForm.php b/includes/htmlform/OOUIHTMLForm.php
index 094551c0fefc..3c3c5dc3541e 100644
--- a/includes/htmlform/OOUIHTMLForm.php
+++ b/includes/htmlform/OOUIHTMLForm.php
@@ -238,12 +238,12 @@ class OOUIHTMLForm extends HTMLForm {
 		return '';
 	}
 
-	public function getHeaderText( $section = null ) {
+	public function getHeaderHtml( $section = null ) {
 		if ( $section === null ) {
 			// We handle $this->mHeader elsewhere, in getBody()
 			return '';
 		} else {
-			return parent::getHeaderText( $section );
+			return parent::getHeaderHtml( $section );
 		}
 	}
 
diff --git a/tests/phpunit/includes/htmlform/HTMLFormTest.php b/tests/phpunit/includes/htmlform/HTMLFormTest.php
index efb753e842e0..99a24c737605 100644
--- a/tests/phpunit/includes/htmlform/HTMLFormTest.php
+++ b/tests/phpunit/includes/htmlform/HTMLFormTest.php
@@ -62,6 +62,13 @@ class HTMLFormTest extends MediaWikiIntegrationTestCase {
 		$this->assertSame( $preText, $form->getPreText() );
 	}
 
+	public function testGetPreHtml() {
+		$preHtml = 'TEST';
+		$form = $this->newInstance();
+		$form->setPreHtml( $preHtml );
+		$this->assertSame( $preHtml, $form->getPreHtml() );
+	}
+
 	public function testGetErrorsOrWarningsWithRawParams() {
 		$form = $this->newInstance();
 		$msg = new RawMessage( 'message with $1' );