Add write support for models

library/Notifications/Common/Model.php

@@ -0,0 +1,234 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 Icinga GmbH <https://icinga.com>
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+namespace Icinga\Module\Notifications\Common;
+
+use ipl\Sql\Connection;
+use ipl\Sql\ExpressionInterface;
+
+/**
+ * Base class for all module models that tracks the changes made to a model
+ *
+ * Records which properties have changed since the model was loaded, and whether the model has been
+ * persisted yet, so the {@see EntityManager} can store a model and write only what actually changed.
+ *
+ * {@see self::setNew()} must be called explicitly when creating a new instance, it tells the {@see EntityManager}
+ * whether to insert or update
+ */
+abstract class Model extends \ipl\Orm\Model
+{
+    /** @var ?bool Whether this model is newly created and does not yet exist in the database */
+    private ?bool $isNew = null;
+
+    /** @var bool Whether the model is marked for deletion on the next {@see EntityManager::save()} */
+    private bool $markedForDeletion = false;
+
+    /** @var array<string, true> Names of properties modified since the model was loaded */
+    private array $modifiedProperties = [];
+
+    /**
+     * Whether a getter for a Closure-backed property is currently resolving.
+     *
+     * {@see \ipl\Orm\Common\PropertiesWithDefaults::getProperty()} memoizes a resolved Closure by
+     * calling {@see setProperty()}. Without this guard, that internal write would be misread as a
+     * user-driven change and (worse) re-enter {@see setProperty()} recursively.
+     *
+     * @var bool
+     */
+    private bool $resolvingProperty = false;
+
+    /**
+     * Get whether this entity is newly created and does not yet exist in the database
+     *
+     * @return ?bool
+     */
+    public function isNew(): ?bool
+    {
+        return $this->isNew;
+    }
+
+    /**
+     * Set whether this entity is newly created and does not yet exist in the database
+     *
+     * @param bool $new
+     *
+     * @return $this
+     */
+    public function setNew(bool $new = true): static
+    {
+        $this->isNew = $new;
+
+        return $this;
+    }
+
+    /**
+     * Get whether the entity, or the given property, has unsaved modifications
+     *
+     * Always returns false for new entities, which carry no change tracking.
+     *
+     * @param ?string $property The property to check, or null to check the whole entity
+     *
+     * @return bool
+     */
+    public function isModified(?string $property = null): bool
+    {
+        if ($property === null) {
+            return ! empty($this->modifiedProperties);
+        }
+
+        return isset($this->modifiedProperties[$property]);
+    }
+
+    /**
+     * Get the names of all properties modified since the entity was loaded as a set keyed by name
+     *
+     * The keys may be columns or relations.
+     *
+     * @return array<string, true>
+     */
+    public function getModifiedProperties(): array
+    {
+        return $this->modifiedProperties;
+    }
+
+    /**
+     * Reset change tracking and accept the current values as the new baseline
+     *
+     * @return $this
+     */
+    public function clearModifiedProperties(): static
+    {
+        $this->modifiedProperties = [];
+        $this->markedForDeletion = false;
+
+        return $this;
+    }
+
+    /**
+     * Get whether the model's table uses soft deletes
+     *
+     * @return bool
+     */
+    public function isSoftDeletable(): bool
+    {
+        return in_array('deleted', $this->getColumns(), true);
+    }
+
+    /**
+     * Mark the model for deletion on the next {@see EntityManager::save()} and return it
+     *
+     * If the model uses soft deletes this function must set the `deleted` property
+     *
+     * @return $this
+     */
+    public function delete(): static
+    {
+        $this->markedForDeletion = true;
+        if ($this->isSoftDeletable()) {
+            $this->deleted = true;
+        }
+
+        return $this;
+    }
+
+    /**
+     * Get whether the model is marked for deletion on the next {@see EntityManager::save()}
+     *
+     * @return bool
+     */
+    public function isMarkedForDeletion(): bool
+    {
+        return $this->markedForDeletion;
+    }
+
+    /**
+     * Get the model's real columns as a property => column map
+     *
+     * "Real" means that the column maps to an actual table column, and can be written to by the {@see EntityManager}
+     *
+     * @return array<string, string>
+     */
+    public function getRealColumnMap(): array
+    {
+        $columns = [];
+        foreach ((array) $this->getKeyName() as $key) {
+            $columns[$key] = $key;
+        }
+
+        foreach ($this->getColumns() as $alias => $column) {
+            if ($column instanceof ExpressionInterface) {
+                continue;
+            }
+
+            if (is_int($alias)) {
+                $columns[$column] = $column;
+            } else {
+                $columns[$alias] = $column;
+            }
+        }
+
+        return $columns;
+    }
+
+    /**
+     * Get the column used to store the timestamp of the most recent modification to the row
+     *
+     * `changed_at` is the schema-wide convention, the {@see EntityManager} checks whether the column
+     * exists on the model before stamping it.
+     *
+     * @return string
+     */
+    public function getChangedAtColumn(): string
+    {
+        return 'changed_at';
+    }
+
+    /**
+     * @param string $key The name of the property, which may be a column or a relation
+     */
+    protected function getProperty(string $key): mixed
+    {
+        $wasResolving = $this->resolvingProperty;
+        $this->resolvingProperty = true;
+        try {
+            return parent::getProperty($key);
+        } finally {
+            $this->resolvingProperty = $wasResolving;
+        }
+    }
+
+    /**
+     * @param string $key The name of the property, which may be a column or a relation
+     */
+    protected function setProperty(string $key, mixed $value): static
+    {
+        if (! $this->resolvingProperty && $this->isNew === false && ! isset($this->modifiedProperties[$key])) {
+            // Resolve the prior value via the trait's iterator, which skips Closure-valued properties.
+            // This avoids triggering lazy relation loaders just to capture change-tracking state.
+            $hadValue = false;
+            $original = null;
+            foreach ($this as $k => $v) {
+                if ($k === $key) {
+                    $hadValue = true;
+                    $original = $v;
+                    break;
+                }
+            }
+
+            if (! $hadValue || $original !== $value) {
+                $this->modifiedProperties[$key] = true;
+            }
+        }
+
+        return parent::setProperty($key, $value);
+    }
+
+    public static function on(Connection $db): StatefulQuery
+    {
+        return (new StatefulQuery())
+            ->setDb($db)
+            ->setModel(new static());
+    }
+}

