Replace BaseTemplateAfterPortlet with SkinAfterPortlet

BaseTemplate should not handle anything but rendering.
In order to allow replacing it with another renderer,
such as Mustache or Vue, its hooks should be moved to
the Skin class instead.

BaseTemplateAfterPortlet is soft deprecated to allow
filtering, preventing the hook from running twice.

Both BaseTemplate::getAfterPortlet and ::renderAfterPortlet
have been deprecated as well, with both now calling
Skin::getAfterPortlet after running the
BaseTemplateAfterPortlet hook.

Bug: T253797
Change-Id: I438daa79d3d97e2518e6258c3213a805bd1f30e8

RELEASE-NOTES-1.35

@@ -1173,6 +1173,11 @@ because of Phabricator reports.
   Use the new UserGroupManager service instead.
 * wfWaitForSlaves() has been hard deprecated. Use LBFactory::waitForReplication
   instead. It was soft deprecated in 1.27.
+* BaseTemplate::getAfterPortlet and ::renderAfterPortlet have been deprecated in
+  favor of the Skin::getAfterPortlet method. Skin::getAfterPortlet does not wrap
+  the result in a div, callers are responsible for that.
+  The hook BaseTemplateAfterPortlet, called by both methods has been deprecated
+  as well and is replaced by SkinAfterPortlet.
 * …
 
 === Other changes in 1.35 ===

autoload.php

@@ -1104,6 +1104,7 @@ $wgAutoloadLocalClasses = [
 	'MediaWiki\\Mail\\IEmailer' => __DIR__ . '/includes/mail/IEmailer.php',
 	'MediaWiki\\ProcOpenError' => __DIR__ . '/includes/exception/ProcOpenError.php',
 	'MediaWiki\\ShellDisabledError' => __DIR__ . '/includes/exception/ShellDisabledError.php',
+	'MediaWiki\\Skins\\Hook\\SkinAfterPortletHook' => __DIR__ . '/includes/skins/Hook/SkinAfterPortletHook.php',
 	'MediaWiki\\Special\\SpecialPageFactory' => __DIR__ . '/includes/specialpage/SpecialPageFactory.php',
 	'MediaWiki\\Storage\\IncompleteRevisionException' => __DIR__ . '/includes/Revision/IncompleteRevisionException.php',
 	'MediaWiki\\Storage\\MutableRevisionRecord' => __DIR__ . '/includes/Revision/MutableRevisionRecord.php',

docs/hooks.txt

@@ -3094,6 +3094,11 @@ the text you're going to add.
 &$data: (string) Text to be printed out directly (without parsing)
 $skin: Skin object
 
+'SkinAfterPortlet': Allows injecting custom HTML after the portlet.
+$skin: Skin object
+$portlet: string portlet name
+&$html: string
+
 'SkinBuildSidebar': At the end of Skin::buildSidebar().
 $skin: Skin object
 &$bar: Sidebar contents

includes/HookContainer/DeprecatedHooks.php

@@ -44,6 +44,7 @@ class DeprecatedHooks {
 		'ArticleEditUpdatesDeleteFromRecentchanges' => [ 'deprecatedVersion' => '1.35' ],
 		'ArticleRevisionUndeleted' => [ 'deprecatedVersion' => '1.35' ],
 		'ArticleRollbackComplete' => [ 'deprecatedVersion' => '1.35' ],
+		'BaseTemplateAfterPortlet' => [ 'deprecatedVersion' => '1.35', 'silent' => true ],
 		'BeforeParserrenderImageGallery' => [ 'deprecatedVersion' => '1.35' ],
 		'InternalParseBeforeSanitize' => [ 'deprecatedVersion' => '1.35' ],
 		'LinkBegin' => [ 'deprecatedVersion' => '1.28' ],

includes/HookContainer/HookRunner.php

@@ -506,6 +506,7 @@ class HookRunner implements
 	\MediaWiki\Session\Hook\SessionMetadataHook,
 	\MediaWiki\Session\Hook\UserSetCookiesHook,
 	\MediaWiki\Shell\Hook\WfShellWikiCmdHook,
+	\MediaWiki\Skins\Hook\SkinAfterPortletHook,
 	\MediaWiki\SpecialPage\Hook\AuthChangeFormFieldsHook,
 	\MediaWiki\SpecialPage\Hook\ChangeAuthenticationDataAuditHook,
 	\MediaWiki\SpecialPage\Hook\ChangesListSpecialPageQueryHook,
@@ -3466,6 +3467,13 @@ class HookRunner implements
 		);
 	}
 
