We plan to establish a mandatory and strong connection between sources and event rules. This is a breaking change.

When creating a new event rule, the user must not only choose a name, but also to which source the rule belongs to. If there are no sources configured yet, the button must be disabled and the user pointed to the source configuration, just like it's been done as part of other recent changes.

Regarding compatibility with existing rules configured before this change, we'll have to think about this eventually, but there's no need for that right now.

The filter capabilities of event rules are severely limited at the moment. To enhance this and to provide enough flexibility for source integrations, the latter are now required. In order to configure sources or filters in an event rule, a source integration is mandatory. The integration is now expected to provide the necessary controls to configure the filter. If no integration is available, neither a source nor event rules can be configured.

A source integration (e.g. Icinga DB Web) must provide an implementation for the following hook:

<?php

/* Icinga Notifications Web | (c) 2025 Icinga GmbH | GPLv2 */

namespace Icinga\Module\Notifications\Hook\V1;

use ipl\Html\Contract\Form;
use ipl\Web\Widget\Icon;

interface SourceHook
{
    /**
     * Get the type of source this integration is responsible for
     *
     * @return string
     */
    public function getSourceType(): string;

    /**
     * Get the label of the source this integration is responsible for
     *
     * @return string
     */
    public function getSourceLabel(): string;

    /**
     * Get the icon of the source this integration is responsible for
     *
     * @return Icon
     */
    public function getSourceIcon(): Icon;

    /**
     * Get available filter targets for event rules
     *
     * If this returns an array of length 1, {@see getRuleFilterEditor()} will immediately be called with the item's
     * key. If the returned array contains multiple values, a simple select box will be rendered first, and the user
     * has to choose an item from the list.
     *
     * @param int $sourceId The ID of the source the rule belongs to
     *
     * @return array<string, string|array<string, string>> target => label | optgroup => (target => label)
     */
    public function getRuleFilterTargets(int $sourceId): array;

    /**
     * Get an editor for the given filter
     *
     * The returned form MUST NOT have a request associated with it and MUST NOT navigate away upon submission.
     * The action of the form is overridden in any case.
     *
     * @param string $filter A filter template or a filter previously serialized by {@see serializeRuleFilter()}
     *
     * @return Form
     */
    public function getRuleFilterEditor(string $filter): Form;

    /**
     * Serialize the filter of the given editor
     *
     * The returned string is stored as-is in the database. The source MUST be able to deserialize it.
     * Upon editing by a user, {@see getRuleFilterEditor()} will be called with the serialized filter.
     *
     * @param Form $editor
     *
     * @return string
     */
    public function serializeRuleFilter(Form $editor): string;
}

This is done as usual in run.php as follows:

$this->provideHook('Notifications/v1/Source');

There can only be a single integration be responsible for a given source. When loading hooks of the aforementioned type, we have to make sure SourceHook::getSourceType() matches with the event rule's associated source.

Since #159, the EventRuleController and EventRuleConfigForm are already somewhat prepared for this.

EventRuleConfigForm::createObjectFilterControls() needs to be adjusted so that no text element is shown if there is a filter defined. Instead, only the button with the ⚙️ icon is shown, similar to the button if no filter is defined.

SourceHook::getRuleFilterTargets() and SourceHook::getRuleFilterEditor() are supposed to be used by EventRuleController::searchEditorAction() as part of a two step mini wizard: The user has to choose a target first, if there are multiple, then the editor appears instead. If a filter is being edited, the first step is of course not required. To change the target selection, it is required to clear the filter and re-open the editor.

Upon submission of the editor, SourceHook::serializeRuleFilter() is used to write the new changes to the session.