From 28c5a6769711d20463a07a3bc41899e201ccd7f4 Mon Sep 17 00:00:00 2001
From: Umherirrender <umherirrender_de.wp@web.de>
Date: Mon, 5 Jun 2023 22:47:23 +0200
Subject: [PATCH] Create HookRunner class and the hook handler interfaces

Bug: T263353
Change-Id: I7ee943a262eba7d2f00fd05925676cc2351b7be9
---
 src/HookHandlers/ParserHooksHandler.php       | 12 +++---
 src/Hooks/HookRunner.php                      | 43 +++++++++++++++++++
 src/Hooks/MathFormulaPostRenderHook.php       | 23 ++++++++++
 .../MathRenderingResultRetrievedHook.php      | 22 ++++++++++
 src/MathLaTeXML.php                           |  8 ++--
 src/MathMathML.php                            |  5 ++-
 tests/phpunit/unit/HookRunnerTest.php         | 16 +++++++
 7 files changed, 118 insertions(+), 11 deletions(-)
 create mode 100644 src/Hooks/HookRunner.php
 create mode 100644 src/Hooks/MathFormulaPostRenderHook.php
 create mode 100644 src/Hooks/MathRenderingResultRetrievedHook.php
 create mode 100644 tests/phpunit/unit/HookRunnerTest.php

diff --git a/src/HookHandlers/ParserHooksHandler.php b/src/HookHandlers/ParserHooksHandler.php
index 02113dd81..2887e6b87 100644
--- a/src/HookHandlers/ParserHooksHandler.php
+++ b/src/HookHandlers/ParserHooksHandler.php
@@ -3,6 +3,7 @@
 namespace MediaWiki\Extension\Math\HookHandlers;
 
 use FatalError;
+use MediaWiki\Extension\Math\Hooks\HookRunner;
 use MediaWiki\Extension\Math\MathConfig;
 use MediaWiki\Extension\Math\MathMathML;
 use MediaWiki\Extension\Math\MathMathMLCli;
@@ -39,8 +40,8 @@ class ParserHooksHandler implements
 	/** @var UserOptionsLookup */
 	private $userOptionsLookup;
 