+	public function onSkinAfterPortlet( $skin, $portlet, &$html ) {
+		return $this->container->run(
+			'SkinAfterPortlet',
+			[ $skin, $portlet, &$html ]
+		);
+	}
+
 	public function onSkinBuildSidebar( $skin, &$bar ) {
 		return $this->container->run(
 			'SkinBuildSidebar',

includes/skins/BaseTemplate.php

@@ -206,6 +206,7 @@ abstract class BaseTemplate extends QuickTemplate {
 	}
 
 	/**
+	 * @deprecated since 1.35 use Skin::getAfterPortlet directly
 	 * @param string $name
 	 */
 	protected function renderAfterPortlet( $name ) {
@@ -215,6 +216,8 @@ abstract class BaseTemplate extends QuickTemplate {
 	/**
 	 * Allows extensions to hook into known portlets and add stuff to them
 	 *
+	 * @deprecated since 1.35 use Skin::getAfterPortlet directly
+	 *
 	 * @param string $name
 	 *
 	 * @return string html
@@ -224,6 +227,7 @@ abstract class BaseTemplate extends QuickTemplate {
 		$html = '';
 		$content = '';
 		$this->getHookRunner()->onBaseTemplateAfterPortlet( $this, $name, $content );
+		$content .= $this->getSkin()->getAfterPortlet( $name );
 
 		if ( $content !== '' ) {
 			$html = Html::rawElement(

includes/skins/Hook/BaseTemplateAfterPortletHook.php

@@ -5,7 +5,7 @@ namespace MediaWiki\Hook;
 use BaseTemplate;
 
 /**
- * @stable for implementation
+ * @deprecated since 1.35 Use SkinAfterPortlet instead
  * @ingroup Hooks
  */
 interface BaseTemplateAfterPortletHook {

includes/skins/Hook/SkinAfterPortletHook.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace MediaWiki\Skins\Hook;
+
+use Skin;
+
+/**
+ * @stable for implementation
+ * @ingroup Hooks
+ */
+interface SkinAfterPortletHook {
+	/**
+	 * This hook is called when generating portlets.
+	 * It allows injecting custom HTML after the portlet.
+	 *
+	 * @since 1.35
+	 *
+	 * @param Skin $skin
+	 * @param string $portlet
+	 * @param string &$html
+	 * @return bool|void True or no return value to continue or false to abort
+	 */
+	public function onSkinAfterPortlet( $skin, $portlet, &$html );
+}

includes/skins/Skin.php

@@ -2423,4 +2423,22 @@ abstract class Skin extends ContextSource {
 				throw new MWException( 'Unknown mode passed to BaseTemplate::makeSearchButton' );
 		}
 	}
+
+	/**
+	 * Allows extensions to hook into known portlets and add stuff to them.
+	 * Unlike its BaseTemplate counterpart, this method does not wrap the html
+	 * provided by the hook in a div.
+	 *
+	 * @param string $name
+	 *
+	 * @return string html
+	 * @since 1.35
+	 */
+	public function getAfterPortlet( string $name ) : string {
+		$html = '';
+
+		$this->getHookRunner()->onSkinAfterPortlet( $this, $name, $html );
+
+		return $html;
+	}
 }