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-54-g00ecf


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-template.php | 26 +++++++++++++++-----------
 classes/plugin.php          | 26 +++++++++++++++-----------
 2 files changed, 30 insertions(+), 22 deletions(-)

(limited to 'classes/plugin.php')

diff --git a/classes/plugin-template.php b/classes/plugin-template.php
index ad6d07ee0..12437525b 100644
--- a/classes/plugin-template.php
+++ b/classes/plugin-template.php
@@ -5,53 +5,57 @@ abstract class PluginTemplate {
 	/** @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);
 
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-54-g00ecf


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-template.php              |  66 ----------
 classes/plugin.php                       | 217 ++-----------------------------
 utils/generate-plugin-hook-prototypes.sh |  33 -----
 3 files changed, 11 insertions(+), 305 deletions(-)
 delete mode 100644 classes/plugin-template.php
 delete mode 100644 utils/generate-plugin-hook-prototypes.sh

(limited to 'classes/plugin.php')

diff --git a/classes/plugin-template.php b/classes/plugin-template.php
deleted file mode 100644
index 12437525b..000000000
--- a/classes/plugin-template.php
+++ /dev/null
@@ -1,66 +0,0 @@
-<?php
-abstract class PluginTemplate {
-	const API_VERSION_COMPAT = 1;
-
-	/** @var PDO $pdo */
-	protected $pdo;
-
-	abstract function init(PluginHost $host) : void;
-
-	/** @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();
-	}
-
-	/** @return array<string,int> */
-	function flags() : array {
-		/* associative array, possible keys:
-			needs_curl = boolean
-		*/
-		return array();
-	}
-
-	function is_public_method(string $method) : bool {
-		return false;
-	}
-
-	function csrf_ignore(string $method) : bool {
-		return false;
-	}
-
-	function get_js() : string {
-		return "";
-	}
-
-	function get_prefs_js() : string {
-		return "";
-	}
-
-	function api_version() : int {
-		return Plugin::API_VERSION_COMPAT;
-	}
-
-	/* gettext-related helpers */
-
-	function __(string $msgid) : string {
-		/** @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 {
-		/** @var Plugin $this -- this is a strictly template-related hack */
-		return _dngettext(PluginHost::object_to_domain($this), $singular, $plural, $number);
-	}
-
-	function T_sprintf() : string {
-		$args = func_get_args();
-		$msgid = array_shift($args);
-
-		return vsprintf($this->__($msgid), $args);
-	}
-
-	/** AUTO_GENERATED_HOOKS_GO_HERE **/
-}
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);
-	}
-
 }
diff --git a/utils/generate-plugin-hook-prototypes.sh b/utils/generate-plugin-hook-prototypes.sh
deleted file mode 100644
index edf1ed5fe..000000000
--- a/utils/generate-plugin-hook-prototypes.sh
+++ /dev/null
@@ -1,33 +0,0 @@
-#!/bin/sh
-
-TMPFILE=$(mktemp)
-
-grep 'hook_.*(' ../classes/pluginhost.php | sed -e 's#[\t ]*/[* ]*##' \
-		-e 's# [*]/$##' \
-		-e 's# *(byref) *##' \
-		-e 's#GLOBAL: ##' | while read F; do
-
-	cat << EOF >> $TMPFILE 
-	function $F {
-		user_error("Dummy method invoked.", E_USER_ERROR);
-	}
-
-EOF
-done
-
-cat ../classes/plugin-template.php | while IFS=\n read L; do
-	case $L in
-		*PluginTemplate* )
-			echo "$L" | sed 's/PluginTemplate/Plugin/'
-			;;
-		*AUTO_GENERATED_HOOKS_GO_HERE* )
-			echo "\t/* plugin hook methods (auto-generated) */\n"
-			cat $TMPFILE
-			;;
-		* )
-			echo "$L"
-			;;
-	esac
-done > ../classes/plugin.php
-
-rm -f -- $TMPFILE
-- 
cgit v1.2.3-54-g00ecf


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-54-g00ecf


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 ++++++-
 plugins/share/init.php | 5 -----
 2 files changed, 6 insertions(+), 6 deletions(-)

