From d670bf1e72d92c3bbeeca874f6a042f4e3a74007 Mon Sep 17 00:00:00 2001
From: KleinMann <47398070+rnkln@users.noreply.github.com>
Date: Thu, 18 Sep 2025 23:44:17 +0200
Subject: Add `entry_before_update` and `entry_before_add` hooks (#7977)

Discussion: https://github.com/FreshRSS/FreshRSS/discussions/7973

Changes proposed in this pull request:

- Add new extension hook "entry_before_add"
- Add new extension hook "entry_before_update"

How to test the feature manually:

1. Create extension that uses the hooks and confirm they are invoked correctly.

Extension to use for testing
https://github.com/rnkln/freshrss-xExtension-Discord/pull/2
---
 app/Controllers/feedController.php             | 12 ++++++++++++
 app/Controllers/importExportController.php     | 13 +++++++++++++
 docs/en/developers/03_Backend/05_Extensions.md |  2 ++
 docs/fr/developers/03_Backend/05_Extensions.md |  8 ++++++++
 lib/Minz/ExtensionManager.php                  |  8 ++++++++
 5 files changed, 43 insertions(+)

diff --git a/app/Controllers/feedController.php b/app/Controllers/feedController.php
index a7c1d15bc..a63109c31 100644
--- a/app/Controllers/feedController.php
+++ b/app/Controllers/feedController.php
@@ -639,6 +639,12 @@ class FreshRSS_feed_Controller extends FreshRSS_ActionController {
 							// If the entry has changed, there is a good chance for the full content to have changed as well.
 							$entry->loadCompleteContent(true);
 
+							$entry = Minz_ExtensionManager::callHook('entry_before_update', $entry);
+							if (!($entry instanceof FreshRSS_Entry)) {
+								// An extension has returned a null value, there is nothing to insert.
+								continue;
+							}
+
 							$entryDAO->updateEntry($entry->toArray());
 						}
 					} else {
@@ -672,6 +678,12 @@ class FreshRSS_feed_Controller extends FreshRSS_ActionController {
 							$feed->pubSubHubbubError(true);
 						}
 
+						$entry = Minz_ExtensionManager::callHook('entry_before_add', $entry);
+						if (!($entry instanceof FreshRSS_Entry)) {
+							// An extension has returned a null value, there is nothing to insert.
+							continue;
+						}
+
 						if ($entryDAO->addEntry($entry->toArray(), true)) {
 							$nbNewArticles++;
 						}
diff --git a/app/Controllers/importExportController.php b/app/Controllers/importExportController.php
index 6ecd9b501..9f9f6b2bd 100644
--- a/app/Controllers/importExportController.php
+++ b/app/Controllers/importExportController.php
@@ -485,9 +485,22 @@ class FreshRSS_importExport_Controller extends FreshRSS_ActionController {
 			}
 
 			if (isset($existingHashForGuids['f_' . $feed_id][$entry->guid()])) {
+				$entry = Minz_ExtensionManager::callHook('entry_before_update', $entry);
+				if (!($entry instanceof FreshRSS_Entry)) {
+					// An extension has returned a null value, there is nothing to insert.
+					continue;
+				}
+
 				$ok = $this->entryDAO->updateEntry($entry->toArray());
 			} else {
 				$entry->_lastSeen(time());
+
+				$entry = Minz_ExtensionManager::callHook('entry_before_add', $entry);
+				if (!($entry instanceof FreshRSS_Entry)) {
+					// An extension has returned a null value, there is nothing to insert.
+					continue;
+				}
+
 				$ok = $this->entryDAO->addEntry($entry->toArray());
 			}
 
diff --git a/docs/en/developers/03_Backend/05_Extensions.md b/docs/en/developers/03_Backend/05_Extensions.md
index 6550b8e6a..fcae42b5a 100644
--- a/docs/en/developers/03_Backend/05_Extensions.md
+++ b/docs/en/developers/03_Backend/05_Extensions.md
@@ -178,6 +178,8 @@ Example response for a `query_icon_info` request:
 * `entry_auto_unread` (`function(FreshRSS_Entry $entry, string $why): void`): Triggered when an entry is automatically marked as unread. The *why* parameter supports the rules {`updated_article`}.
 * `entry_before_display` (`function($entry) -> Entry | null`): will be executed every time an entry is rendered. The entry itself (instance of FreshRSS\_Entry) will be passed as parameter.
 * `entry_before_insert` (`function($entry) -> Entry | null`): will be executed when a feed is refreshed and new entries will be imported into the database. The new entry (instance of FreshRSS\_Entry) will be passed as parameter.
+* `entry_before_add` (`function($entry) -> Entry | null`): will be executed when a feed is refreshed and just before an entry is added to the database. Useful for reading the final state of the entry after filter actions have been applied. The new entry (instance of FreshRSS\_Entry) will be passed as parameter.
+* `entry_before_update` (`function($entry) -> Entry | null`): will be executed when a feed is refreshed and just before an entry is updated in the database. Useful for reading the final state of the entry after filter actions have been applied. The updated entry (instance of FreshRSS\_Entry) will be passed as parameter.
 * `feed_before_actualize` (`function($feed) -> Feed | null`): will be executed when a feed is updated. The feed (instance of FreshRSS\_Feed) will be passed as parameter.
 * `feed_before_insert` (`function($feed) -> Feed | null`): will be executed when a new feed is imported into the database. The new feed (instance of FreshRSS\_Feed) will be passed as parameter.
 * `freshrss_init` (`function() -> none`): will be executed at the end of the initialization of FreshRSS, useful to initialize components or to do additional access checks.
diff --git a/docs/fr/developers/03_Backend/05_Extensions.md b/docs/fr/developers/03_Backend/05_Extensions.md
index cdf70fe74..18cc892be 100644
--- a/docs/fr/developers/03_Backend/05_Extensions.md
+++ b/docs/fr/developers/03_Backend/05_Extensions.md
@@ -235,6 +235,14 @@ The following events are available:
 	executed when a feed is refreshed and new entries will be imported into
 	the database. The new entry (instance of FreshRSS\_Entry) will be passed
 	as parameter.
+* `entry_before_add` (`function($entry) -> Entry | null`): will be
+	executed when a feed is refreshed and just before an entry is added to the database.
+	Useful for reading the final state of the entry after filter actions have been applied.
+	The new entry (instance of FreshRSS\_Entry) will be passed as parameter.
+* `entry_before_update` (`function($entry) -> Entry | null`): will be
+	executed when a feed is refreshed and just before an entry is updated in the database.
+	Useful for reading the final state of the entry after filter actions have been applied.
+	The updated entry (instance of FreshRSS\_Entry) will be passed as parameter.
 * `entries_favorite` (`function(array $ids, bool $is_favorite): void`):
 	will be executed when some entries are marked or unmarked as favorites (starred)
 * `feed_before_actualize` (`function($feed) -> Feed | null`): will be
diff --git a/lib/Minz/ExtensionManager.php b/lib/Minz/ExtensionManager.php
index b3a29f9f7..b91a89de7 100644
--- a/lib/Minz/ExtensionManager.php
+++ b/lib/Minz/ExtensionManager.php
@@ -62,6 +62,14 @@ final class Minz_ExtensionManager {
 			'list' => [],
 			'signature' => 'OneToOne',
 		],
+		'entry_before_add' => [	// function($entry) -> Entry | null
+			'list' => [],
+			'signature' => 'OneToOne',
+		],
+		'entry_before_update' => [	// function($entry) -> Entry | null
+			'list' => [],
+			'signature' => 'OneToOne',
+		],
 		'feed_before_actualize' => [	// function($feed) -> Feed | null
 			'list' => [],
 			'signature' => 'OneToOne',
-- 
cgit v1.2.3