Remove getForm() and replace by getFormInformation()

This commit removes SimpleCaptcha::getForm() and replaces it by its more informative
counterpart getFormInformation(), which returns an array, which provides some
more information about the form than only the html.

The information included in the array is:
 * html: The HTML of the CAPTCHA form (this is the same as what you expected from
   getForm() previously)
 * modules: ResourceLoader modules, if any, that should be added to the output of the
   page
 * modulestyles: ResourceLoader style modules, if any, that should be added to th
   output of the page
 * headitems: Head items that should be added to the output (see OutputPage::addHeadItems)

Mostly you shouldn't need to handle the response of getFormInformation() anymore, as there's
a new function, addFormToOutput(), which takes an instance of OutputPage as a first parameter
and handles the response of getFormInformation for you (adds all information to the given
OutputPage instance, if they're provided).

Bug: T141300
Depends-On: I433afd124b57526caa13a540cda48ba2b99a9bde
Change-Id: I25f344538052fc18993c43185fbd97804a7cfc81

FancyCaptcha/FancyCaptcha.class.php

@@ -99,15 +99,9 @@ class FancyCaptcha extends SimpleCaptcha {
 		];
 	}
 
-	/**
-	 * Insert the captcha prompt into the edit form.
-	 * @param OutputPage $out
-	 */
-	function getForm( OutputPage $out, $tabIndex = 1 ) {
+	function getFormInformation( $tabIndex = 1 ) {
 		global $wgEnableAPI;
-
-		// Uses addModuleStyles so it is loaded when JS is disabled.
-		$out->addModuleStyles( 'ext.confirmEdit.fancyCaptcha.styles' );
+		$modules = [];
 
 		$title = SpecialPage::getTitleFor( 'Captcha', 'image' );
 		$info = $this->getCaptcha();
@@ -115,7 +109,7 @@ class FancyCaptcha extends SimpleCaptcha {
 
 		if ( $wgEnableAPI ) {
 			// Loaded only if JS is enabled
-			$out->addModules( 'ext.confirmEdit.fancyCaptcha' );
+			$modules[] = 'ext.confirmEdit.fancyCaptcha';
 
 			$captchaReload = Html::element(
 				'small',
@@ -172,7 +166,12 @@ class FancyCaptcha extends SimpleCaptcha {
 				]
 			) . Html::closeElement( 'div' ) . Html::closeElement( 'div' ) . "\n";
 
-			return $form;
+		return [
+			'html' => $form,
+			'modules' => $modules,
+			// Uses addModuleStyles so it is loaded when JS is disabled.
+			'modulestyles' => [ 'ext.confirmEdit.fancyCaptcha.styles' ],
+		];
 	}
 
 	/**

MathCaptcha/MathCaptcha.class.php

@@ -25,11 +25,7 @@ class MathCaptcha extends SimpleCaptcha {
 		];
 	}
 
-	/**
-	 * Produce a nice little form
-	 * @param OutputPage $out
-	 */
-	function getForm( OutputPage $out, $tabIndex = 1 ) {
+	function getFormInformation( $tabIndex = 1 ) {
 		list( $sum, $answer ) = $this->pickSum();
 		$index = $this->storeCaptcha( [ 'answer' => $answer ] );
 
@@ -40,7 +36,7 @@ class MathCaptcha extends SimpleCaptcha {
 			'required'
 		] ) . '</td></tr></table>';
 		$form .= Html::hidden( 'wpCaptchaId', $index );
-		return $form;
+		return [ 'html' => $form ];
 	}
 
 	/** Pick a random sum */

QuestyCaptcha/QuestyCaptcha.class.php

@@ -50,7 +50,7 @@ class QuestyCaptcha extends SimpleCaptcha {
 		return [ 'question' => $question, 'answer' => $answer ];
 	}
 
-	function getForm( OutputPage $out, $tabIndex = 1 ) {
+	function getFormInformation( $tabIndex = 1 ) {
 		$captcha = $this->getCaptcha();
 		if ( !$captcha ) {
 			die(
@@ -58,20 +58,22 @@ class QuestyCaptcha extends SimpleCaptcha {
 			);
 		}
 		$index = $this->storeCaptcha( $captcha );
-		return "<p><label for=\"wpCaptchaWord\">{$captcha['question']}</label> " .
-			Html::element( 'input', [
-				'name' => 'wpCaptchaWord',
-				'id'   => 'wpCaptchaWord',
-				'class' => 'mw-ui-input',
-				'required',
-				'autocomplete' => 'off',
-				'tabindex' => $tabIndex ] ) . // tab in before the edit textarea
-			"</p>\n" .
-			Xml::element( 'input', [
-				'type'  => 'hidden',
-				'name'  => 'wpCaptchaId',
-				'id'    => 'wpCaptchaId',
-				'value' => $index ] );
+		return [
+			'html' => "<p><label for=\"wpCaptchaWord\">{$captcha['question']}</label> " .
+				Html::element( 'input', [
+					'name' => 'wpCaptchaWord',
+					'id'   => 'wpCaptchaWord',
+					'class' => 'mw-ui-input',
+					'required',
+					'autocomplete' => 'off',
+					'tabindex' => $tabIndex ] ) . // tab in before the edit textarea
+				"</p>\n" .
+				Xml::element( 'input', [
+					'type'  => 'hidden',
+					'name'  => 'wpCaptchaId',
+					'id'    => 'wpCaptchaId',
+					'value' => $index ] )
+		];
 	}
 
 	function showHelp() {

ReCaptcha/ReCaptcha.class.php

@@ -13,9 +13,8 @@ class ReCaptcha extends SimpleCaptcha {
 	/**
 	 * Displays the reCAPTCHA widget.
 	 * If $this->recaptcha_error is set, it will display an error in the widget.
-	 * @param OutputPage $out
 	 */
-	function getForm( OutputPage $out, $tabIndex = 1 ) {
+	function getFormInformation( $tabIndex = 1 ) {
 		global $wgReCaptchaPublicKey, $wgReCaptchaTheme;
 
 		$useHttps = ( isset( $_SERVER['HTTPS'] ) && $_SERVER['HTTPS'] == 'on' );
@@ -23,8 +22,10 @@ class ReCaptcha extends SimpleCaptcha {
 			[ 'theme' => $wgReCaptchaTheme, 'tabindex' => $tabIndex ]
 		);
 
-		return Html::inlineScript( $js ) .
-			   recaptcha_get_html( $wgReCaptchaPublicKey, $this->recaptcha_error, $useHttps );
+		return [
+			'html' => Html::inlineScript( $js ) .
+				recaptcha_get_html( $wgReCaptchaPublicKey, $this->recaptcha_error, $useHttps )
+		];
 	}
 
 	protected function getCaptchaParamsFromRequest( WebRequest $request ) {

ReCaptchaNoCaptcha/ReCaptchaNoCaptcha.class.php

@@ -10,19 +10,12 @@ class ReCaptchaNoCaptcha extends SimpleCaptcha {
 	private $error = null;
 	/**
 	 * Get the captcha form.
-	 * @return string
+	 * @return array
 	 */
-	function getForm( OutputPage $out, $tabIndex = 1 ) {
-		global $wgReCaptchaSiteKey;
-		$lang = htmlspecialchars( urlencode( $out->getLanguage()->getCode() ) );
+	function getFormInformation( $tabIndex = 1 ) {
+		global $wgReCaptchaSiteKey, $wgLang;
+		$lang = htmlspecialchars( urlencode( $wgLang->getCode() ) );
 
-		// Insert reCAPTCHA script, in display language, if available.
-		// Language falls back to the browser's display language.
-		// See https://developers.google.com/recaptcha/docs/faq
-		$out->addHeadItem(
-			'g-recaptchascript',
-			"<script src=\"https://www.google.com/recaptcha/api.js?hl={$lang}\" async defer></script>"
-		);
 		$output = Html::element( 'div', [
 			'class' => [
 				'g-recaptcha',
@@ -54,7 +47,15 @@ class ReCaptchaNoCaptcha extends SimpleCaptcha {
   </div>
 </noscript>
 HTML;
-		return $output;
+		return [
+			'html' => $output,
+			'headitems' => [
+				// Insert reCAPTCHA script, in display language, if available.
+				// Language falls back to the browser's display language.
+				// See https://developers.google.com/recaptcha/docs/faq
+				"<script src=\"https://www.google.com/recaptcha/api.js?hl={$lang}\" async defer></script>"
+			]
+		];
 	}
 
 	protected function logCheckError( $info ) {

SimpleCaptcha/Captcha.php

@@ -3,6 +3,9 @@
 use MediaWiki\Auth\AuthenticationRequest;
 use MediaWiki\Logger\LoggerFactory;
 
+/**
+ * Demo CAPTCHA (not for production usage) and base class for real CAPTCHAs
+ */
 class SimpleCaptcha {
 	protected static $messagePrefix = 'captcha-';
 
@@ -84,26 +87,84 @@ class SimpleCaptcha {
 	 *
 	 * Override this!
 	 *
-	 * @return string HTML
+	 * It is not guaranteed that the CAPTCHA will load synchronously with the main page
+	 * content. So you can not rely on registering handlers before page load. E.g.:
+	 *
+	 * NOT SAFE: $( window ).on( 'load', handler )
+	 * SAFE: $( handler )
+	 *
+	 * However, if the HTML is loaded dynamically via AJAX, the following order will
+	 * be used.
+	 *
+	 * headitems => modulestyles + modules => add main HTML to DOM when modulestyles +
+	 * modules are ready.
+	 *
+	 * @param int $tabIndex Tab index to start from
+	 *
+	 * @return array Associative array with the following keys:
+	 *   string html - Main HTML
+	 *   array modules (optional) - Array of ResourceLoader module names
+	 *   array modulestyles (optional) - Array of ResourceLoader module names to be
+	 *		included as style-only modules.
+	 *   array headitems (optional) - Head items (see OutputPage::addHeadItems), as a numeric array
+	 * 		of raw HTML strings. Do not use unless no other option is feasible.
 	 */
-	function getForm( OutputPage $out, $tabIndex = 1 ) {
+	public function getFormInformation( $tabIndex = 1 ) {
 		$captcha = $this->getCaptcha();
 		$index = $this->storeCaptcha( $captcha );
 
-		return "<p><label for=\"wpCaptchaWord\">{$captcha['question']} = </label>" .
-			Xml::element( 'input', [
-				'name' => 'wpCaptchaWord',
-				'class' => 'mw-ui-input',
-				'id'   => 'wpCaptchaWord',
-				'size'  => 5,
-				'autocomplete' => 'off',
-				'tabindex' => $tabIndex ] ) . // tab in before the edit textarea
-			"</p>\n" .
-			Xml::element( 'input', [
-				'type'  => 'hidden',
-				'name'  => 'wpCaptchaId',
-				'id'    => 'wpCaptchaId',
-				'value' => $index ] );
+		return [
+			'html' => "<p><label for=\"wpCaptchaWord\">{$captcha['question']} = </label>" .
+				Xml::element( 'input', [
+					'name' => 'wpCaptchaWord',
+					'class' => 'mw-ui-input',
+					'id'   => 'wpCaptchaWord',
+					'size'  => 5,
+					'autocomplete' => 'off',
+					'tabindex' => $tabIndex ] ) . // tab in before the edit textarea
+				"</p>\n" .
+				Xml::element( 'input', [
+					'type'  => 'hidden',
+					'name'  => 'wpCaptchaId',
+					'id'    => 'wpCaptchaId',
+					'value' => $index ] )
+		];
+	}
+
+	/**
+	 * Uses getFormInformation() to get the CAPTCHA form and adds it to the given
+	 * OutputPage object.
+	 *
+	 * @param OutputPage $out The OutputPage object to which the form should be added
+	 * @param integer $tabIndex See self::getFormInformation
+	 */
+	public function addFormToOutput( OutputPage $out, $tabIndex = 1 ) {
+		$this->addFormInformationToOutput( $out, $this->getFormInformation( $tabIndex ) );
+	}
+
+	/**
+	 * Processes the given $formInformation array and adds the options (see getFormInformation())
+	 * to the given OutputPage object.
+	 *
+	 * @param OutputPage $out The OutputPage object to which the form should be added
+	 * @param array $formInformation
+	 */
+	public function addFormInformationToOutput( OutputPage $out, array $formInformation ) {
+		if ( !$formInformation ) {
+			return;
+		}
+		if ( isset( $formInformation['html'] ) ) {
+			$out->addHTML( $formInformation['html'] );
+		}
+		if ( isset( $formInformation['modules'] ) ) {
+			$out->addModules( $formInformation['modules'] );
+		}
+		if ( isset( $formInformation['modulestyles'] ) ) {
+			$out->addModuleStyles( $formInformation['modulestyles'] );
+		}
+		if ( isset( $formInformation['headitems'] ) ) {
+			$out->addHeadItems( $formInformation['headitems'] );
+		}
 	}
 
 	/**
@@ -129,7 +190,7 @@ class SimpleCaptcha {
 		if ( $this->action !== 'edit' ) {
 			unset( $page->ConfirmEdit_ActivateCaptcha );
 			$out->addWikiText( $this->getMessage( $this->action )->text() );
-			$out->addHTML( $this->getForm( $out ) );
+			$this->addFormToOutput( $out );
 		}
 	}
 
@@ -145,7 +206,7 @@ class SimpleCaptcha {
 			$this->shouldCheck( $page, '', '', $context )
 		) {
 			$out->addWikiText( $this->getMessage( $this->action )->text() );
-			$out->addHTML( $this->getForm( $out ) );
+			$this->addFormToOutput( $out );
 		}
 		unset( $page->ConfirmEdit_ActivateCaptcha );
 	}
@@ -174,17 +235,23 @@ class SimpleCaptcha {
 	 * @return bool true to keep running callbacks
 	 */
 	function injectEmailUser( &$form ) {
-		global $wgCaptchaTriggers, $wgOut, $wgUser;
+		global $wgCaptchaTriggers;
+		$out = $form->getOutput();
+		$user = $form->getUser();
 		if ( $wgCaptchaTriggers['sendemail'] ) {
 			$this->action = 'sendemail';
-			if ( $wgUser->isAllowed( 'skipcaptcha' ) ) {
+			if ( $user->isAllowed( 'skipcaptcha' ) ) {
 				wfDebug( "ConfirmEdit: user group allows skipping captcha on email sending\n" );
 				return true;
 			}
+			$formInformation = $this->getFormInformation();
+			$formMetainfo = $formInformation;
+			unset( $formMetainfo['html'] );
+			$this->addFormInformationToOutput( $out, $formMetainfo );
 			$form->addFooterText(
 				"<div class='captcha'>" .
-				$wgOut->parse( $this->getMessage( 'sendemail' )->text() ) .
-				$this->getForm( $wgOut ) .
+				$out->parse( $this->getMessage( 'sendemail' )->text() ) .
+				$formInformation['html'] .
 				"</div>\n" );
 		}
 		return true;
@@ -209,6 +276,10 @@ class SimpleCaptcha {
 				'event' => 'captcha.display',
 				'type' => 'accountcreation',
 			] );
+			$formInformation = $this->getFormInformation( 8 );
+			$formMetainfo = $formInformation;
+			unset( $formMetainfo['html'] );
+			$this->addFormInformationToOutput( $wgOut, $formMetainfo );
 			$captcha = "<div class='captcha'>" .
 				$wgOut->parse( $this->getMessage( 'createaccount' )->text() ) .
 				// FIXME: Hardcoded tab index
@@ -217,7 +288,7 @@ class SimpleCaptcha {
 				// there may are wikis which allows to mention the "real name",
 				// which would have 7 as tabIndex, so increase
 				// 6 by 2 and use it for the CAPTCHA -> 8 (the submit button has a tabIndex of 10)
-				$this->getForm( $wgOut, 8 ) .
+				$formInformation['html'] .
 				"</div>\n";
 			// for older MediaWiki versions
 			if ( is_callable( [ $template, 'extend' ] ) ) {
@@ -258,9 +329,13 @@ class SimpleCaptcha {
 				'perUser' => $perUserTriggered
 			] );
 			$this->action = 'badlogin';
+			$formInformation = $this->getFormInformation();
+			$formMetainfo = $formInformation;
+			unset( $formMetainfo['html'] );
+			$this->addFormInformationToOutput( $wgOut, $formMetainfo );
 			$captcha = "<div class='captcha'>" .
 				$wgOut->parse( $this->getMessage( 'badlogin' )->text() ) .
-				$this->getForm( $wgOut ) .
+				$formInformation['html'] .
 				"</div>\n";
 			// for older MediaWiki versions
 			if ( is_callable( [ $template, 'extend' ] ) ) {