Add a generic hook system: Actions, Filters and Resolvers

[kainhofer]

Summary

Adds Admidio's foundation for extensibility: Actions (notify), Filters (transform), and Resolvers (ask for one answer), dispatched by a single static registry (Admidio\Hooks\Hooks). The goal is to let a plugin observe or adjust core behaviour — a value before it's saved, a form before it's rendered, a login attempt, a list row — without patching core files.

Documentation: https://www.admidio.org/dokuwiki/doku.php?id=en:entwickler:hooks

The design has three layers:

• Generic entity hooks (entity_created, entity_value, …) for genuinely cross-cutting consumers — an audit log, a sync framework.
• Entity-specific hooks (oidc_client_created, event_updated, …), the normal plugin-facing CRUD API. Both layers are dispatched automatically from one central Entity lifecycle, for all 36 entities that opted in — nothing is hand-wired per module.
• Semantic/system hooks where the interesting boundary isn't one entity save: forms (form_built, form_select_options), pages (page_title, page_before_render), components (component_visible), translation (translation_missing as a resolver), login/logout, email, and a first generic list vocabulary (list_columns, list_data, list_row_actions, list_rendered_data) proven end-to-end on the Contacts list.

Persistence hooks are transaction-aware: dispatched only after the outermost commit, coalesced when one record is saved twice in a transaction, and carry an immutable EntityChangeSet (old/new values per field, a snapshot for deletions) so a listener never needs its own before/after cache. ChangeNotification — the existing "mail admins about profile changes" feature — was migrated onto this as the first real consumer, replacing 14 hand-written call sites with three listeners.

Not in this PR: a plugin loading/discovery mechanism (deliberately out of scope — this PR is the hook engine, not the plugin system that would register callbacks into it), and converting the remaining list-based modules (Inventory, Category Report, Changelog) to the new list hooks, which Contacts alone was chosen to prove first.

General Idea

The general idea of filters and actions is similar to the WordPress approach, which makes WP so versatile and easy to tweak. The modifications should not need to implement certain classes or interfaces or follow strict rules. Simply registering one callback function that will be called automatically by the core is enough to modify core behavior.

This actions/filters/resolvers feature also needs a generic plugin system, which I'm currently also designing and implementing. Having an easy, simple plugin system together with this actions/filters/resolvers provides an enormous amount of possibilities to configure / modify even core behavior and easily extend admidio in ways I can't even think about yet.

Simple examples

Add some JS to the settings page: Place this php code in some file that is loaded (e.g. at the end of common.php for now, later these callbacks will typically be registered by plugins):

Admidio\Hooks\Hooks::addAction('page_before_render', function (Admidio\UI\Presenter\PagePresenter  $page) {
    if ($page->getHtmlID() === 'adm_preferences') {
        $page->addJavascript('alert("Discuss all changes with the webmaster first.");', true);
    }
});

That's it... All other uses are equally simple, like restricting the email field to a certain domain when modifying profiles:

Admidio\Hooks\Hooks::addFilter('user_data_value', function (mixed $value, Admidio\Infrastructure\Entity\Entity $userData, string $columnName, mixed $oldValue) {
    if ($columnName !== 'usd_value') {
        return $value;
    }
    // reject an email outside the association's domain
    if ($userData->getValue('usf_name_intern') === 'EMAIL' && !str_ends_with($value, '@example.org')) {
        throw new Exception('Only @example.org addresses are allowed.');
    }
    return $value;
});

The profile change mail notifications were already modified to listen to the user_created/user_updated/user_deleted/user_data_.../membership_... actions instead of being hardcoded in the setValue calls. ChangeNotificatiion::registerListeners:

    protected function registerListeners(): void
    {
        foreach (array('created', 'updated', 'deleted') as $stage) {
            Hooks::addAction('user_' . $stage, array($this, 'onUserChanged'), Hooks::DEFAULT_PRIORITY, 1, 'change_notification');
            Hooks::addAction('user_data_' . $stage, array($this, 'onUserDataChanged'), Hooks::DEFAULT_PRIORITY, 1, 'change_notification');
            Hooks::addAction('membership_' . $stage, array($this, 'onMembershipChanged'), Hooks::DEFAULT_PRIORITY, 1, 'change_notification');
        }
    }