library/Notifications/Common/StatefulQuery.php

@@ -0,0 +1,81 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 Icinga GmbH <https://icinga.com>
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+namespace Icinga\Module\Notifications\Common;
+
+use Generator;
+use ipl\Orm\Query;
+
+/**
+ * Mark models loaded from the db as not new, and can flag every result for deletion
+ */
+class StatefulQuery extends Query
+{
+    /** @var bool Whether all yielded models should be marked for deletion */
+    protected bool $deleteAll = false;
+
+    /**
+     * Mark each yielded model as loaded, and for deletion when {@see self::deleteAll()} was set
+     *
+     * @inheritDoc
+     *
+     * @return Generator
+     */
+    public function yieldResults(): Generator
+    {
+        foreach (parent::yieldResults() as $key => $model) {
+            if ($model instanceof Model) {
+                $this->markLoaded($model);
+                if ($this->deleteAll) {
+                    $model->delete();
+                }
+            }
+
+            yield $key => $model;
+        }
+    }
+
+    /**
+     * Mark each model as deleted when yielded by {@see self::yieldResults()}
+     *
+     * This only affects the root models themselves, not their eager-loaded relations
+     *
+     * @return $this
+     */
+    public function deleteAll(): static
+    {
+        $this->deleteAll = true;
+
+        return $this;
+    }
+
+    /**
+     * Recursively mark the given model and its eagerly-loaded related models as loaded
+     *
+     * @param Model $model
+     *
+     * @return void
+     */
+    private function markLoaded(Model $model): void
+    {
+        if ($model->isNew() !== null) {
+            return;
+        }
+
+        $model->setNew(false);
+
+        foreach ($model as $value) {
+            if ($value instanceof Model) {
+                $this->markLoaded($value);
+            } elseif (is_array($value)) {
+                foreach ($value as $item) {
+                    if ($item instanceof Model) {
+                        $this->markLoaded($item);
+                    }
+                }
+            }
+        }
+    }
+}

library/Notifications/Model/AvailableChannelType.php

@@ -5,7 +5,7 @@
 
 namespace Icinga\Module\Notifications\Model;
 
-use ipl\Orm\Model;
+use Icinga\Module\Notifications\Common\Model;
 use ipl\Orm\Query;
 use ipl\Orm\Relations;
 

library/Notifications/Model/BrowserSession.php

@@ -6,9 +6,9 @@
 namespace Icinga\Module\Notifications\Model;
 
 use DateTime;
+use Icinga\Module\Notifications\Common\Model;
 use ipl\Orm\Behavior\MillisecondTimestamp;
 use ipl\Orm\Behaviors;
-use ipl\Orm\Model;
 
 /**
  * @property string $php_session_id

library/Notifications/Model/Channel.php

@@ -6,10 +6,10 @@
 namespace Icinga\Module\Notifications\Model;
 
 use DateTime;
+use Icinga\Module\Notifications\Common\Model;
 use ipl\Orm\Behavior\BoolCast;
 use ipl\Orm\Behavior\MillisecondTimestamp;
 use ipl\Orm\Behaviors;
-use ipl\Orm\Model;
 use ipl\Orm\Query;
 use ipl\Orm\Relations;
 use ipl\Web\Widget\Icon;

library/Notifications/Model/Contact.php

@@ -6,10 +6,10 @@
 namespace Icinga\Module\Notifications\Model;
 
 use DateTime;
+use Icinga\Module\Notifications\Common\Model;
 use ipl\Orm\Behavior\BoolCast;
 use ipl\Orm\Behavior\MillisecondTimestamp;
 use ipl\Orm\Behaviors;
-use ipl\Orm\Model;
 use ipl\Orm\Query;
 use ipl\Orm\Relations;
 
@@ -87,7 +87,7 @@ public function createRelations(Relations $relations): void
             ->setCandidateKey('default_channel_id');
 
         $relations->belongsToMany('incident', Incident::class)
-            ->through('incident_contact')
+            ->through(IncidentContact::class)
             ->setJoinType('LEFT');
 
         $relations->hasMany('incident_contact', IncidentContact::class);
@@ -101,7 +101,7 @@ public function createRelations(Relations $relations): void
         $relations->hasMany('contactgroup_member', ContactgroupMember::class);
 
         $relations->belongsToMany('contactgroup', Contactgroup::class)
-            ->through('contactgroup_member')
+            ->through(ContactgroupMember::class)
             ->setJoinType('LEFT');
     }
 }

library/Notifications/Model/ContactAddress.php

@@ -6,10 +6,10 @@
 namespace Icinga\Module\Notifications\Model;
 
 use DateTime;
+use Icinga\Module\Notifications\Common\Model;
 use ipl\Orm\Behavior\BoolCast;
 use ipl\Orm\Behavior\MillisecondTimestamp;
 use ipl\Orm\Behaviors;
-use ipl\Orm\Model;
 use ipl\Orm\Query;
 use ipl\Orm\Relations;