From b381e9579295b238d44532a50edb6422b8c6b4ab Mon Sep 17 00:00:00 2001
From: Andrew Dolgov <noreply@fakecake.org>
Date: Sat, 13 Nov 2021 18:18:05 +0300
Subject: experimental: auto-generate and add all plugin hook methods to Plugin
 class

---
 classes/plugin.php | 194 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 194 insertions(+)

(limited to 'classes/plugin.php')

diff --git a/classes/plugin.php b/classes/plugin.php
index ecafa7888..1b6702d72 100644
--- a/classes/plugin.php
+++ b/classes/plugin.php
@@ -58,4 +58,198 @@ abstract class Plugin {
 		return vsprintf($this->__($msgid), $args);
 	}
 
+	/* plugin hook methods (auto-generated) */
+
+	function hook_article_button($line) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_article_filter($article) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_prefs_tab($tab) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_prefs_tab_section($section) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_prefs_tabs() {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_feed_parsed($parser, $feed_id) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_update_task($cli_options) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_auth_user($login, $password, $service) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_hotkey_map($hotkeys) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_render_article($article) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_render_article_cdm($article) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_feed_fetched($feed_data, $fetch_url, $owner_uid, $feed) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_sanitize($doc, $site_url, $allowed_elements, $disallowed_attributes, $article_id) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_render_article_api($params) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_toolbar_button() {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_action_item() {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_headline_toolbar_button($feed_id, $is_cat) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_hotkey_info($hotkeys) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_article_left_button($row) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_prefs_edit_feed($feed_id) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_prefs_save_feed($feed_id) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_fetch_feed($feed_data, $fetch_url, $owner_uid, $feed, $last_article_timestamp, $auth_login, $auth_pass) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_query_headlines($row) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_house_keeping() {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_search($query) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_format_enclosures($rv, $result, $id, $always_display_enclosures, $article_content, $hide_images) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_subscribe_feed($contents, $url, $auth_login, $auth_pass) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_headlines_before($feed, $is_cat, $qfh_ret) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_render_enclosure($entry, $id, $rv) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_article_filter_action($article, $action) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_article_export_feed($line, $feed, $is_cat, $owner_uid) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_main_toolbar_button() {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_enclosure_entry($entry, $id, $rv) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_format_article($html, $row) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_feed_basic_info($basic_info, $fetch_url, $owner_uid, $feed_id, $auth_login, $auth_pass) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_send_local_file($filename) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_unsubscribe_feed($feed_id, $owner_uid) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_send_mail(Mailer $mailer, $params) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_filter_triggered($feed_id, $owner_uid, $article, $matched_filters, $matched_rules, $article_filters) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_get_full_text($url) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_article_image($enclosures, $content, $site_url) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_feed_tree() {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_iframe_whitelisted($url) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_enclosure_imported($enclosure, $feed) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_headlines_custom_sort_map() {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_headlines_custom_sort_override($order) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_headline_toolbar_select_menu_item($feed_id, $is_cat) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_pre_subscribe($url, $auth_login, $auth_pass) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
 }
-- 
cgit v1.2.3


From f2323bda81a8fb4f80fff043b356449ef0233305 Mon Sep 17 00:00:00 2001
From: Andrew Dolgov <noreply@fakecake.org>
Date: Sat, 13 Nov 2021 18:26:11 +0300
Subject: fix phpstan warnings in classes/plugin-template.php

---
 classes/plugin.php | 26 +++++++++++++++-----------
 1 file changed, 15 insertions(+), 11 deletions(-)

(limited to 'classes/plugin.php')

diff --git a/classes/plugin.php b/classes/plugin.php
index 1b6702d72..08a122023 100644
--- a/classes/plugin.php
+++ b/classes/plugin.php
@@ -5,53 +5,57 @@ abstract class Plugin {
 	/** @var PDO $pdo */
 	protected $pdo;
 
-	abstract function init(PluginHost $host);
+	abstract function init(PluginHost $host) : void;
 
-	abstract function about();
+	/** @return array<float|string|bool> */
+	abstract function about() : array;
 	// return array(1.0, "plugin", "No description", "No author", false);
 
 	function __construct() {
 		$this->pdo = Db::pdo();
 	}
 
-	function flags() {
+	/** @return array<string,int> */
+	function flags() : array {
 		/* associative array, possible keys:
 			needs_curl = boolean
 		*/
 		return array();
 	}
 
-	function is_public_method($method) {
+	function is_public_method(string $method) : bool {
 		return false;
 	}
 
-	function csrf_ignore($method) {
+	function csrf_ignore(string $method) : bool {
 		return false;
 	}
 
-	function get_js() {
+	function get_js() : string {
 		return "";
 	}
 
-	function get_prefs_js() {
+	function get_prefs_js() : string {
 		return "";
 	}
 
-	function api_version() {
+	function api_version() : int {
 		return Plugin::API_VERSION_COMPAT;
 	}
 
 	/* gettext-related helpers */
 
-	function __($msgid) {
+	function __(string $msgid) : string {
+		/** @var Plugin $this -- this is a strictly template-related hack */
 		return _dgettext(PluginHost::object_to_domain($this), $msgid);
 	}
 
-	function _ngettext($singular, $plural, $number) {
+	function _ngettext(string $singular, string $plural, int $number) : string {
+		/** @var Plugin $this -- this is a strictly template-related hack */
 		return _dngettext(PluginHost::object_to_domain($this), $singular, $plural, $number);
 	}
 
-	function T_sprintf() {
+	function T_sprintf() : string {
 		$args = func_get_args();
 		$msgid = array_shift($args);
 
-- 
cgit v1.2.3


From 9845d5fd15c8e123f31f39574d2b48437a3e0586 Mon Sep 17 00:00:00 2001
From: Andrew Dolgov <noreply@fakecake.org>
Date: Sat, 13 Nov 2021 19:36:24 +0300
Subject: revert all plugin base class related changes to keep compatibility
 with extant plugins (for the time being)

---
 classes/plugin.php | 217 +++--------------------------------------------------
 1 file changed, 11 insertions(+), 206 deletions(-)

(limited to 'classes/plugin.php')

diff --git a/classes/plugin.php b/classes/plugin.php
index 08a122023..5d6d4d39e 100644
--- a/classes/plugin.php
+++ b/classes/plugin.php
@@ -5,10 +5,10 @@ abstract class Plugin {
 	/** @var PDO $pdo */
 	protected $pdo;
 
-	abstract function init(PluginHost $host) : void;
+	abstract function init($host);
 
 	/** @return array<float|string|bool> */
-	abstract function about() : array;
+	abstract function about();
 	// return array(1.0, "plugin", "No description", "No author", false);
 
 	function __construct() {
@@ -16,244 +16,49 @@ abstract class Plugin {
 	}
 
 	/** @return array<string,int> */
-	function flags() : array {
+	function flags() {
 		/* associative array, possible keys:
 			needs_curl = boolean
 		*/
 		return array();
 	}
 
-	function is_public_method(string $method) : bool {
+	function is_public_method($method) {
 		return false;
 	}
 
-	function csrf_ignore(string $method) : bool {
+	function csrf_ignore($method) {
 		return false;
 	}
 
-	function get_js() : string {
+	function get_js() {
 		return "";
 	}
 
-	function get_prefs_js() : string {
+	function get_prefs_js() {
 		return "";
 	}
 
-	function api_version() : int {
+	function api_version() {
 		return Plugin::API_VERSION_COMPAT;
 	}
 
 	/* gettext-related helpers */
 
-	function __(string $msgid) : string {
+	function __($msgid) {
 		/** @var Plugin $this -- this is a strictly template-related hack */
 		return _dgettext(PluginHost::object_to_domain($this), $msgid);
 	}
 
-	function _ngettext(string $singular, string $plural, int $number) : string {
+	function _ngettext($singular, $plural, $number) {
 		/** @var Plugin $this -- this is a strictly template-related hack */
 		return _dngettext(PluginHost::object_to_domain($this), $singular, $plural, $number);
 	}
 
-	function T_sprintf() : string {
+	function T_sprintf() {
 		$args = func_get_args();
 		$msgid = array_shift($args);
 
 		return vsprintf($this->__($msgid), $args);
 	}
-
-	/* plugin hook methods (auto-generated) */
-
-	function hook_article_button($line) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_article_filter($article) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_prefs_tab($tab) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_prefs_tab_section($section) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_prefs_tabs() {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_feed_parsed($parser, $feed_id) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_update_task($cli_options) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_auth_user($login, $password, $service) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_hotkey_map($hotkeys) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_render_article($article) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_render_article_cdm($article) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_feed_fetched($feed_data, $fetch_url, $owner_uid, $feed) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_sanitize($doc, $site_url, $allowed_elements, $disallowed_attributes, $article_id) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_render_article_api($params) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_toolbar_button() {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_action_item() {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_headline_toolbar_button($feed_id, $is_cat) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_hotkey_info($hotkeys) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_article_left_button($row) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_prefs_edit_feed($feed_id) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_prefs_save_feed($feed_id) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_fetch_feed($feed_data, $fetch_url, $owner_uid, $feed, $last_article_timestamp, $auth_login, $auth_pass) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_query_headlines($row) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_house_keeping() {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_search($query) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_format_enclosures($rv, $result, $id, $always_display_enclosures, $article_content, $hide_images) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_subscribe_feed($contents, $url, $auth_login, $auth_pass) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_headlines_before($feed, $is_cat, $qfh_ret) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_render_enclosure($entry, $id, $rv) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_article_filter_action($article, $action) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_article_export_feed($line, $feed, $is_cat, $owner_uid) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_main_toolbar_button() {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_enclosure_entry($entry, $id, $rv) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_format_article($html, $row) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_feed_basic_info($basic_info, $fetch_url, $owner_uid, $feed_id, $auth_login, $auth_pass) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_send_local_file($filename) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_unsubscribe_feed($feed_id, $owner_uid) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_send_mail(Mailer $mailer, $params) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_filter_triggered($feed_id, $owner_uid, $article, $matched_filters, $matched_rules, $article_filters) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_get_full_text($url) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_article_image($enclosures, $content, $site_url) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_feed_tree() {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_iframe_whitelisted($url) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_enclosure_imported($enclosure, $feed) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_headlines_custom_sort_map() {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_headlines_custom_sort_override($order) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_headline_toolbar_select_menu_item($feed_id, $is_cat) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-	function hook_pre_subscribe($url, $auth_login, $auth_pass) {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
 }
-- 
cgit v1.2.3


From 37827427a22d2e379c1142e2eb3d46c53e43783b Mon Sep 17 00:00:00 2001
From: Andrew Dolgov <noreply@fakecake.org>
Date: Sat, 13 Nov 2021 19:41:50 +0300
Subject: rework previous Plugin changes as phpdoc annotations

---
 classes/plugin.php | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

(limited to 'classes/plugin.php')

diff --git a/classes/plugin.php b/classes/plugin.php
index 5d6d4d39e..5b486d766 100644
--- a/classes/plugin.php
+++ b/classes/plugin.php
@@ -5,6 +5,11 @@ abstract class Plugin {
 	/** @var PDO $pdo */
 	protected $pdo;
 
+	/**
+	 * @param PluginHost $host
+	 *
+	 * @return void
+	 * */
 	abstract function init($host);
 
 	/** @return array<float|string|bool> */
@@ -23,38 +28,60 @@ abstract class Plugin {
 		return array();
 	}
 
+	/**
+	 * @param string $method
+	 *
+	 * @return bool */
 	function is_public_method($method) {
 		return false;
 	}
 
+	/**
+	 * @param string $method
+	 *
+	 * @return bool */
 	function csrf_ignore($method) {
 		return false;
 	}
 
+	/** @return string */
 	function get_js() {
 		return "";
 	}
 
+	/** @return string */
 	function get_prefs_js() {
 		return "";
 	}
 
+	/** @return int */
 	function api_version() {
 		return Plugin::API_VERSION_COMPAT;
 	}
 
 	/* gettext-related helpers */
 
+	/**
+	 * @param string $msgid
+	 *
+	 * @return string */
 	function __($msgid) {
 		/** @var Plugin $this -- this is a strictly template-related hack */
 		return _dgettext(PluginHost::object_to_domain($this), $msgid);
 	}
 
+	/**
+	 * @param string $singular
+	 * @param string $plural
+	 * @param int $number
+	 *
+	 * @return string */
 	function _ngettext($singular, $plural, $number) {
 		/** @var Plugin $this -- this is a strictly template-related hack */
 		return _dngettext(PluginHost::object_to_domain($this), $singular, $plural, $number);
 	}
 
+	/** @return string */
 	function T_sprintf() {
 		$args = func_get_args();
 		$msgid = array_shift($args);
-- 
cgit v1.2.3


From 03d069226886a6955cc71c6b25ddc92b9b7d47b2 Mon Sep 17 00:00:00 2001
From: Andrew Dolgov <noreply@fakecake.org>
Date: Sat, 13 Nov 2021 19:52:47 +0300
Subject: no need to duplicate annotations

---
 classes/plugin.php | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

(limited to 'classes/plugin.php')

diff --git a/classes/plugin.php b/classes/plugin.php
index 5b486d766..eae2c0c17 100644
--- a/classes/plugin.php
+++ b/classes/plugin.php
@@ -12,7 +12,7 @@ abstract class Plugin {
 	 * */
 	abstract function init($host);
 
-	/** @return array<float|string|bool> */
+	/** @return array<null|float|string|bool> */
 	abstract function about();
 	// return array(1.0, "plugin", "No description", "No author", false);
 
@@ -49,6 +49,11 @@ abstract class Plugin {
 		return "";
 	}
 
+	/** @return string */
+	function get_css() {
+		return "";
+	}
+
 	/** @return string */
 	function get_prefs_js() {
 		return "";
-- 
cgit v1.2.3


From 618e96b793769ef4d7912f1f16f1ca7436acd199 Mon Sep 17 00:00:00 2001
From: Andrew Dolgov <noreply@fakecake.org>
Date: Sat, 13 Nov 2021 19:55:30 +0300
Subject: deal with some warnings in plugins/trgm,readability and base plugin
 class

---
 classes/plugin.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'classes/plugin.php')

diff --git a/classes/plugin.php b/classes/plugin.php
index eae2c0c17..ea79e6a65 100644
--- a/classes/plugin.php
+++ b/classes/plugin.php
@@ -20,7 +20,7 @@ abstract class Plugin {
 		$this->pdo = Db::pdo();
 	}
 
-	/** @return array<string,int> */
+	/** @return array<string,bool> */
 	function flags() {
 		/* associative array, possible keys:
 			needs_curl = boolean
-- 
cgit v1.2.3


From 5e34fe17a7717b6484e1c7f8a31e3f57e71ab45d Mon Sep 17 00:00:00 2001
From: Andrew Dolgov <noreply@fakecake.org>
Date: Sat, 13 Nov 2021 20:03:28 +0300
Subject: experimental: bring back plugin hooks to Plugin base class once (to
 be improved/fixed with annotations later)

---
 classes/plugin.php | 194 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 194 insertions(+)

(limited to 'classes/plugin.php')

diff --git a/classes/plugin.php b/classes/plugin.php
index ea79e6a65..feae9ec9c 100644
--- a/classes/plugin.php
+++ b/classes/plugin.php
@@ -93,4 +93,198 @@ abstract class Plugin {
 
 		return vsprintf($this->__($msgid), $args);
 	}
+
+	/* plugin hook methods */
+
+	function hook_article_button($line) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_article_filter($article) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_prefs_tab($tab) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_prefs_tab_section($section) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_prefs_tabs() {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_feed_parsed($parser, $feed_id) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_update_task($cli_options) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_auth_user($login, $password, $service) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_hotkey_map($hotkeys) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_render_article($article) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_render_article_cdm($article) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_feed_fetched($feed_data, $fetch_url, $owner_uid, $feed) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_sanitize($doc, $site_url, $allowed_elements, $disallowed_attributes, $article_id) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_render_article_api($params) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_toolbar_button() {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_action_item() {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_headline_toolbar_button($feed_id, $is_cat) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_hotkey_info($hotkeys) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_article_left_button($row) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_prefs_edit_feed($feed_id) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_prefs_save_feed($feed_id) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_fetch_feed($feed_data, $fetch_url, $owner_uid, $feed, $last_article_timestamp, $auth_login, $auth_pass) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_query_headlines($row) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_house_keeping() {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_search($query) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_format_enclosures($rv, $result, $id, $always_display_enclosures, $article_content, $hide_images) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_subscribe_feed($contents, $url, $auth_login, $auth_pass) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_headlines_before($feed, $is_cat, $qfh_ret) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_render_enclosure($entry, $id, $rv) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_article_filter_action($article, $action) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_article_export_feed($line, $feed, $is_cat, $owner_uid) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_main_toolbar_button() {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_enclosure_entry($entry, $id, $rv) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_format_article($html, $row) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_feed_basic_info($basic_info, $fetch_url, $owner_uid, $feed_id, $auth_login, $auth_pass) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_send_local_file($filename) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_unsubscribe_feed($feed_id, $owner_uid) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_send_mail(Mailer $mailer, $params) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_filter_triggered($feed_id, $owner_uid, $article, $matched_filters, $matched_rules, $article_filters) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_get_full_text($url) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_article_image($enclosures, $content, $site_url) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_feed_tree() {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_iframe_whitelisted($url) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_enclosure_imported($enclosure, $feed) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_headlines_custom_sort_map() {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_headlines_custom_sort_override($order) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_headline_toolbar_select_menu_item($feed_id, $is_cat) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
+
+	function hook_pre_subscribe($url, $auth_login, $auth_pass) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+	}
 }
-- 
cgit v1.2.3


From fe5ada72504705f9304c3f0bba049a20998fe650 Mon Sep 17 00:00:00 2001
From: Andrew Dolgov <noreply@fakecake.org>
Date: Sat, 13 Nov 2021 20:07:13 +0300
Subject: set some annotations on Plugin hook methods

---
 classes/plugin.php | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

(limited to 'classes/plugin.php')

diff --git a/classes/plugin.php b/classes/plugin.php
index feae9ec9c..638cc2f50 100644
--- a/classes/plugin.php
+++ b/classes/plugin.php
@@ -96,22 +96,39 @@ abstract class Plugin {
 
 	/* plugin hook methods */
 
+	/**
+	 * @param array<string,mixed> $line
+	 * @return string
+	 */
 	function hook_article_button($line) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
+	/**
+	 * @param array<string,mixed> $article
+	 * @return array<string,mixed>
+	 */
 	function hook_article_filter($article) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
+	/**
+	 * @param string $tab
+	 * @return void
+	 */
 	function hook_prefs_tab($tab) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
+	/**
+	 * @param string $section
+	 * @return void
+	 */
 	function hook_prefs_tab_section($section) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
+	/** @return void  */
 	function hook_prefs_tabs() {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
-- 
cgit v1.2.3


From 81a10f69bcc38b62aad79f9be716adcf4ed49d2d Mon Sep 17 00:00:00 2001
From: Andrew Dolgov <noreply@fakecake.org>
Date: Sun, 14 Nov 2021 10:48:32 +0300
Subject: deal with phpstan warnings related to base authentication modules

---
 classes/plugin.php | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

(limited to 'classes/plugin.php')

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) {
-- 
cgit v1.2.3


From 0a2dcacbcf01e1ebb225570fb99811c4215c6ea9 Mon Sep 17 00:00:00 2001
From: Andrew Dolgov <noreply@fakecake.org>
Date: Sun, 14 Nov 2021 11:11:49 +0300
Subject: normalize some mismatching hook function definitions to match base
 Plugin class

---
 classes/plugin.php | 27 +++++++++++++++++++++------
 1 file changed, 21 insertions(+), 6 deletions(-)

(limited to 'classes/plugin.php')

diff --git a/classes/plugin.php b/classes/plugin.php
index bcd8c0de7..8c14cd78d 100644
--- a/classes/plugin.php
+++ b/classes/plugin.php
@@ -1,4 +1,11 @@
 <?php
+/* TODO: I haven't yet decided if we're keeping hook prototypes which did grow (with additional params) over time and breaking all plugins
+	with legacy function definitions, or commenting base definitions out for the time being -fox
+
+	(It's a shame that PHP doesn't support argument overloading)
+
+	Stuff like hook_enclosure_entry() etc.
+*/
 abstract class Plugin {
 	const API_VERSION_COMPAT = 1;
 
@@ -142,10 +149,12 @@ abstract class Plugin {
 	}
 
 	/** this is a pluginhost compatibility wrapper that invokes $this->authenticate(...$args) (Auth_Base)
-	 * @param mixed $args = ($login, $password, $service)
+	 * @param string $login
+	 * @param string $password
+	 * @param string $service
 	 * @return int|false user_id
 	 */
-	function hook_auth_user(...$args) {
+	function hook_auth_user($login, $password, $service = '') {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 		return false;
 	}
@@ -153,10 +162,10 @@ abstract class Plugin {
 	/** IAuthModule only
 	 * @param string $login
 	 * @param string $password
-	 * optional third string $service
+	 * @param string $service
 	 * @return int|false user_id
 	 */
-	function authenticate($login, $password) {
+	function authenticate($login, $password, $service = '') {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 		return false;
 	}
@@ -257,6 +266,12 @@ abstract class Plugin {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
+	/**
+	 * @param array<string,string> $entry
+	 * @param int $id
+	 * @param array{'formatted': string, 'entries': array<int, array<string, mixed>>} $rv
+	 * @return array<string,string>
+	 */
 	function hook_enclosure_entry($entry, $id, $rv) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
@@ -289,7 +304,7 @@ abstract class Plugin {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
-	function hook_article_image($enclosures, $content, $site_url) {
+	function hook_article_image($enclosures, $content, $site_url, $article) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
@@ -317,7 +332,7 @@ abstract class Plugin {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
-	function hook_pre_subscribe($url, $auth_login, $auth_pass) {
+	function hook_pre_subscribe(&$url, $auth_login, $auth_pass) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 }
-- 
cgit v1.2.3


From af2f4460ce94f48aa4c3bb3176c59325b6612b32 Mon Sep 17 00:00:00 2001
From: Andrew Dolgov <noreply@fakecake.org>
Date: Sun, 14 Nov 2021 16:49:10 +0300
Subject:  * deal with some phpstan warnings in base plugin class  * arguably
 better hack for incompatible plugins causing E_COMPILE_ERROR

---
 classes/plugin.php | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)

(limited to 'classes/plugin.php')

diff --git a/classes/plugin.php b/classes/plugin.php
index 8c14cd78d..b027a05c3 100644
--- a/classes/plugin.php
+++ b/classes/plugin.php
@@ -140,10 +140,19 @@ abstract class Plugin {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
+	/**
+	 * @param FeedParser $parser
+	 * @param int $feed_id
+	 * @return void
+	 */
 	function hook_feed_parsed($parser, $feed_id) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
+	/**
+	 * @param array<string,string> $cli_options
+	 * @return void
+	 */
 	function hook_update_task($cli_options) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
@@ -170,44 +179,94 @@ abstract class Plugin {
 		return false;
 	}
 
+	/**
+	 * @param array<string, string> $hotkeys
+	 * @return array<string, string>
+	 */
 	function hook_hotkey_map($hotkeys) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
+	/**
+	 * @param array<string, mixed> $article
+	 * @return array<string, mixed>
+	 */
 	function hook_render_article($article) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return [];
 	}
 
+	/**
+	 * @param array<string, mixed> $article
+	 * @return array<string, mixed>
+	 */
 	function hook_render_article_cdm($article) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return [];
 	}
 
+	/**
+	 * @param string $feed_data
+	 * @param string $fetch_url
+	 * @param int $owner_uid
+	 * @param int $feed
+	 * @return string
+	 */
 	function hook_feed_fetched($feed_data, $fetch_url, $owner_uid, $feed) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return "";
 	}
 
 	function hook_sanitize($doc, $site_url, $allowed_elements, $disallowed_attributes, $article_id) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
+	/**
+	 * @param array{'article': array<string,mixed>} $params
+	 * @return array<string, string>
+	 */
 	function hook_render_article_api($params) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return [];
 	}
 
+	/** @return string  */
 	function hook_toolbar_button() {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return "";
 	}
 
+	/** @return string  */
 	function hook_action_item() {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return "";
 	}
 
+	/**
+	 * @param int $feed_id
+	 * @param bool $is_cat
+	 * @return string
+	 */
 	function hook_headline_toolbar_button($feed_id, $is_cat) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return "";
 	}
 
+	/**
+	 * @param array<string,string> $hotkeys
+	 * @return array<string,string>
+	 */
 	function hook_hotkey_info($hotkeys) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return [];
 	}
 
 	function hook_article_left_button($row) {
@@ -230,6 +289,7 @@ abstract class Plugin {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
+	/** @return void  */
 	function hook_house_keeping() {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
@@ -262,6 +322,7 @@ abstract class Plugin {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
+	/** @return void  */
 	function hook_main_toolbar_button() {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
@@ -296,24 +357,57 @@ abstract class Plugin {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
+	/** NOTE: $article_filters should be renamed $filter_actions because that's what this is
+	 * @param int $feed_id
+	 * @param int $owner_uid
+	 * @param array<string,mixed> $article
+	 * @param array<string,mixed> $matched_filters
+	 * @param array<string,string|bool|int> $matched_rules
+	 * @param array<string,string> $article_filters
+	 * @return void
+	 */
 	function hook_filter_triggered($feed_id, $owner_uid, $article, $matched_filters, $matched_rules, $article_filters) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
+	/**
+	 * @param string $url
+	 * @return string
+	 */
 	function hook_get_full_text($url) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return "";
 	}
 
+	/**
+	 * @param array<string,string> $enclosures
+	 * @param string $content
+	 * @param string $site_url
+	 * @param array<string,mixed> $article
+	 * @return string
+	 */
 	function hook_article_image($enclosures, $content, $site_url, $article) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return "";
 	}
 
+	/** @return string */
 	function hook_feed_tree() {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return "";
 	}
 
+	/**
+	 * @param string $url
+	 * @return bool
+	 */
 	function hook_iframe_whitelisted($url) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return false;
 	}
 
 	function hook_enclosure_imported($enclosure, $feed) {
-- 
cgit v1.2.3


From 55729b4bbd79c6afa913d3a4acc576eef5cfaae1 Mon Sep 17 00:00:00 2001
From: Andrew Dolgov <noreply@fakecake.org>
Date: Sun, 14 Nov 2021 17:07:47 +0300
Subject: fix HOOK_QUERY_HEADLINES being invoked with different argument lists,
 add some more phpdoc comments for base plugin class

---
 classes/plugin.php | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 81 insertions(+), 4 deletions(-)

(limited to 'classes/plugin.php')

diff --git a/classes/plugin.php b/classes/plugin.php
index b027a05c3..96541d033 100644
--- a/classes/plugin.php
+++ b/classes/plugin.php
@@ -109,6 +109,8 @@ abstract class Plugin {
 	 */
 	function hook_article_button($line) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return "";
 	}
 
 	/**
@@ -117,6 +119,8 @@ abstract class Plugin {
 	 */
 	function hook_article_filter($article) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return [];
 	}
 
 	/**
@@ -185,6 +189,8 @@ abstract class Plugin {
 	 */
 	function hook_hotkey_map($hotkeys) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return [];
 	}
 
 	/**
@@ -269,14 +275,28 @@ abstract class Plugin {
 		return [];
 	}
 
+	/**
+	 * @param array<string,mixed> $row
+	 * @return string
+	 */
 	function hook_article_left_button($row) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return "";
 	}
 
+	/**
+	 * @param int $feed_id
+	 * @return void
+	 */
 	function hook_prefs_edit_feed($feed_id) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
+	/**
+	 * @param int $feed_id
+	 * @return void
+	 */
 	function hook_prefs_save_feed($feed_id) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
@@ -285,8 +305,15 @@ abstract class Plugin {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
-	function hook_query_headlines($row) {
+	/**
+	 * @param array<string,mixed> $row
+	 * @param int $excerpt_length
+	 * @return array<string,mixed>
+	 */
+	function hook_query_headlines($row, $excerpt_length) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return [];
 	}
 
 	/** @return void  */
@@ -294,23 +321,50 @@ abstract class Plugin {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
+	/**
+	 * @param string $query
+	 * @return array<string>
+	 */
 	function hook_search($query) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return [];
 	}
 
 	function hook_format_enclosures($rv, $result, $id, $always_display_enclosures, $article_content, $hide_images) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
+	/**
+	 * @param string $contents
+	 * @param string $url
+	 * @param string $auth_login
+	 * @param string $auth_pass
+	 * @return string (possibly mangled feed data)
+	 */
 	function hook_subscribe_feed($contents, $url, $auth_login, $auth_pass) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
+	/**
+	 * @param int $feed
+	 * @param bool $is_cat
+	 * @param array<string,mixed> $qfh_ret (headlines object)
+	 * @return string
+	 */
 	function hook_headlines_before($feed, $is_cat, $qfh_ret) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return "";
 	}
 
-	function hook_render_enclosure($entry, $id, $rv) {
+	/**
+	 * @param array<string,mixed> $entry
+	 * @param int $article_id
+	 * @param array<string,mixed> $rv
+	 * @return string
+	 */
+	function hook_render_enclosure($entry, $article_id, $rv) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
@@ -318,8 +372,17 @@ abstract class Plugin {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
+	/**
+	 * @param array<string,mixed> $line
+	 * @param int $feed
+	 * @param bool $is_cat
+	 * @param int $owner_uid
+	 * @return array<string,mixed> ($line)
+	 */
 	function hook_article_export_feed($line, $feed, $is_cat, $owner_uid) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return [];
 	}
 
 	/** @return void  */
@@ -331,12 +394,19 @@ abstract class Plugin {
 	 * @param array<string,string> $entry
 	 * @param int $id
 	 * @param array{'formatted': string, 'entries': array<int, array<string, mixed>>} $rv
-	 * @return array<string,string>
+	 * @return array<string,string> ($entry)
 	 */
 	function hook_enclosure_entry($entry, $id, $rv) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return [];
 	}
 
+	/**
+	 * @param string $html
+	 * @param array<string,mixed> $row
+	 * @return string ($html)
+	 */
 	function hook_format_article($html, $row) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
@@ -353,8 +423,15 @@ abstract class Plugin {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
-	function hook_send_mail(Mailer $mailer, $params) {
+	/**
+	 * @param Mailer $mailer
+	 * @param array<string,mixed> $params
+	 * @return int
+	 */
+	function hook_send_mail($mailer, $params) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return -1;
 	}
 
 	/** NOTE: $article_filters should be renamed $filter_actions because that's what this is
-- 
cgit v1.2.3


From dd7299b6d070d26ff97194ef14be349f08776e2a Mon Sep 17 00:00:00 2001
From: Andrew Dolgov <noreply@fakecake.org>
Date: Sun, 14 Nov 2021 17:19:35 +0300
Subject: deal with a few more phpstan warnings re: base plugin class

---
 classes/plugin.php | 48 +++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 47 insertions(+), 1 deletion(-)

(limited to 'classes/plugin.php')

diff --git a/classes/plugin.php b/classes/plugin.php
index 96541d033..ac234f081 100644
--- a/classes/plugin.php
+++ b/classes/plugin.php
@@ -226,8 +226,18 @@ abstract class Plugin {
 		return "";
 	}
 
+	/**
+	 * @param DOMDocument $doc
+	 * @param string $site_url
+	 * @param array<string> $allowed_elements
+	 * @param array<string> $disallowed_attributes
+	 * @param int $article_id
+	 * @return DOMDocument
+	 */
 	function hook_sanitize($doc, $site_url, $allowed_elements, $disallowed_attributes, $article_id) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return $doc;
 	}
 
 	/**
@@ -301,8 +311,20 @@ abstract class Plugin {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
+	/**
+	 * @param string $feed_data
+	 * @param string $fetch_url
+	 * @param int $owner_uid
+	 * @param int $feed
+	 * @param int $last_article_timestamp
+	 * @param string $auth_login
+	 * @param string $auth_pass
+	 * @return string (possibly mangled feed data)
+	 */
 	function hook_fetch_feed($feed_data, $fetch_url, $owner_uid, $feed, $last_article_timestamp, $auth_login, $auth_pass) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return "";
 	}
 
 	/**
@@ -331,8 +353,19 @@ abstract class Plugin {
 		return [];
 	}
 
-	function hook_format_enclosures($rv, $result, $id, $always_display_enclosures, $article_content, $hide_images) {
+	/**
+	 * @param string $enclosures_formatted
+	 * @param array<int, array<string, mixed>> $enclosures
+	 * @param int $article_id
+	 * @param bool $always_display_enclosures
+	 * @param string $article_content
+	 * @param bool $hide_images
+	 * @return string|array<string,array<int, array<string, mixed>>> ($enclosures_formatted, $enclosures)
+	 */
+	function hook_format_enclosures($enclosures_formatted, $enclosures, $article_id, $always_display_enclosures, $article_content, $hide_images) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return "";
 	}
 
 	/**
@@ -344,6 +377,8 @@ abstract class Plugin {
 	 */
 	function hook_subscribe_feed($contents, $url, $auth_login, $auth_pass) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return "";
 	}
 
 	/**
@@ -366,10 +401,19 @@ abstract class Plugin {
 	 */
 	function hook_render_enclosure($entry, $article_id, $rv) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return "";
 	}
 
+	/**
+	 * @param array<string,mixed> $article
+	 * @param string $action
+	 * @return array<string,mixed> ($article)
+	 */
 	function hook_article_filter_action($article, $action) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return [];
 	}
 
 	/**
@@ -409,6 +453,8 @@ abstract class Plugin {
 	 */
 	function hook_format_article($html, $row) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return "";
 	}
 
 	function hook_feed_basic_info($basic_info, $fetch_url, $owner_uid, $feed_id, $auth_login, $auth_pass) {
-- 
cgit v1.2.3


From 01b39d985c9f194a35c690a18149cbb06fc7b0d3 Mon Sep 17 00:00:00 2001
From: Andrew Dolgov <noreply@fakecake.org>
Date: Sun, 14 Nov 2021 18:00:03 +0300
Subject: deal with the rest of warnings in plugin.php

---
 classes/plugin.php | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

(limited to 'classes/plugin.php')

diff --git a/classes/plugin.php b/classes/plugin.php
index ac234f081..b20bbcbc2 100644
--- a/classes/plugin.php
+++ b/classes/plugin.php
@@ -457,16 +457,40 @@ abstract class Plugin {
 		return "";
 	}
 
+	/**
+	 * @param array{"title": string, "site_url": string} $basic_info
+	 * @param string $fetch_url
+	 * @param int $owner_uid
+	 * @param int $feed_id
+	 * @param string $auth_login
+	 * @param string $auth_pass
+	 * @return array{"title": string, "site_url": string}
+	 */
 	function hook_feed_basic_info($basic_info, $fetch_url, $owner_uid, $feed_id, $auth_login, $auth_pass) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return $basic_info;
 	}
 
+	/**
+	 * @param string $filename
+	 * @return bool
+	 */
 	function hook_send_local_file($filename) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return false;
 	}
 
+	/**
+	 * @param int $feed_id
+	 * @param int $owner_uid
+	 * @return bool
+	 */
 	function hook_unsubscribe_feed($feed_id, $owner_uid) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return false;
 	}
 
 	/**
@@ -533,23 +557,54 @@ abstract class Plugin {
 		return false;
 	}
 
+	/**
+	 * @param array<string,string> $enclosure
+	 * @param int $feed
+	 * @return array<string,string> ($enclosure)
+	 */
 	function hook_enclosure_imported($enclosure, $feed) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return $enclosure;
 	}
 
+	/** @return array<string,string> */
 	function hook_headlines_custom_sort_map() {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return ["" => ""];
 	}
 
+	/**
+	 * @param string $order
+	 * @return array<int, string|bool> -- query, skip_first_id
+	 */
 	function hook_headlines_custom_sort_override($order) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return ["", false];
 	}
 
+	/**
+	 * @param int $feed_id
+	 * @param int $is_cat
+	 * @return string
+	 */
 	function hook_headline_toolbar_select_menu_item($feed_id, $is_cat) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return "";
 	}
 
+	/**
+	 * @param string $url
+	 * @param string $auth_login
+	 * @param string $auth_pass
+	 * @return bool
+	 */
 	function hook_pre_subscribe(&$url, $auth_login, $auth_pass) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+
+		return false;
 	}
 }
-- 
cgit v1.2.3


From 7988c79bd40356b62d9f1bca03284c0b35a49fcd Mon Sep 17 00:00:00 2001
From: Andrew Dolgov <noreply@fakecake.org>
Date: Sun, 14 Nov 2021 18:05:31 +0300
Subject: plugin.php: add some minor method phpdoc corrections

---
 classes/plugin.php | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'classes/plugin.php')

diff --git a/classes/plugin.php b/classes/plugin.php
index b20bbcbc2..290c4cc3b 100644
--- a/classes/plugin.php
+++ b/classes/plugin.php
@@ -241,7 +241,7 @@ abstract class Plugin {
 	}
 
 	/**
-	 * @param array{'article': array<string,mixed>} $params
+	 * @param array{'article': array<string,mixed>|null, 'headline': array<string,mixed>|null} $params
 	 * @return array<string, string>
 	 */
 	function hook_render_article_api($params) {
@@ -532,7 +532,7 @@ abstract class Plugin {
 	 * @param string $content
 	 * @param string $site_url
 	 * @param array<string,mixed> $article
-	 * @return string
+	 * @return string|array<int,string>
 	 */
 	function hook_article_image($enclosures, $content, $site_url, $article) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
-- 
cgit v1.2.3


From 6bd6a14c207ddaf35256b11dd381093d57ef38a4 Mon Sep 17 00:00:00 2001
From: Andrew Dolgov <noreply@fakecake.org>
Date: Sun, 14 Nov 2021 20:19:12 +0300
Subject: revise phpdoc annotations for hook_sanitize()

---
 classes/plugin.php | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'classes/plugin.php')

diff --git a/classes/plugin.php b/classes/plugin.php
index 290c4cc3b..55ccff9c3 100644
--- a/classes/plugin.php
+++ b/classes/plugin.php
@@ -232,7 +232,7 @@ abstract class Plugin {
 	 * @param array<string> $allowed_elements
 	 * @param array<string> $disallowed_attributes
 	 * @param int $article_id
-	 * @return DOMDocument
+	 * @return DOMDocument|array<int,DOMDocument|array<string>>
 	 */
 	function hook_sanitize($doc, $site_url, $allowed_elements, $disallowed_attributes, $article_id) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -519,7 +519,7 @@ abstract class Plugin {
 
 	/**
 	 * @param string $url
-	 * @return string
+	 * @return string|false
 	 */
 	function hook_get_full_text($url) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
-- 
cgit v1.2.3


From 56cf425e457dbf6cb75a899c67f527b2efe340d7 Mon Sep 17 00:00:00 2001
From: Andrew Dolgov <noreply@fakecake.org>
Date: Sun, 14 Nov 2021 23:03:25 +0300
Subject: revise prototype for hook_enclosure_imported

---
 classes/plugin.php | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'classes/plugin.php')

diff --git a/classes/plugin.php b/classes/plugin.php
index 55ccff9c3..333f605ca 100644
--- a/classes/plugin.php
+++ b/classes/plugin.php
@@ -558,9 +558,9 @@ abstract class Plugin {
 	}
 
 	/**
-	 * @param array<string,string> $enclosure
+	 * @param object $enclosure
 	 * @param int $feed
-	 * @return array<string,string> ($enclosure)
+	 * @return object ($enclosure)
 	 */
 	function hook_enclosure_imported($enclosure, $feed) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
-- 
cgit v1.2.3


From 12f9df1066e4b22d5b748c4a9821106515948d75 Mon Sep 17 00:00:00 2001
From: wn_ <invalid@email.com>
Date: Sun, 14 Nov 2021 22:11:27 +0000
Subject: Fix the return signature for Plugin#hook_hotkey_info()

---
 classes/plugin.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'classes/plugin.php')

diff --git a/classes/plugin.php b/classes/plugin.php
index 333f605ca..1cfa5ecbe 100644
--- a/classes/plugin.php
+++ b/classes/plugin.php
@@ -277,7 +277,7 @@ abstract class Plugin {
 
 	/**
 	 * @param array<string,string> $hotkeys
-	 * @return array<string,string>
+	 * @return array<string, array<string, string>>
 	 */
 	function hook_hotkey_info($hotkeys) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
-- 
cgit v1.2.3


From 324d926eb46f049b2a03743fc445ccceabd4dfb9 Mon Sep 17 00:00:00 2001
From: wn_ <invalid@email.com>
Date: Sun, 14 Nov 2021 22:16:16 +0000
Subject: Also fix the param signature for Plugin#hook_hotkey_info()

---
 classes/plugin.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'classes/plugin.php')

diff --git a/classes/plugin.php b/classes/plugin.php
index 1cfa5ecbe..40b821b8c 100644
--- a/classes/plugin.php
+++ b/classes/plugin.php
@@ -276,7 +276,7 @@ abstract class Plugin {
 	}
 
 	/**
-	 * @param array<string,string> $hotkeys
+	 * @param array<string, array<string, string>> $hotkeys
 	 * @return array<string, array<string, string>>
 	 */
 	function hook_hotkey_info($hotkeys) {
-- 
cgit v1.2.3


From edc7998851b457e9f83ab49b9e17c88b4b153bad Mon Sep 17 00:00:00 2001
From: Andrew Dolgov <noreply@fakecake.org>
Date: Mon, 15 Nov 2021 06:53:55 +0300
Subject: revise phpdoc annotations for hook_search()

---
 classes/plugin.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'classes/plugin.php')

diff --git a/classes/plugin.php b/classes/plugin.php
index 40b821b8c..16e9791eb 100644
--- a/classes/plugin.php
+++ b/classes/plugin.php
@@ -345,7 +345,7 @@ abstract class Plugin {
 
 	/**
 	 * @param string $query
-	 * @return array<string>
+	 * @return array<int, string|array<string>>
 	 */
 	function hook_search($query) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
-- 
cgit v1.2.3


From 10d1a8c05aba9f6c66021e3708ac6aa2ba714a2e Mon Sep 17 00:00:00 2001
From: Andrew Dolgov <noreply@fakecake.org>
Date: Tue, 16 Nov 2021 16:31:40 +0300
Subject: adjust phpdoc tags for hook definitions/constants (make them
 reference each other)

---
 classes/plugin.php | 85 ++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 70 insertions(+), 15 deletions(-)

(limited to 'classes/plugin.php')

diff --git a/classes/plugin.php b/classes/plugin.php
index 16e9791eb..afa9d7a78 100644
--- a/classes/plugin.php
+++ b/classes/plugin.php
@@ -1,11 +1,4 @@
 <?php
-/* TODO: I haven't yet decided if we're keeping hook prototypes which did grow (with additional params) over time and breaking all plugins
-	with legacy function definitions, or commenting base definitions out for the time being -fox
-
-	(It's a shame that PHP doesn't support argument overloading)
-
-	Stuff like hook_enclosure_entry() etc.
-*/
 abstract class Plugin {
 	const API_VERSION_COMPAT = 1;
 
@@ -103,9 +96,12 @@ abstract class Plugin {
 
 	/* plugin hook methods */
 
+	/* GLOBAL hooks are invoked in global context, only available to system plugins (loaded via .env for all users) */
+
 	/**
 	 * @param array<string,mixed> $line
 	 * @return string
+	 * @see PluginHost::HOOK_ARTICLE_BUTTON
 	 */
 	function hook_article_button($line) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -116,6 +112,7 @@ abstract class Plugin {
 	/**
 	 * @param array<string,mixed> $article
 	 * @return array<string,mixed>
+	 * @see PluginHost::HOOK_ARTICLE_FILTER
 	 */
 	function hook_article_filter($article) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -126,6 +123,7 @@ abstract class Plugin {
 	/**
 	 * @param string $tab
 	 * @return void
+	 * @see PluginHost::HOOK_PREFS_TAB
 	 */
 	function hook_prefs_tab($tab) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -134,12 +132,15 @@ abstract class Plugin {
 	/**
 	 * @param string $section
 	 * @return void
+	 * @see PluginHost::HOOK_PREFS_TAB_SECTION
 	 */
 	function hook_prefs_tab_section($section) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
-	/** @return void  */
+	/** @return void
+	 * @see PluginHost::HOOK_PREFS_TABS
+	*/
 	function hook_prefs_tabs() {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
@@ -148,14 +149,16 @@ abstract class Plugin {
 	 * @param FeedParser $parser
 	 * @param int $feed_id
 	 * @return void
+	 * @see PluginHost::HOOK_FEED_PARSED
 	 */
 	function hook_feed_parsed($parser, $feed_id) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
-	/**
+	/** GLOBAL
 	 * @param array<string,string> $cli_options
 	 * @return void
+	 * @see PluginHost::HOOK_UPDATE_TASK
 	 */
 	function hook_update_task($cli_options) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -166,6 +169,7 @@ abstract class Plugin {
 	 * @param string $password
 	 * @param string $service
 	 * @return int|false user_id
+	 * @see PluginHost::HOOK_AUTH_USER
 	 */
 	function hook_auth_user($login, $password, $service = '') {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -186,6 +190,7 @@ abstract class Plugin {
 	/**
 	 * @param array<string, string> $hotkeys
 	 * @return array<string, string>
+	 * @see PluginHost::HOOK_HOTKEY_MAP
 	 */
 	function hook_hotkey_map($hotkeys) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -196,6 +201,7 @@ abstract class Plugin {
 	/**
 	 * @param array<string, mixed> $article
 	 * @return array<string, mixed>
+	 * @see PluginHost::HOOK_RENDER_ARTICLE
 	 */
 	function hook_render_article($article) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -206,6 +212,7 @@ abstract class Plugin {
 	/**
 	 * @param array<string, mixed> $article
 	 * @return array<string, mixed>
+	 * @see PluginHost::HOOK_RENDER_ARTICLE_CDM
 	 */
 	function hook_render_article_cdm($article) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -219,6 +226,7 @@ abstract class Plugin {
 	 * @param int $owner_uid
 	 * @param int $feed
 	 * @return string
+	 * @see PluginHost::HOOK_FEED_FETCHED
 	 */
 	function hook_feed_fetched($feed_data, $fetch_url, $owner_uid, $feed) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -233,6 +241,7 @@ abstract class Plugin {
 	 * @param array<string> $disallowed_attributes
 	 * @param int $article_id
 	 * @return DOMDocument|array<int,DOMDocument|array<string>>
+	 * @see PluginHost::HOOK_SANITIZE
 	 */
 	function hook_sanitize($doc, $site_url, $allowed_elements, $disallowed_attributes, $article_id) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -243,6 +252,7 @@ abstract class Plugin {
 	/**
 	 * @param array{'article': array<string,mixed>|null, 'headline': array<string,mixed>|null} $params
 	 * @return array<string, string>
+	 * @see PluginHost::HOOK_RENDER_ARTICLE_API
 	 */
 	function hook_render_article_api($params) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -250,14 +260,20 @@ abstract class Plugin {
 		return [];
 	}
 
-	/** @return string  */
+	/**
+	 * @return string
+	 * @see PluginHost::HOOK_TOOLBAR_BUTTON
+	 */
 	function hook_toolbar_button() {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 
 		return "";
 	}
 
-	/** @return string  */
+	/**
+	 * @return string
+	 * @see PluginHost::HOOK_ACTION_ITEM
+	 */
 	function hook_action_item() {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 
@@ -268,6 +284,7 @@ abstract class Plugin {
 	 * @param int $feed_id
 	 * @param bool $is_cat
 	 * @return string
+	 * @see PluginHost::HOOK_HEADLINE_TOOLBAR_BUTTON
 	 */
 	function hook_headline_toolbar_button($feed_id, $is_cat) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -278,6 +295,7 @@ abstract class Plugin {
 	/**
 	 * @param array<string, array<string, string>> $hotkeys
 	 * @return array<string, array<string, string>>
+	 * @see PluginHost::HOOK_HOTKEY_INFO
 	 */
 	function hook_hotkey_info($hotkeys) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -288,6 +306,7 @@ abstract class Plugin {
 	/**
 	 * @param array<string,mixed> $row
 	 * @return string
+	 * @see PluginHost::HOOK_ARTICLE_LEFT_BUTTON
 	 */
 	function hook_article_left_button($row) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -298,6 +317,7 @@ abstract class Plugin {
 	/**
 	 * @param int $feed_id
 	 * @return void
+	 * @see PluginHost::HOOK_PREFS_EDIT_FEED
 	 */
 	function hook_prefs_edit_feed($feed_id) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -306,6 +326,7 @@ abstract class Plugin {
 	/**
 	 * @param int $feed_id
 	 * @return void
+	 * @see PluginHost::HOOK_PREFS_SAVE_FEED
 	 */
 	function hook_prefs_save_feed($feed_id) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -320,6 +341,7 @@ abstract class Plugin {
 	 * @param string $auth_login
 	 * @param string $auth_pass
 	 * @return string (possibly mangled feed data)
+	 * @see PluginHost::HOOK_FETCH_FEED
 	 */
 	function hook_fetch_feed($feed_data, $fetch_url, $owner_uid, $feed, $last_article_timestamp, $auth_login, $auth_pass) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -331,6 +353,7 @@ abstract class Plugin {
 	 * @param array<string,mixed> $row
 	 * @param int $excerpt_length
 	 * @return array<string,mixed>
+	 * @see PluginHost::HOOK_QUERY_HEADLINES
 	 */
 	function hook_query_headlines($row, $excerpt_length) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -338,7 +361,9 @@ abstract class Plugin {
 		return [];
 	}
 
-	/** @return void  */
+	/** GLOBAL
+	 * @return void
+	 * @see PluginHost::HOOK_HOUSE_KEEPING */
 	function hook_house_keeping() {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
@@ -346,6 +371,7 @@ abstract class Plugin {
 	/**
 	 * @param string $query
 	 * @return array<int, string|array<string>>
+	 * @see PluginHost::HOOK_SEARCH
 	 */
 	function hook_search($query) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -361,6 +387,7 @@ abstract class Plugin {
 	 * @param string $article_content
 	 * @param bool $hide_images
 	 * @return string|array<string,array<int, array<string, mixed>>> ($enclosures_formatted, $enclosures)
+	 * @see PluginHost::HOOK_FORMAT_ENCLOSURES
 	 */
 	function hook_format_enclosures($enclosures_formatted, $enclosures, $article_id, $always_display_enclosures, $article_content, $hide_images) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -374,6 +401,7 @@ abstract class Plugin {
 	 * @param string $auth_login
 	 * @param string $auth_pass
 	 * @return string (possibly mangled feed data)
+	 * @see PluginHost::HOOK_SUBSCRIBE_FEED
 	 */
 	function hook_subscribe_feed($contents, $url, $auth_login, $auth_pass) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -386,6 +414,7 @@ abstract class Plugin {
 	 * @param bool $is_cat
 	 * @param array<string,mixed> $qfh_ret (headlines object)
 	 * @return string
+	 * @see PluginHost::HOOK_HEADLINES_BEFORE
 	 */
 	function hook_headlines_before($feed, $is_cat, $qfh_ret) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -398,6 +427,7 @@ abstract class Plugin {
 	 * @param int $article_id
 	 * @param array<string,mixed> $rv
 	 * @return string
+	 * @see PluginHost::HOOK_RENDER_ENCLOSURE
 	 */
 	function hook_render_enclosure($entry, $article_id, $rv) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -409,6 +439,7 @@ abstract class Plugin {
 	 * @param array<string,mixed> $article
 	 * @param string $action
 	 * @return array<string,mixed> ($article)
+	 * @see PluginHost::HOOK_ARTICLE_FILTER_ACTION
 	 */
 	function hook_article_filter_action($article, $action) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -422,6 +453,7 @@ abstract class Plugin {
 	 * @param bool $is_cat
 	 * @param int $owner_uid
 	 * @return array<string,mixed> ($line)
+	 * @see PluginHost::HOOK_ARTICLE_EXPORT_FEED
 	 */
 	function hook_article_export_feed($line, $feed, $is_cat, $owner_uid) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -429,7 +461,10 @@ abstract class Plugin {
 		return [];
 	}
 
-	/** @return void  */
+	/**
+	 * @return void
+	 * @see PluginHost::HOOK_MAIN_TOOLBAR_BUTTON
+	*/
 	function hook_main_toolbar_button() {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
@@ -439,6 +474,7 @@ abstract class Plugin {
 	 * @param int $id
 	 * @param array{'formatted': string, 'entries': array<int, array<string, mixed>>} $rv
 	 * @return array<string,string> ($entry)
+	 * @see PluginHost::HOOK_ENCLOSURE_ENTRY
 	 */
 	function hook_enclosure_entry($entry, $id, $rv) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -450,6 +486,7 @@ abstract class Plugin {
 	 * @param string $html
 	 * @param array<string,mixed> $row
 	 * @return string ($html)
+	 * @see PluginHost::HOOK_FORMAT_ARTICLE
 	 */
 	function hook_format_article($html, $row) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -465,6 +502,7 @@ abstract class Plugin {
 	 * @param string $auth_login
 	 * @param string $auth_pass
 	 * @return array{"title": string, "site_url": string}
+	 * @see PluginHost::HOOK_FEED_BASIC_INFO
 	 */
 	function hook_feed_basic_info($basic_info, $fetch_url, $owner_uid, $feed_id, $auth_login, $auth_pass) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -475,6 +513,7 @@ abstract class Plugin {
 	/**
 	 * @param string $filename
 	 * @return bool
+	 * @see PluginHost::HOOK_SEND_LOCAL_FILE
 	 */
 	function hook_send_local_file($filename) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -486,6 +525,7 @@ abstract class Plugin {
 	 * @param int $feed_id
 	 * @param int $owner_uid
 	 * @return bool
+	 * @see PluginHost::HOOK_UNSUBSCRIBE_FEED
 	 */
 	function hook_unsubscribe_feed($feed_id, $owner_uid) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -497,6 +537,7 @@ abstract class Plugin {
 	 * @param Mailer $mailer
 	 * @param array<string,mixed> $params
 	 * @return int
+	 * @see PluginHost::HOOK_SEND_MAIL
 	 */
 	function hook_send_mail($mailer, $params) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -512,6 +553,7 @@ abstract class Plugin {
 	 * @param array<string,string|bool|int> $matched_rules
 	 * @param array<string,string> $article_filters
 	 * @return void
+	 * @see PluginHost::HOOK_FILTER_TRIGGERED
 	 */
 	function hook_filter_triggered($feed_id, $owner_uid, $article, $matched_filters, $matched_rules, $article_filters) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -520,6 +562,7 @@ abstract class Plugin {
 	/**
 	 * @param string $url
 	 * @return string|false
+	 * @see PluginHost::HOOK_GET_FULL_TEXT
 	 */
 	function hook_get_full_text($url) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -533,6 +576,7 @@ abstract class Plugin {
 	 * @param string $site_url
 	 * @param array<string,mixed> $article
 	 * @return string|array<int,string>
+	 * @see PluginHost::HOOK_ARTICLE_IMAGE
 	 */
 	function hook_article_image($enclosures, $content, $site_url, $article) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -540,7 +584,10 @@ abstract class Plugin {
 		return "";
 	}
 
-	/** @return string */
+	/**
+	 * @return string
+	 * @see PluginHost::HOOK_FEED_TREE
+	 * */
 	function hook_feed_tree() {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 
@@ -550,6 +597,7 @@ abstract class Plugin {
 	/**
 	 * @param string $url
 	 * @return bool
+	 * @see PluginHost::HOOK_IFRAME_WHITELISTED
 	 */
 	function hook_iframe_whitelisted($url) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -561,6 +609,7 @@ abstract class Plugin {
 	 * @param object $enclosure
 	 * @param int $feed
 	 * @return object ($enclosure)
+	 * @see PluginHost::HOOK_ENCLOSURE_IMPORTED
 	 */
 	function hook_enclosure_imported($enclosure, $feed) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -568,7 +617,10 @@ abstract class Plugin {
 		return $enclosure;
 	}
 
-	/** @return array<string,string> */
+	/**
+	 * @return array<string,string>
+	 * @see PluginHost::HOOK_HEADLINES_CUSTOM_SORT_MAP
+	 */
 	function hook_headlines_custom_sort_map() {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 
@@ -578,6 +630,7 @@ abstract class Plugin {
 	/**
 	 * @param string $order
 	 * @return array<int, string|bool> -- query, skip_first_id
+	 * @see PluginHost::HOOK_HEADLINES_CUSTOM_SORT_OVERRIDE
 	 */
 	function hook_headlines_custom_sort_override($order) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -589,6 +642,7 @@ abstract class Plugin {
 	 * @param int $feed_id
 	 * @param int $is_cat
 	 * @return string
+	 * @see PluginHost::HOOK_HEADLINE_TOOLBAR_SELECT_MENU_ITEM
 	 */
 	function hook_headline_toolbar_select_menu_item($feed_id, $is_cat) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -601,6 +655,7 @@ abstract class Plugin {
 	 * @param string $auth_login
 	 * @param string $auth_pass
 	 * @return bool
+	 * @see PluginHost::HOOK_PRE_SUBSCRIBE
 	 */
 	function hook_pre_subscribe(&$url, $auth_login, $auth_pass) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
-- 
cgit v1.2.3


From 3e273ea527d3f6d39adade93e24815a78370bea4 Mon Sep 17 00:00:00 2001
From: Andrew Dolgov <noreply@fakecake.org>
Date: Wed, 17 Nov 2021 15:56:58 +0300
Subject: add descriptions for some plugin hooks

---
 classes/plugin.php | 58 ++++++++++++++++++++++++++++++------------------------
 1 file changed, 32 insertions(+), 26 deletions(-)

(limited to 'classes/plugin.php')

diff --git a/classes/plugin.php b/classes/plugin.php
index afa9d7a78..8b533b389 100644
--- a/classes/plugin.php
+++ b/classes/plugin.php
@@ -98,10 +98,11 @@ abstract class Plugin {
 
 	/* GLOBAL hooks are invoked in global context, only available to system plugins (loaded via .env for all users) */
 
-	/**
+	/** Adds buttons for article (on the right) - e.g. mail, share, add note.
 	 * @param array<string,mixed> $line
 	 * @return string
 	 * @see PluginHost::HOOK_ARTICLE_BUTTON
+	 * @see Plugin::hook_article_left_button()
 	 */
 	function hook_article_button($line) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -109,7 +110,7 @@ abstract class Plugin {
 		return "";
 	}
 
-	/**
+	/** Allows plugins to alter article data as gathered from feed XML, i.e. embed images, get full text content, etc.
 	 * @param array<string,mixed> $article
 	 * @return array<string,mixed>
 	 * @see PluginHost::HOOK_ARTICLE_FILTER
@@ -120,7 +121,7 @@ abstract class Plugin {
 		return [];
 	}
 
-	/**
+	/** Allow adding new UI elements (e.g. accordion panes) to (top) tab contents in Preferences
 	 * @param string $tab
 	 * @return void
 	 * @see PluginHost::HOOK_PREFS_TAB
@@ -129,7 +130,7 @@ abstract class Plugin {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
-	/**
+	/** Allow adding new content to various sections of preferences UI (i.e. OPML import/export pane)
 	 * @param string $section
 	 * @return void
 	 * @see PluginHost::HOOK_PREFS_TAB_SECTION
@@ -138,14 +139,15 @@ abstract class Plugin {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
-	/** @return void
+	/** Allows adding new (top) tabs in preferences UI
+	 * @return void
 	 * @see PluginHost::HOOK_PREFS_TABS
 	*/
 	function hook_prefs_tabs() {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
-	/**
+	/** Invoked when feed XML is processed by FeedParser class
 	 * @param FeedParser $parser
 	 * @param int $feed_id
 	 * @return void
@@ -155,7 +157,7 @@ abstract class Plugin {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
-	/** GLOBAL
+	/** GLOBAL: Invoked when a feed update task finishes
 	 * @param array<string,string> $cli_options
 	 * @return void
 	 * @see PluginHost::HOOK_UPDATE_TASK
@@ -164,7 +166,7 @@ abstract class Plugin {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
-	/** this is a pluginhost compatibility wrapper that invokes $this->authenticate(...$args) (Auth_Base)
+	/** This is a pluginhost compatibility wrapper that invokes $this->authenticate(...$args) (Auth_Base)
 	 * @param string $login
 	 * @param string $password
 	 * @param string $service
@@ -187,10 +189,11 @@ abstract class Plugin {
 		return false;
 	}
 
-	/**
+	/** Allows plugins to modify global hotkey map (hotkey sequence -> action)
 	 * @param array<string, string> $hotkeys
 	 * @return array<string, string>
 	 * @see PluginHost::HOOK_HOTKEY_MAP
+	 * @see Plugin::hook_hotkey_info()
 	 */
 	function hook_hotkey_map($hotkeys) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -198,7 +201,7 @@ abstract class Plugin {
 		return [];
 	}
 
-	/**
+	/** Invoked when article is rendered by backend (before it gets passed to frontent JS code) - three panel mode
 	 * @param array<string, mixed> $article
 	 * @return array<string, mixed>
 	 * @see PluginHost::HOOK_RENDER_ARTICLE
@@ -209,7 +212,7 @@ abstract class Plugin {
 		return [];
 	}
 
-	/**
+	/** Invoked when article is rendered by backend (before it gets passed to frontent JS code) - combined mode
 	 * @param array<string, mixed> $article
 	 * @return array<string, mixed>
 	 * @see PluginHost::HOOK_RENDER_ARTICLE_CDM
@@ -220,7 +223,7 @@ abstract class Plugin {
 		return [];
 	}
 
-	/**
+	/** Invoked when raw feed XML data has been successfully downloaded (but not parsed yet)
 	 * @param string $feed_data
 	 * @param string $fetch_url
 	 * @param int $owner_uid
@@ -234,7 +237,7 @@ abstract class Plugin {
 		return "";
 	}
 
-	/**
+	/** Invoked on article content when it is sanitized (i.e. potentially harmful tags removed)
 	 * @param DOMDocument $doc
 	 * @param string $site_url
 	 * @param array<string> $allowed_elements
@@ -249,7 +252,7 @@ abstract class Plugin {
 		return $doc;
 	}
 
-	/**
+	/** Invoked when article is rendered by backend (before it gets passed to frontent JS code) - exclusive to API clients
 	 * @param array{'article': array<string,mixed>|null, 'headline': array<string,mixed>|null} $params
 	 * @return array<string, string>
 	 * @see PluginHost::HOOK_RENDER_ARTICLE_API
@@ -260,7 +263,7 @@ abstract class Plugin {
 		return [];
 	}
 
-	/**
+	/** Allows adding new UI elements to tt-rss main toolbar
 	 * @return string
 	 * @see PluginHost::HOOK_TOOLBAR_BUTTON
 	 */
@@ -270,7 +273,7 @@ abstract class Plugin {
 		return "";
 	}
 
-	/**
+	/** Allows adding new items to tt-rss main Actions... dropdown menu
 	 * @return string
 	 * @see PluginHost::HOOK_ACTION_ITEM
 	 */
@@ -280,7 +283,7 @@ abstract class Plugin {
 		return "";
 	}
 
-	/**
+	/** Allows adding new UI elements to the toolbar area related to currently loaded feed headlines
 	 * @param int $feed_id
 	 * @param bool $is_cat
 	 * @return string
@@ -292,10 +295,11 @@ abstract class Plugin {
 		return "";
 	}
 
-	/**
+	/** Allows adding new hotkey action names and descriptions
 	 * @param array<string, array<string, string>> $hotkeys
 	 * @return array<string, array<string, string>>
 	 * @see PluginHost::HOOK_HOTKEY_INFO
+	 * @see Plugin::hook_hotkey_map()
 	 */
 	function hook_hotkey_info($hotkeys) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -303,10 +307,11 @@ abstract class Plugin {
 		return [];
 	}
 
-	/**
+	/** Adds per-article buttons on the left side
 	 * @param array<string,mixed> $row
 	 * @return string
 	 * @see PluginHost::HOOK_ARTICLE_LEFT_BUTTON
+	 * @see Plugin::hook_article_button()
 	 */
 	function hook_article_left_button($row) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
@@ -314,7 +319,7 @@ abstract class Plugin {
 		return "";
 	}
 
-	/**
+	/** Allows adding new UI elements to the "Plugins" tab of the feed editor UI
 	 * @param int $feed_id
 	 * @return void
 	 * @see PluginHost::HOOK_PREFS_EDIT_FEED
@@ -323,7 +328,7 @@ abstract class Plugin {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
-	/**
+	/** Invoked when data is saved in the feed editor
 	 * @param int $feed_id
 	 * @return void
 	 * @see PluginHost::HOOK_PREFS_SAVE_FEED
@@ -332,7 +337,8 @@ abstract class Plugin {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
-	/**
+	/** Allows overriding built-in fetching mechanism for feeds, substituting received data if necessary
+	 * (i.e. origin site doesn't actually provide any RSS feeds), or XML is invalid
 	 * @param string $feed_data
 	 * @param string $fetch_url
 	 * @param int $owner_uid
@@ -349,7 +355,7 @@ abstract class Plugin {
 		return "";
 	}
 
-	/**
+	/** Invoked when headlines data ($row) has been retrieved from the database
 	 * @param array<string,mixed> $row
 	 * @param int $excerpt_length
 	 * @return array<string,mixed>
@@ -361,16 +367,16 @@ abstract class Plugin {
 		return [];
 	}
 
-	/** GLOBAL
+	/** GLOBAL: This is run periodically by the update daemon when idle
 	 * @return void
 	 * @see PluginHost::HOOK_HOUSE_KEEPING */
 	function hook_house_keeping() {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
-	/**
+	/** Allows overriding built-in article search
 	 * @param string $query
-	 * @return array<int, string|array<string>>
+	 * @return array<int, string|array<string>> - list(SQL search query, highlight keywords)
 	 * @see PluginHost::HOOK_SEARCH
 	 */
 	function hook_search($query) {
-- 
cgit v1.2.3


From aeb4137cbdb53e4f0b3127b96f1f9d9416a58205 Mon Sep 17 00:00:00 2001
From: Andrew Dolgov <noreply@fakecake.org>
Date: Wed, 17 Nov 2021 18:30:32 +0300
Subject: document a few more plugin hooks

---
 classes/plugin.php | 44 +++++++++++++++++++++++---------------------
 1 file changed, 23 insertions(+), 21 deletions(-)

(limited to 'classes/plugin.php')

diff --git a/classes/plugin.php b/classes/plugin.php
index 8b533b389..0a9f837fc 100644
--- a/classes/plugin.php
+++ b/classes/plugin.php
@@ -263,7 +263,7 @@ abstract class Plugin {
 		return [];
 	}
 
-	/** Allows adding new UI elements to tt-rss main toolbar
+	/** Allows adding new UI elements to tt-rss main toolbar (to the right, before Actions... dropdown)
 	 * @return string
 	 * @see PluginHost::HOOK_TOOLBAR_BUTTON
 	 */
@@ -385,7 +385,7 @@ abstract class Plugin {
 		return [];
 	}
 
-	/**
+	/** Invoked when enclosures are rendered to HTML (when article itself is rendered)
 	 * @param string $enclosures_formatted
 	 * @param array<int, array<string, mixed>> $enclosures
 	 * @param int $article_id
@@ -401,7 +401,7 @@ abstract class Plugin {
 		return "";
 	}
 
-	/**
+	/** Invoked during feed subscription (after data has been fetched)
 	 * @param string $contents
 	 * @param string $url
 	 * @param string $auth_login
@@ -467,7 +467,7 @@ abstract class Plugin {
 		return [];
 	}
 
-	/**
+	/** Allows adding custom buttons to tt-rss main toolbar (left side)
 	 * @return void
 	 * @see PluginHost::HOOK_MAIN_TOOLBAR_BUTTON
 	*/
@@ -475,7 +475,7 @@ abstract class Plugin {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
-	/**
+	/** Invoked for every enclosure entry as article is being rendered
 	 * @param array<string,string> $entry
 	 * @param int $id
 	 * @param array{'formatted': string, 'entries': array<int, array<string, mixed>>} $rv
@@ -488,7 +488,7 @@ abstract class Plugin {
 		return [];
 	}
 
-	/**
+	/** Share plugins run this when article is being rendered as HTML for sharing
 	 * @param string $html
 	 * @param array<string,mixed> $row
 	 * @return string ($html)
@@ -500,7 +500,7 @@ abstract class Plugin {
 		return "";
 	}
 
-	/**
+	/** Invoked when basic feed information (title, site_url) is being collected, useful to override default if feed doesn't provide anything (or feed itself is synthesized)
 	 * @param array{"title": string, "site_url": string} $basic_info
 	 * @param string $fetch_url
 	 * @param int $owner_uid
@@ -516,7 +516,8 @@ abstract class Plugin {
 		return $basic_info;
 	}
 
-	/**
+	/** Invoked when file (e.g. cache entry, static data) is being sent to client, may override default mechanism
+	 * using faster httpd-specific implementation (see nginx_xaccel)
 	 * @param string $filename
 	 * @return bool
 	 * @see PluginHost::HOOK_SEND_LOCAL_FILE
@@ -527,7 +528,7 @@ abstract class Plugin {
 		return false;
 	}
 
-	/**
+	/** Invoked when user tries to unsubscribe from a feed, returning true would prevent any further default actions
 	 * @param int $feed_id
 	 * @param int $owner_uid
 	 * @return bool
@@ -539,7 +540,7 @@ abstract class Plugin {
 		return false;
 	}
 
-	/**
+	/** Invoked when mail is being sent (if no hooks are registered, tt-rss uses PHP mail() as a fallback)
 	 * @param Mailer $mailer
 	 * @param array<string,mixed> $params
 	 * @return int
@@ -551,7 +552,8 @@ abstract class Plugin {
 		return -1;
 	}
 
-	/** NOTE: $article_filters should be renamed $filter_actions because that's what this is
+	/** Invoked when filter is triggered on an article, may be used to implement logging for filters
+	 * NOTE: $article_filters should be renamed $filter_actions because that's what this is
 	 * @param int $feed_id
 	 * @param int $owner_uid
 	 * @param array<string,mixed> $article
@@ -565,7 +567,7 @@ abstract class Plugin {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
-	/**
+	/** Plugins may provide this to allow getting full article text (af_readbility implements this)
 	 * @param string $url
 	 * @return string|false
 	 * @see PluginHost::HOOK_GET_FULL_TEXT
@@ -576,7 +578,7 @@ abstract class Plugin {
 		return "";
 	}
 
-	/**
+	/** Invoked when article flavor image is being determined, allows overriding default selection logic
 	 * @param array<string,string> $enclosures
 	 * @param string $content
 	 * @param string $site_url
@@ -590,8 +592,8 @@ abstract class Plugin {
 		return "";
 	}
 
-	/**
-	 * @return string
+	/** Allows adding arbitrary elements before feed tree
+	 * @return string HTML
 	 * @see PluginHost::HOOK_FEED_TREE
 	 * */
 	function hook_feed_tree() {
@@ -600,7 +602,7 @@ abstract class Plugin {
 		return "";
 	}
 
-	/**
+	/** Invoked for every iframe to determine if it is allowed to be displayed
 	 * @param string $url
 	 * @return bool
 	 * @see PluginHost::HOOK_IFRAME_WHITELISTED
@@ -623,7 +625,7 @@ abstract class Plugin {
 		return $enclosure;
 	}
 
-	/**
+	/** Allows adding custom elements to headline sort dropdown (name -> caption)
 	 * @return array<string,string>
 	 * @see PluginHost::HOOK_HEADLINES_CUSTOM_SORT_MAP
 	 */
@@ -633,9 +635,9 @@ abstract class Plugin {
 		return ["" => ""];
 	}
 
-	/**
+	/** Allows overriding headline sorting (or provide custom sort methods)
 	 * @param string $order
-	 * @return array<int, string|bool> -- query, skip_first_id
+	 * @return array<int, string|bool> -- (query, skip_first_id)
 	 * @see PluginHost::HOOK_HEADLINES_CUSTOM_SORT_OVERRIDE
 	 */
 	function hook_headlines_custom_sort_override($order) {
@@ -644,7 +646,7 @@ abstract class Plugin {
 		return ["", false];
 	}
 
-	/**
+	/** Allows adding custom elements to headlines Select... dropdown
 	 * @param int $feed_id
 	 * @param int $is_cat
 	 * @return string
@@ -656,7 +658,7 @@ abstract class Plugin {
 		return "";
 	}
 
-	/**
+	/** Invoked when user tries to subscribe to feed, may override information (i.e. feed URL) used afterwards
 	 * @param string $url
 	 * @param string $auth_login
 	 * @param string $auth_pass
-- 
cgit v1.2.3