-	/** @var HookContainer */
-	private $hookContainer;
+	/** @var HookRunner */
+	private $hookRunner;
 
 	/**
 	 * @param RendererFactory $rendererFactory
@@ -54,7 +55,7 @@ class ParserHooksHandler implements
 	) {
 		$this->rendererFactory = $rendererFactory;
 		$this->userOptionsLookup = $userOptionsLookup;
-		$this->hookContainer = $hookContainer;
+		$this->hookRunner = new HookRunner( $hookContainer );
 	}
 
 	/**
@@ -138,9 +139,8 @@ class ParserHooksHandler implements
 			$renderer->addTrackingCategories( $parser );
 			return $renderer->getLastError();
 		}
-		// TODO: Convert to a new style hook system
-		$this->hookContainer->run( 'MathFormulaPostRender',
-			[ $parser, $renderer, &$renderedMath ]
+		$this->hookRunner->onMathFormulaPostRender(
+			$parser, $renderer, $renderedMath
 		); // Enables indexing of math formula
 
 		// Writes cache if rendering was successful
diff --git a/src/Hooks/HookRunner.php b/src/Hooks/HookRunner.php
new file mode 100644
index 000000000..7a5355599
--- /dev/null
+++ b/src/Hooks/HookRunner.php
@@ -0,0 +1,43 @@
+<?php
+
+namespace MediaWiki\Extension\Math\Hooks;
+
+use MediaWiki\Extension\Math\MathRenderer;
+use MediaWiki\HookContainer\HookContainer;
+use Parser;
+use stdClass;
+
+/**
+ * This is a hook runner class, see docs/Hooks.md in core.
+ * @internal
+ */
+class HookRunner implements
+	MathFormulaPostRenderHook,
+	MathRenderingResultRetrievedHook
+{
+	private HookContainer $hookContainer;
+
+	public function __construct( HookContainer $hookContainer ) {
+		$this->hookContainer = $hookContainer;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public function onMathFormulaPostRender( Parser $parser, MathRenderer $renderer, string &$renderedMath ) {
+		return $this->hookContainer->run(
+			'MathFormulaPostRender',
+			[ $parser, $renderer, &$renderedMath ]
+		);
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public function onMathRenderingResultRetrieved( MathRenderer &$renderer, stdClass &$jsonResult ) {
+		return $this->hookContainer->run(
+			'MathRenderingResultRetrieved',
+			[ &$renderer, &$jsonResult ]
+		);
+	}
+}
diff --git a/src/Hooks/MathFormulaPostRenderHook.php b/src/Hooks/MathFormulaPostRenderHook.php
new file mode 100644
index 000000000..9a6a50860
--- /dev/null
+++ b/src/Hooks/MathFormulaPostRenderHook.php
@@ -0,0 +1,23 @@
+<?php
+
+namespace MediaWiki\Extension\Math\Hooks;
+
+use MediaWiki\Extension\Math\MathRenderer;
+use Parser;
+
+/**
+ * This is a hook handler interface, see docs/Hooks.md in core.
+ * Use the hook name "MathFormulaPostRender" to register handlers implementing this interface.
+ *
+ * @stable to implement
+ * @ingroup Hooks
+ */
+interface MathFormulaPostRenderHook {
+	/**
+	 * @param Parser $parser
+	 * @param MathRenderer $renderer
+	 * @param string &$renderedMath
+	 * @return bool|void True or no return value to continue or false to abort
+	 */
+	public function onMathFormulaPostRender( Parser $parser, MathRenderer $renderer, string &$renderedMath );
+}
diff --git a/src/Hooks/MathRenderingResultRetrievedHook.php b/src/Hooks/MathRenderingResultRetrievedHook.php
new file mode 100644
index 000000000..32e9b7d35
--- /dev/null
+++ b/src/Hooks/MathRenderingResultRetrievedHook.php
@@ -0,0 +1,22 @@
+<?php
+
+namespace MediaWiki\Extension\Math\Hooks;
+
+use MediaWiki\Extension\Math\MathRenderer;
+use stdClass;
+
+/**
+ * This is a hook handler interface, see docs/Hooks.md in core.
+ * Use the hook name "MathRenderingResultRetrieved" to register handlers implementing this interface.
+ *
+ * @stable to implement
+ * @ingroup Hooks
+ */
+interface MathRenderingResultRetrievedHook {
+	/**
+	 * @param MathRenderer &$renderer
+	 * @param stdClass &$jsonResult
+	 * @return bool|void True or no return value to continue or false to abort
+	 */
+	public function onMathRenderingResultRetrieved( MathRenderer &$renderer, stdClass &$jsonResult );
+}
diff --git a/src/MathLaTeXML.php b/src/MathLaTeXML.php
index 15bfbe394..34a38945b 100644
--- a/src/MathLaTeXML.php
+++ b/src/MathLaTeXML.php
@@ -2,6 +2,7 @@
 
 namespace MediaWiki\Extension\Math;
 
+use MediaWiki\Extension\Math\Hooks\HookRunner;
 use MediaWiki\Logger\LoggerFactory;
 use MediaWiki\MediaWikiServices;
 use StatusValue;
@@ -117,9 +118,10 @@ class MathLaTeXML extends MathMathML {
 					$this->setMathml( $jsonResult->result );
 					// Avoid PHP 7.1 warning from passing $this by reference
 					$renderer = $this;
-					MediaWikiServices::getInstance()->getHookContainer()->run( 'MathRenderingResultRetrieved',
-						[ &$renderer, &$jsonResult ]
-					); // Enables debugging of server results
+					( new HookRunner( MediaWikiServices::getInstance()->getHookContainer() ) )
+						->onMathRenderingResultRetrieved(
+							$renderer, $jsonResult
+						); // Enables debugging of server results
 					return StatusValue::newGood();
 				}
 
diff --git a/src/MathMathML.php b/src/MathMathML.php
index 067978df9..82a8c670b 100644
--- a/src/MathMathML.php
+++ b/src/MathMathML.php
@@ -9,6 +9,7 @@
 namespace MediaWiki\Extension\Math;
 
 use Html;
+use MediaWiki\Extension\Math\Hooks\HookRunner;
 use MediaWiki\Logger\LoggerFactory;
 use MediaWiki\MediaWikiServices;
 use Psr\Log\LoggerInterface;
@@ -547,8 +548,8 @@ class MathMathML extends MathRenderer {
 			}
 			// Avoid PHP 7.1 warning from passing $this by reference
 			$renderer = $this;
-			MediaWikiServices::getInstance()->getHookContainer()->run( 'MathRenderingResultRetrieved',
-				[ &$renderer, &$jsonResult ]
+			( new HookRunner( MediaWikiServices::getInstance()->getHookContainer() ) )->onMathRenderingResultRetrieved(
+				$renderer, $jsonResult
 			); // Enables debugging of server results
 			return StatusValue::newGood(); // FIXME: empty?
 		} else {
diff --git a/tests/phpunit/unit/HookRunnerTest.php b/tests/phpunit/unit/HookRunnerTest.php
new file mode 100644
index 000000000..757ce087e
--- /dev/null
+++ b/tests/phpunit/unit/HookRunnerTest.php
@@ -0,0 +1,16 @@
+<?php
+
+namespace MediaWiki\Extension\Math\Tests\Unit;
+
+use MediaWiki\Extension\Math\Hooks\HookRunner;
+use MediaWiki\Tests\HookContainer\HookRunnerTestBase;
+
+/**
+ * @covers \MediaWiki\Extension\Math\Hooks\HookRunner
+ */
+class HookRunnerTest extends HookRunnerTestBase {
+
+	public static function provideHookRunners() {
+		yield HookRunner::class => [ HookRunner::class ];
+	}
+}