diff --git a/docs/en/developers/03_Backend/05_Extensions.md b/docs/en/developers/03_Backend/05_Extensions.md index 328a46646..3773d9bf8 100644 --- a/docs/en/developers/03_Backend/05_Extensions.md +++ b/docs/en/developers/03_Backend/05_Extensions.md @@ -119,7 +119,7 @@ The `Minz_Extension` abstract class defines another set of methods that should n * `getFileUrl(string $filename, bool $isStatic = true): string` will return the URL to a file in the `static` directory. The first parameter is the name of the file (without `static/`). Set `$isStatic` to true for user-independent files, and to `false` for files saved in a user’s own directory. -* the `registerController` method register an extension controller in FreshRSS. The selected controller must be defined in the extension *Controllers* folder, its file name must be `\Controller.php`, and its class name must be `FreshExtension_\_Controller`. +* the `registerController` method registers an extension controller in FreshRSS. The selected controller must be defined in the extension *Controllers* folder, its file name must be `Controller.php`, and its class name must be `FreshExtension__Controller`. * the `registerViews` method registers the extension views in FreshRSS. * the `registerTranslates` method registers the extension translation files in FreshRSS. * the `registerHook` method registers hook actions in different part of the application. @@ -167,42 +167,43 @@ final class HelloWorldExtension extends Minz_Extension The following events are available: -* `action_execute` (`function(Minz_Controller $controller): bool`): Called before an action is executed in `Minz_Dispatcher::launchAction()`. +* `Minz_HookType::ActionExecute` (`function(Minz_ActionController $controller): bool`): Called before an action is executed in `Minz_Dispatcher::launchAction()`. By returning `true`, you allow the original action to proceed further; `false` stops further execution of the action. This hook can be used for adding extra functionality to an existing action. See also: `Minz_Request::is()`, `Minz_Request::controllerName()`, `Minz_Request::actionName()`. -* `api_misc` (`function(): void`): to allow extensions to have their own API endpoint - on `/api/misc.php/Extension%20Name/` or `/api/misc.php?ext=Extension%20Name`. -* `before_login_btn` (`function(): string`): Allows to insert HTML before the login button. Applies to the create button on the register page as well. Example use case is inserting a captcha widget. -* `check_url_before_add` (`function($url) -> Url | null`): will be executed every time a URL is added. The URL itself will be passed as parameter. This way a website known to have feeds which doesn’t advertise it in the header can still be automatically supported. -* `custom_favicon_btn_url` (`function(FreshRSS_Feed $feed): string | null`): Allows extensions to implement a button for setting a custom favicon for individual feeds by providing an URL. The URL will be sent a POST request with the `extAction` field set to either `query_icon_info` or `update_icon`, along with an `id` field which describes the feed's ID. +* `Minz_HookType::ApiMisc` (`function(): void`): to allow extensions to have their own API endpoint +* `Minz_HookType::BeforeLoginBtn` (`function(): string`): Allows to insert HTML before the login button. Applies to the create button on the register page as well. Example use case is inserting a captcha widget. +* `Minz_HookType::CheckUrlBeforeAdd` (`function($url) -> Url | null`): will be executed every time a URL is added. The URL itself will be passed as parameter. This way a website known to have feeds which doesn’t advertise it in the header can still be automatically supported. +* `Minz_HookType::CustomFaviconBtnUrl` (`function(FreshRSS_Feed $feed): string | null`): Allows extensions to implement a button for setting a custom favicon for individual feeds by providing an URL. The URL will be sent a POST request with the `extAction` field set to either `query_icon_info` or `update_icon`, along with an `id` field which describes the feed's ID. Example response for a `query_icon_info` request: ```json {"extName":"YouTube Video Feed","iconUrl":"..\/f.php?h=40838a43"} ``` -* `custom_favicon_hash` (`function(FreshRSS_Feed $feed): string | null`): Enables the modification of custom favicon hashes by returning params from the hook function. The hook should check if the `customFaviconExt` attribute of `$feed` is set to the extension's name before returning a custom value. Otherwise, the return value should be null. -* `entry_auto_read` (`function(FreshRSS_Entry $entry, string $why): void`): Triggered when an entry is automatically marked as read. The *why* parameter supports the rules {`filter`, `upon_reception`, `same_title_in_feed`}. -* `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. -* `freshrss_user_maintenance` (`function() -> none`): will be executed for each user during the `actualize_script`, useful to run some maintenance tasks on the user. -* `js_vars` (`function($vars = array) -> array | null`): will be executed if the `jsonVars` in the header will be generated. -* `menu_admin_entry` (`function() -> string`): add an entry at the end of the "Administration" menu, the returned string must be valid HTML (e.g. `
  • New entry
  • `). -* `menu_configuration_entry` (`function() -> string`): add an entry at the end of the "Configuration" menu, the returned string must be valid HTML (e.g. `
  • New entry
  • `). -* `menu_other_entry` (`function() -> string`): add an entry at the end of the header dropdown menu (i.e. after the "About" entry), the returned string must be valid HTML (e.g. `
  • New entry
  • `). -* `nav_entries` (`function() -> string`): will add DOM elements before the navigation buttons. -* `nav_menu` (`function() -> string`): will be executed if the navigation was built. -* `nav_reading_modes` (`function($reading_modes) -> array | null`): **TODO** add documentation. -* `post_update` (`function(none) -> none`): **TODO** add documentation. -* `simplepie_after_init` (`function(FreshRSS_SimplePieCustom $simplePie, FreshRSS_Feed $feed, bool $result): void`): Triggered after fetching an RSS/Atom feed with SimplePie. Useful for instance to get the HTTP response headers (e.g. `$simplePie->data['headers']`). -* `simplepie_before_init` (`function(FreshRSS_SimplePieCustom $simplePie, FreshRSS_Feed $feed): void`): Triggered before fetching an RSS/Atom feed with SimplePie. -* `view_modes` (`function(array $viewModes): array|null`): Allow extensions to register additional view modes than *normal*, *reader*, *global*. +* `Minz_HookType::CustomFaviconHash` (`function(FreshRSS_Feed $feed): string | null`): Enables the modification of custom favicon hashes by returning params from the hook function. The hook should check if the `customFaviconExt` attribute of `$feed` is set to the extension's name before returning a custom value. Otherwise, the return value should be null. +* `Minz_HookType::EntriesFavorite` (`function(array $ids, bool $is_favorite): void`): + will be executed when some entries are marked or unmarked as favorites (starred) +* `Minz_HookType::EntryAutoRead` (`function(FreshRSS_Entry $entry, string $why): void`): Triggered when an entry is automatically marked as read. The *why* parameter supports the rules {`filter`, `upon_reception`, `same_title_in_feed`}. +* `Minz_HookType::EntryAutoUnread` (`function(FreshRSS_Entry $entry, string $why): void`): Triggered when an entry is automatically marked as unread. The *why* parameter supports the rules {`updated_article`}. +* `Minz_HookType::EntryBeforeDisplay` (`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. +* `Minz_HookType::EntryBeforeInsert` (`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. +* `Minz_HookType::EntryBeforeAdd` (`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. +* `Minz_HookType::EntryBeforeUpdate` (`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. +* `Minz_HookType::FeedBeforeActualize` (`function($feed) -> Feed | null`): will be executed when a feed is updated. The feed (instance of FreshRSS\_Feed) will be passed as parameter. +* `Minz_HookType::FeedBeforeInsert` (`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. +* `Minz_HookType::FreshrssInit` (`function() -> none`): will be executed at the end of the initialization of FreshRSS, useful to initialize components or to do additional access checks. +* `Minz_HookType::FreshrssUserMaintenance` (`function() -> none`): will be executed for each user during the `actualize_script`, useful to run some maintenance tasks on the user. +* `Minz_HookType::JsVars` (`function($vars = array) -> array | null`): will be executed if the `jsonVars` in the header will be generated. +* `Minz_HookType::MenuAdminEntry` (`function() -> string`): add an entry at the end of the "Administration" menu, the returned string must be valid HTML (e.g. `
  • New entry
  • `). +* `Minz_HookType::MenuConfigurationEntry` (`function() -> string`): add an entry at the end of the "Configuration" menu, the returned string must be valid HTML (e.g. `
  • New entry
  • `). +* `Minz_HookType::MenuOtherEntry` (`function() -> string`): add an entry at the end of the header dropdown menu (i.e. after the "About" entry), the returned string must be valid HTML (e.g. `
  • New entry
  • `). +* `Minz_HookType::NavEntries` (`function() -> string`): will add DOM elements before the navigation buttons. +* `Minz_HookType::NavMenu` (`function() -> string`): will be executed if the navigation was built. +* `Minz_HookType::NavReadingModes` (`function($reading_modes) -> array | null`): **TODO** add documentation. +* `Minz_HookType::PostUpdate` (`function(none) -> none`): **TODO** add documentation. +* `Minz_HookType::SimplepieAfterInit` (`function(FreshRSS_SimplePieCustom $simplePie, FreshRSS_Feed $feed, bool $result): void`): Triggered after fetching an RSS/Atom feed with SimplePie. Useful for instance to get the HTTP response headers (e.g. `$simplePie->data['headers']`). +* `Minz_HookType::SimplepieBeforeInit` (`function(FreshRSS_SimplePieCustom $simplePie, FreshRSS_Feed $feed): void`): Triggered before fetching an RSS/Atom feed with SimplePie. +* `Minz_HookType::ViewModes` (`function(array $viewModes): array|null`): Allow extensions to register additional view modes than *normal*, *reader*, *global*. -> ℹ️ Note: the `simplepie_*` hooks are only fired for feeds using SimplePie via pull, i.e. normal RSS/Atom feeds. This excludes WebSub (push), and the various HTML or JSON Web scraping methods. +> ℹ️ Note: the `Minz_HookType::Simplepie*` hooks are only fired for feeds using SimplePie via pull, i.e. normal RSS/Atom feeds. This excludes WebSub (push), and the various HTML or JSON Web scraping methods. ### JavaScript events @@ -220,7 +221,7 @@ if (document.readyState && document.readyState !== 'loading' && typeof window.co The following events are available: -* `freshrss:globalContextLoaded`: will be dispatched after load the global `context` variable, useful for referencing variables injected with the `js_vars` hook. +* `freshrss:globalContextLoaded`: will be dispatched after load the global `context` variable, useful for referencing variables injected with the `Minz_HookType::JsVars` hook. ### Injecting CDN content diff --git a/lib/Minz/Extension.php b/lib/Minz/Extension.php index 51088a7a9..8c02caa3f 100644 --- a/lib/Minz/Extension.php +++ b/lib/Minz/Extension.php @@ -258,11 +258,11 @@ abstract class Minz_Extension { /** * Register a new hook. * - * @param string $hook_name the hook name (must exist). + * @param Minz_HookType|string $hook_name the hook name (must exist). * @param callable $hook_function the function name to call (must be callable). * @param int $priority the priority of the hook, default priority is 0, the higher the value the lower the priority */ - final protected function registerHook(string $hook_name, $hook_function, int $priority = Minz_Hook::DEFAULT_PRIORITY): void { + final protected function registerHook(Minz_HookType|string $hook_name, $hook_function, int $priority = Minz_Hook::DEFAULT_PRIORITY): void { Minz_ExtensionManager::addHook($hook_name, $hook_function, $priority); }