(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 "";
diff --git a/plugins/share/init.php b/plugins/share/init.php
index 4a2a942d7..4dbc389fd 100644
--- a/plugins/share/init.php
+++ b/plugins/share/init.php
@@ -3,14 +3,12 @@ class Share extends Plugin {
 	/** @var PluginHost $host */
 	private $host;
 
-	/** @return array<float|string|null> */
 	function about() {
 		return array(null,
 			"Share article by unique URL",
 			"fox");
 	}
 
-	/** @param PluginHost $host */
 	function init($host) {
 		$this->host = $host;
 
@@ -22,17 +20,14 @@ class Share extends Plugin {
 		return $method == "get";
 	}
 
-	/** @return string */
 	function get_js() {
 		return file_get_contents(__DIR__ . "/share.js");
 	}
 
-	/** @return string */
 	function get_css() {
 		return file_get_contents(__DIR__ . "/share.css");
 	}
 
-	/** @return string */
 	function get_prefs_js() {
 		return file_get_contents(__DIR__ . "/share_prefs.js");
 	}
-- 
cgit v1.2.3-54-g00ecf


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 +-
 plugins/af_psql_trgm/init.php   | 8 +++++++-
 plugins/af_readability/init.php | 3 ++-
 3 files changed, 10 insertions(+), 3 deletions(-)

(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
diff --git a/plugins/af_psql_trgm/init.php b/plugins/af_psql_trgm/init.php
index 87415450b..aea24fea7 100644
--- a/plugins/af_psql_trgm/init.php
+++ b/plugins/af_psql_trgm/init.php
@@ -1,9 +1,13 @@
 <?php
 class Af_Psql_Trgm extends Plugin {
 
-	/* @var PluginHost $host */
+	/** @var PluginHost $host */
 	private $host;
+
+	/** @var float */
 	private $default_similarity = 0.75;
+
+	/** @var int */
 	private $default_min_length = 32;
 
 	function about() {
@@ -12,6 +16,7 @@ class Af_Psql_Trgm extends Plugin {
 			"fox");
 	}
 
+	/** @return void */
 	function save() {
 		$similarity = (float) $_POST["similarity"];
 		$min_title_length = (int) $_POST["min_title_length"];
@@ -45,6 +50,7 @@ class Af_Psql_Trgm extends Plugin {
 		return file_get_contents(__DIR__ . "/init.js");
 	}
 
+	/** @return void */
 	function showrelated() {
 		$id = (int) $_REQUEST['id'];
 		$owner_uid = $_SESSION["uid"];
diff --git a/plugins/af_readability/init.php b/plugins/af_readability/init.php
index a39cc278e..05b229eae 100755
--- a/plugins/af_readability/init.php
+++ b/plugins/af_readability/init.php
@@ -6,7 +6,7 @@ use \andreskrey\Readability\Configuration;
 
 class Af_Readability extends Plugin {
 
-	/* @var PluginHost $host */
+	/** @var PluginHost $host */
 	private $host;
 
 	function about() {
@@ -19,6 +19,7 @@ class Af_Readability extends Plugin {
 		return array("needs_curl" => true);
 	}
 
+	/** @return void */
 	function save() {
 		$enable_share_anything = checkbox_to_sql_bool($_POST["enable_share_anything"] ?? "");
 
-- 
cgit v1.2.3-54-g00ecf


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-54-g00ecf


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 +++++++++++++++++
 plugins/share/init.php |  4 ++--
 2 files changed, 19 insertions(+), 2 deletions(-)

(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);
 	}
diff --git a/plugins/share/init.php b/plugins/share/init.php
index 4dbc389fd..b900de5c0 100644
--- a/plugins/share/init.php
+++ b/plugins/share/init.php
@@ -43,8 +43,8 @@ class Share extends Plugin {
 		print __("Article unshared");
 	}
 
-	/** @param int $id
-	 *
+	/**
+	 * @param string $id
 	 * @return void */
 	function hook_prefs_tab_section($id) {
 		if ($id == "prefFeedsPublishedGenerated") {
-- 
cgit v1.2.3-54-g00ecf


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/auth/base.php          |  1 -
 classes/iauthmodule.php        | 13 ++++++++++++-
 classes/plugin.php             | 18 +++++++++++++++++-
 plugins/auth_internal/init.php |  1 +
 4 files changed, 30 insertions(+), 3 deletions(-)

(limited to 'classes/plugin.php')

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) {
diff --git a/plugins/auth_internal/init.php b/plugins/auth_internal/init.php
index 77f7596f0..b66f7719b 100644
--- a/plugins/auth_internal/init.php
+++ b/plugins/auth_internal/init.php
@@ -12,6 +12,7 @@ class Auth_Internal extends Auth_Base {
 		$host->add_hook($host::HOOK_AUTH_USER, $this);
 	}
 
+	/** @param string $service */
 	function authenticate($login, $password, $service = '') {
 
 		$otp = (int) ($_REQUEST["otp"] ?? 0);
-- 
cgit v1.2.3-54-g00ecf


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/auth/base.php                 |  4 ++--
 classes/iauthmodule.php               | 10 ++++++----
 classes/plugin.php                    | 27 +++++++++++++++++++++------
 plugins/af_youtube_embed/init.php     |  2 +-
 plugins/auth_remote/init.php          |  2 +-
 plugins/cache_starred_images/init.php |  2 +-
 plugins/no_iframes/init.php           |  2 +-
 7 files changed, 33 insertions(+), 16 deletions(-)

(limited to 'classes/plugin.php')

diff --git a/classes/auth/base.php b/classes/auth/base.php
index 939a9d358..9950cbf07 100644
--- a/classes/auth/base.php
+++ b/classes/auth/base.php
@@ -8,8 +8,8 @@ abstract class Auth_Base extends Plugin implements IAuthModule {
 		$this->pdo = Db::pdo();
 	}
 
-	function hook_auth_user(...$args) {
-		return $this->authenticate(...$args);
+	function hook_auth_user($login, $password, $service = '') {
+		return $this->authenticate($login, $password, $service);
 	}
 
 	// Auto-creates specified user if allowed by system configuration
diff --git a/classes/iauthmodule.php b/classes/iauthmodule.php
index 39aae4cc2..dbf8c5587 100644
--- a/classes/iauthmodule.php
+++ b/classes/iauthmodule.php
@@ -3,14 +3,16 @@ interface IAuthModule {
 	/**
 	 * @param string $login
 	 * @param string $password
-	 * optional third string $service
+	 * @param string $service
 	 * @return int|false user_id
 	 */
-	function authenticate($login, $password); // + optional third parameter: $service
+	function authenticate($login, $password, $service = '');
 
 	/** 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 = '');
 }
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);
 	}
 }
diff --git a/plugins/af_youtube_embed/init.php b/plugins/af_youtube_embed/init.php
index 771ee8c46..a1be5562a 100644
--- a/plugins/af_youtube_embed/init.php
+++ b/plugins/af_youtube_embed/init.php
@@ -18,7 +18,7 @@ class Af_Youtube_Embed extends Plugin {
 			"youtu.be"]);
 	}
 
-	function hook_render_enclosure($entry, $hide_images) {
+	function hook_render_enclosure($entry, $id, $rv) {
 
 		$url = $entry["content_url"];
 
diff --git a/plugins/auth_remote/init.php b/plugins/auth_remote/init.php
index b240a9402..35ee9e31d 100644
--- a/plugins/auth_remote/init.php
+++ b/plugins/auth_remote/init.php
@@ -29,7 +29,7 @@ class Auth_Remote extends Auth_Base {
 		return "";
 	}
 
-	function authenticate($login, $password) {
+	function authenticate($login, $password, $service = '') {
 		$try_login = "";
 
 		foreach (["REMOTE_USER", "HTTP_REMOTE_USER", "REDIRECT_REMOTE_USER", "PHP_AUTH_USER"] as $hdr) {
diff --git a/plugins/cache_starred_images/init.php b/plugins/cache_starred_images/init.php
index d94e60504..36e8b73f0 100755
--- a/plugins/cache_starred_images/init.php
+++ b/plugins/cache_starred_images/init.php
@@ -97,7 +97,7 @@ class Cache_Starred_Images extends Plugin {
 		}
 	}
 
-	function hook_enclosure_entry($enc, $article_id) {
+	function hook_enclosure_entry($enc, $article_id, $rv) {
 		$local_filename = $article_id . "-" . sha1($enc["content_url"]);
 
 		if ($this->cache->exists($local_filename)) {
diff --git a/plugins/no_iframes/init.php b/plugins/no_iframes/init.php
index 3cfa15915..dc297b60e 100644
--- a/plugins/no_iframes/init.php
+++ b/plugins/no_iframes/init.php
@@ -11,7 +11,7 @@ class No_Iframes extends Plugin {
 		$host->add_hook($host::HOOK_SANITIZE, $this);
 	}
 
-	function hook_sanitize($doc, $site_url, $allowed_elements, $disallowed_attributes) {
+	function hook_sanitize($doc, $site_url, $allowed_elements, $disallowed_attributes, $article_id) {
 
 		$xpath = new DOMXpath($doc);
 		$entries = $xpath->query('//iframe');
-- 
cgit v1.2.3-54-g00ecf


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 ++++++++++++++++++++++++++++++++++++++++++++++++++
 classes/pluginhost.php | 18 +++++++---
 classes/pref/prefs.php |  2 +-
 3 files changed, 108 insertions(+), 6 deletions(-)

(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) {
diff --git a/classes/pluginhost.php b/classes/pluginhost.php
index 7688a6d0d..4b0c14a35 100755
--- a/classes/pluginhost.php
+++ b/classes/pluginhost.php
@@ -434,16 +434,24 @@ class PluginHost {
 
 				// WIP hack
 				// we can't catch incompatible method signatures via Throwable
-				// maybe also auto-disable user plugin in this situation? idk -fox
-				if ($_SESSION["plugin_blacklist.$class"] ?? false) {
-					user_error("Plugin $class has caused a PHP Fatal Error so it won't be loaded again in this session.", E_USER_NOTICE);
+				// this also enables global tt-rss safe mode in case there are more plugins like this
+				if (($_SESSION["plugin_blacklist"][$class] ?? 0)) {
+
+					// only report once per-plugin per-session
+					if ($_SESSION["plugin_blacklist"][$class] < 2) {
+						user_error("Plugin $class has caused a PHP fatal error so it won't be loaded again in this session.", E_USER_WARNING);
+						$_SESSION["plugin_blacklist"][$class] = 2;
+					}
+
+					$_SESSION["safe_mode"] = 1;
+
 					continue;
 				}
 
 				try {
-					$_SESSION["plugin_blacklist.$class"] = true;
+					$_SESSION["plugin_blacklist"][$class] = 1;
 					require_once $file;
-					$_SESSION["plugin_blacklist.$class"] = false;
+					unset($_SESSION["plugin_blacklist"][$class]);
 
 				} catch (Error $err) {
 					user_error($err, E_USER_WARNING);
diff --git a/classes/pref/prefs.php b/classes/pref/prefs.php
index 3a39bf981..025d8fda2 100644
--- a/classes/pref/prefs.php
+++ b/classes/pref/prefs.php
@@ -17,7 +17,7 @@ class Pref_Prefs extends Handler_Protected {
 	const PI_ERR_PLUGIN_NOT_FOUND = "PI_ERR_PLUGIN_NOT_FOUND";
 	const PI_ERR_NO_WORKDIR = "PI_ERR_NO_WORKDIR";
 
-	function csrf_ignore(string $method): bool {
+	function csrf_ignore($method) : bool {
 		$csrf_ignored = array("index", "updateself", "otpqrcode");
 
 		return array_search($method, $csrf_ignored) !== false;
-- 
cgit v1.2.3-54-g00ecf


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/handler/public.php |  4 ++-
 classes/plugin.php         | 85 +++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 84 insertions(+), 5 deletions(-)

(limited to 'classes/plugin.php')

diff --git a/classes/handler/public.php b/classes/handler/public.php
index e28bb5fd2..b5282c222 100755
--- a/classes/handler/public.php
+++ b/classes/handler/public.php
@@ -93,11 +93,13 @@ class Handler_Public extends Handler {
 				$line["content_preview"] = Sanitizer::sanitize(truncate_string(strip_tags($line["content"]), 100, '...'));
 				$line["tags"] = Article::_get_tags($line["id"], $owner_uid);
 
+				$max_excerpt_length = 250;
+
 				PluginHost::getInstance()->chain_hooks_callback(PluginHost::HOOK_QUERY_HEADLINES,
 					function ($result) use (&$line) {
 						$line = $result;
 					},
-					$line);
+					$line, $max_excerpt_length);
 
 				PluginHost::getInstance()->chain_hooks_callback(PluginHost::HOOK_ARTICLE_EXPORT_FEED,
 					function ($result) use (&$line) {
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-54-g00ecf


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 ++++++++++++++++++++++++++++++++++++++++-
 plugins/af_readability/init.php |  1 +
 2 files changed, 48 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) {
diff --git a/plugins/af_readability/init.php b/plugins/af_readability/init.php
index 05b229eae..8e75d0c2e 100755
--- a/plugins/af_readability/init.php
+++ b/plugins/af_readability/init.php
@@ -187,6 +187,7 @@ class Af_Readability extends Plugin {
 			case "action_append":
 				return $this->process_article($article, true);
 		}
+		return $article;
 	}
 
 	public function extract_content($url) {
-- 
cgit v1.2.3-54-g00ecf


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 ++++++++++++++++++++++++++++++++++++++++++++++
 plugins/af_comics/init.php |  1 +
 2 files changed, 56 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;
 	}
 }
diff --git a/plugins/af_comics/init.php b/plugins/af_comics/init.php
index 84d95a2ba..a9a8f3faa 100755
--- a/plugins/af_comics/init.php
+++ b/plugins/af_comics/init.php
@@ -1,6 +1,7 @@
 <?php
 class Af_Comics extends Plugin {
 
+	/** @var array<object> $filters */
 	private $filters = array();
 
 	function about() {
-- 
cgit v1.2.3-54-g00ecf


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-54-g00ecf


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 ++--
 plugins/af_youtube_embed/init.php | 2 ++
 2 files changed, 4 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);
diff --git a/plugins/af_youtube_embed/init.php b/plugins/af_youtube_embed/init.php
index a1be5562a..ff44bb291 100644
--- a/plugins/af_youtube_embed/init.php
+++ b/plugins/af_youtube_embed/init.php
@@ -32,6 +32,8 @@ class Af_Youtube_Embed extends Plugin {
 				</div>";
 
 		}
+
+		return "";
 	}
 
 	function api_version() {
-- 
cgit v1.2.3-54-g00ecf


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-54-g00ecf


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-54-g00ecf


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-54-g00ecf


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-54-g00ecf


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 +++++++++++++++++++++++++++++++++--------
 classes/pluginhost.php | 102 ++++++++++++++++++++++++-------------------------
 2 files changed, 119 insertions(+), 68 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);
diff --git a/classes/pluginhost.php b/classes/pluginhost.php
index 4b0c14a35..83868514c 100755
--- a/classes/pluginhost.php
+++ b/classes/pluginhost.php
@@ -48,155 +48,151 @@ class PluginHost {
 	const API_VERSION = 2;
 	const PUBLIC_METHOD_DELIMITER = "--";
 
-	// Hooks marked with *1 are run in global context and available
-	// to plugins loaded in config.php only
-
-	/** hook_article_button($line) */
+	/** @see Plugin::hook_article_button() */
 	const HOOK_ARTICLE_BUTTON = "hook_article_button";
 
-	/** hook_article_filter($article) */
+	/** @see Plugin::hook_article_filter() */
 	const HOOK_ARTICLE_FILTER = "hook_article_filter";
 
-	/** hook_prefs_tab($tab) */
+	/** @see Plugin::hook_prefs_tab() */
 	const HOOK_PREFS_TAB = "hook_prefs_tab";
 
-	/** hook_prefs_tab_section($section) */
+	/** @see Plugin::hook_prefs_tab_section() */
 	const HOOK_PREFS_TAB_SECTION = "hook_prefs_tab_section";
 
-	/** hook_prefs_tabs() */
+	/** @see Plugin::hook_prefs_tabs() */
 	const HOOK_PREFS_TABS = "hook_prefs_tabs";
 
-	/** hook_feed_parsed($parser, $feed_id) */
+	/** @see Plugin::hook_feed_parsed() */
 	const HOOK_FEED_PARSED = "hook_feed_parsed";
 
-	/** GLOBAL: hook_update_task($cli_options) */
+	/** @see Plugin::hook_update_task() */
 	const HOOK_UPDATE_TASK = "hook_update_task"; //*1
 
-	/** hook_auth_user($login, $password, $service) (byref) */
+	/** @see Plugin::hook_auth_user() */
 	const HOOK_AUTH_USER = "hook_auth_user";
 
-	/** hook_hotkey_map($hotkeys) (byref) */
+	/** @see Plugin::hook_hotkey_map() */
 	const HOOK_HOTKEY_MAP = "hook_hotkey_map";
 
-	/** hook_render_article($article) */
+	/** @see Plugin::hook_render_article() */
 	const HOOK_RENDER_ARTICLE = "hook_render_article";
 
-	/** hook_render_article_cdm($article) */
+	/** @see Plugin::hook_render_article_cdm() */
 	const HOOK_RENDER_ARTICLE_CDM = "hook_render_article_cdm";
 
-	/** hook_feed_fetched($feed_data, $fetch_url, $owner_uid, $feed) (byref) */
+	/** @see Plugin::hook_feed_fetched() */
 	const HOOK_FEED_FETCHED = "hook_feed_fetched";
 
-	/** hook_sanitize($doc, $site_url, $allowed_elements, $disallowed_attributes, $article_id) (byref) */
+	/** @see Plugin::hook_sanitize() */
 	const HOOK_SANITIZE = "hook_sanitize";
 
-	/** hook_render_article_api($params) */
+	/** @see Plugin::hook_render_article_api() */
 	const HOOK_RENDER_ARTICLE_API = "hook_render_article_api";
 
-	/** hook_toolbar_button() */
+	/** @see Plugin::hook_toolbar_button() */
 	const HOOK_TOOLBAR_BUTTON = "hook_toolbar_button";
 
-	/** hook_action_item() */
+	/** @see Plugin::hook_action_item() */
 	const HOOK_ACTION_ITEM = "hook_action_item";
 
-	/** hook_headline_toolbar_button($feed_id, $is_cat) */
+	/** @see Plugin::hook_headline_toolbar_button() */
 	const HOOK_HEADLINE_TOOLBAR_BUTTON = "hook_headline_toolbar_button";
 
-	/** hook_hotkey_info($hotkeys) (byref) */
+	/** @see Plugin::hook_hotkey_info() */
 	const HOOK_HOTKEY_INFO = "hook_hotkey_info";
 
-	/** hook_article_left_button($row) */
+	/** @see Plugin::hook_article_left_button() */
 	const HOOK_ARTICLE_LEFT_BUTTON = "hook_article_left_button";
 
-	/** hook_prefs_edit_feed($feed_id) */
+	/** @see Plugin::hook_prefs_edit_feed() */
 	const HOOK_PREFS_EDIT_FEED = "hook_prefs_edit_feed";
 
-	/** hook_prefs_save_feed($feed_id) */
+	/** @see Plugin::hook_prefs_save_feed() */
 	const HOOK_PREFS_SAVE_FEED = "hook_prefs_save_feed";
 
-	/** hook_fetch_feed($feed_data, $fetch_url, $owner_uid, $feed, $last_article_timestamp, $auth_login, $auth_pass) (byref) */
+	/** @see Plugin::hook_fetch_feed() */
 	const HOOK_FETCH_FEED = "hook_fetch_feed";
 
-	/** hook_query_headlines($row) (byref) */
+	/** @see Plugin::hook_query_headlines() */
 	const HOOK_QUERY_HEADLINES = "hook_query_headlines";
 
-	/** GLOBAL: hook_house_keeping() */
+	/** @see Plugin::hook_house_keeping() */
 	const HOOK_HOUSE_KEEPING = "hook_house_keeping"; //*1
 
-	/** hook_search($query) */
+	/** @see Plugin::hook_search() */
 	const HOOK_SEARCH = "hook_search";
 
-	/** hook_format_enclosures($rv, $result, $id, $always_display_enclosures, $article_content, $hide_images) (byref) */
+	/** @see Plugin::hook_format_enclosures() */
 	const HOOK_FORMAT_ENCLOSURES = "hook_format_enclosures";
 
-	/** hook_subscribe_feed($contents, $url, $auth_login, $auth_pass) (byref) */
+	/** @see Plugin::hook_subscribe_feed() */
 	const HOOK_SUBSCRIBE_FEED = "hook_subscribe_feed";
 
-	/** hook_headlines_before($feed, $is_cat, $qfh_ret) */
+	/** @see Plugin::hook_headlines_before() */
 	const HOOK_HEADLINES_BEFORE = "hook_headlines_before";
 
-	/** hook_render_enclosure($entry, $id, $rv) */
+	/** @see Plugin::hook_render_enclosure() */
 	const HOOK_RENDER_ENCLOSURE = "hook_render_enclosure";
 
-	/** hook_article_filter_action($article, $action) */
+	/** @see Plugin::hook_article_filter_action() */
 	const HOOK_ARTICLE_FILTER_ACTION = "hook_article_filter_action";
 
-	/** hook_article_export_feed($line, $feed, $is_cat, $owner_uid) (byref) */
+	/** @see Plugin::hook_article_export_feed() */
 	const HOOK_ARTICLE_EXPORT_FEED = "hook_article_export_feed";
 
-	/** hook_main_toolbar_button() */
+	/** @see Plugin::hook_main_toolbar_button() */
 	const HOOK_MAIN_TOOLBAR_BUTTON = "hook_main_toolbar_button";
 
-	/** hook_enclosure_entry($entry, $id, $rv) (byref) */
+	/** @see Plugin::hook_enclosure_entry() */
 	const HOOK_ENCLOSURE_ENTRY = "hook_enclosure_entry";
 
-	/** hook_format_article($html, $row) */
+	/** @see Plugin::hook_format_article() */
 	const HOOK_FORMAT_ARTICLE = "hook_format_article";
 
-	/** @deprecated removed, do not use */
+	/** @see Plugin::hook_format_article_cdm() */
 	const HOOK_FORMAT_ARTICLE_CDM = "hook_format_article_cdm";
 
-	/** hook_feed_basic_info($basic_info, $fetch_url, $owner_uid, $feed_id, $auth_login, $auth_pass) (byref) */
+	/** @see Plugin::hook_feed_basic_info() */
 	const HOOK_FEED_BASIC_INFO = "hook_feed_basic_info";
 
-	/** hook_send_local_file($filename) */
+	/** @see Plugin::hook_send_local_file() */
 	const HOOK_SEND_LOCAL_FILE = "hook_send_local_file";
 
-	/** hook_unsubscribe_feed($feed_id, $owner_uid) */
+	/** @see Plugin::hook_unsubscribe_feed() */
 	const HOOK_UNSUBSCRIBE_FEED = "hook_unsubscribe_feed";
 
-	/** hook_send_mail(Mailer $mailer, $params) */
+	/** @see Plugin::hook_send_mail() */
 	const HOOK_SEND_MAIL = "hook_send_mail";
 
-	/** hook_filter_triggered($feed_id, $owner_uid, $article, $matched_filters, $matched_rules, $article_filters) */
+	/** @see Plugin::hook_filter_triggered() */
 	const HOOK_FILTER_TRIGGERED = "hook_filter_triggered";
 
-	/** hook_get_full_text($url) */
+	/** @see Plugin::hook_get_full_text() */
 	const HOOK_GET_FULL_TEXT = "hook_get_full_text";
 
-	/** hook_article_image($enclosures, $content, $site_url) */
+	/** @see Plugin::hook_article_image() */
 	const HOOK_ARTICLE_IMAGE = "hook_article_image";
 
-	/** hook_feed_tree() */
+	/** @see Plugin::hook_feed_tree() */
 	const HOOK_FEED_TREE = "hook_feed_tree";
 
-	/** hook_iframe_whitelisted($url) */
+	/** @see Plugin::hook_iframe_whitelisted() */
 	const HOOK_IFRAME_WHITELISTED = "hook_iframe_whitelisted";
 
-	/** hook_enclosure_imported($enclosure, $feed) */
+	/** @see Plugin::hook_enclosure_imported() */
 	const HOOK_ENCLOSURE_IMPORTED = "hook_enclosure_imported";
 
-	/** hook_headlines_custom_sort_map() */
+	/** @see Plugin::hook_headlines_custom_sort_map() */
 	const HOOK_HEADLINES_CUSTOM_SORT_MAP = "hook_headlines_custom_sort_map";
 
-	/** hook_headlines_custom_sort_override($order) */
+	/** @see Plugin::hook_headlines_custom_sort_override() */
 	const HOOK_HEADLINES_CUSTOM_SORT_OVERRIDE = "hook_headlines_custom_sort_override";
 
-	/** hook_headline_toolbar_select_menu_item($feed_id, $is_cat) */
+	/** @see Plugin::hook_headline_toolbar_select_menu_item() */
 	const HOOK_HEADLINE_TOOLBAR_SELECT_MENU_ITEM = "hook_headline_toolbar_select_menu_item";
 
-
-	/** hook_pre_subscribe($url, $auth_login, $auth_pass) (byref) */
+	/** @see Plugin::hook_pre_subscribe() */
 	const HOOK_PRE_SUBSCRIBE = "hook_pre_subscribe";
 
 	const KIND_ALL = 1;
-- 
cgit v1.2.3-54-g00ecf


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-54-g00ecf


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-54-g00ecf