deal with phpstan warnings related to base authentication modules

3 files changed, 29 insertions, 3 deletions

diff --git a/classes/auth/base.php b/classes/auth/base.php
index 82ea06e1b..939a9d358 100644
--- a/classes/auth/base.php
+++ b/classes/auth/base.php
@@ -8,7 +8,6 @@ abstract class Auth_Base extends Plugin implements IAuthModule {
 		$this->pdo = Db::pdo();
 	}
 
-	// compatibility wrapper, because of how pluginhost works (hook name == method name)
 	function hook_auth_user(...$args) {
 		return $this->authenticate(...$args);
 	}
diff --git a/classes/iauthmodule.php b/classes/iauthmodule.php
index e714cc6ca..39aae4cc2 100644
--- a/classes/iauthmodule.php
+++ b/classes/iauthmodule.php
@@ -1,5 +1,16 @@
 <?php
 interface IAuthModule {
+	/**
+	 * @param string $login
+	 * @param string $password
+	 * optional third string $service
+	 * @return int|false user_id
+	 */
 	function authenticate($login, $password); // + optional third parameter: $service
-	function hook_auth_user(...$args); // compatibility wrapper due to how hooks work
+
+	/** this is a pluginhost compatibility wrapper that invokes $this->authenticate(...$args) (Auth_Base)
+	 * @param mixed $args = ($login, $password, $service)
+	 * @return int|false user_id
+	 */
+	function hook_auth_user(...$args);
 }
diff --git a/classes/plugin.php b/classes/plugin.php
index 638cc2f50..bcd8c0de7 100644
--- a/classes/plugin.php
+++ b/classes/plugin.php
@@ -141,8 +141,24 @@ abstract class Plugin {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
-	function hook_auth_user($login, $password, $service) {
+	/** this is a pluginhost compatibility wrapper that invokes $this->authenticate(...$args) (Auth_Base)
+	 * @param mixed $args = ($login, $password, $service)
+	 * @return int|false user_id
+	 */
+	function hook_auth_user(...$args) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+		return false;
+	}
+
+	/** IAuthModule only
+	 * @param string $login
+	 * @param string $password
+	 * optional third string $service
+	 * @return int|false user_id
+	 */
+	function authenticate($login, $password) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+		return false;
 	}
 
 	function hook_hotkey_map($hotkeys) {