Skip to content

A free open source IT asset/license management system

Added HasCalendarEvents trait

snipe0d239a2da6ee
diff --git a/app/Models/Traits/HasCalendarEvents.php b/app/Models/Traits/HasCalendarEvents.php
new file mode 100644
index 0000000000..59c4c1aee1
--- /dev/null
+++ b/app/Models/Traits/HasCalendarEvents.php
@@ -0,0 +1,266 @@
+<?php
+
+namespace App\Models\Traits;
+
+use App\Models\CalendarEvent;
+use Illuminate\Database\Eloquent\SoftDeletes;
+
+/**
+ * Opts a model into publishing rows into the calendar_events index
+ * table so its date/datetime columns show up on the unified calendar
+ * view (and any per-entity calendar page that queries the index).
+ *
+ * A source model implements calendarEventDefinitions() to declare
+ * which of its columns become events. The trait's observer keeps the
+ * index in sync on save / delete / restore. Nothing beyond dates gets
+ * stored on the index row - name, url, color, and any extras are
+ * resolved live from the source model at read time so this table
+ * never drifts from source values that aren't date-shaped.
+ *
+ * Consumer models MUST implement:
+ *
+ * public function calendarEventDefinitions(): array
+ * {
+ * return [
+ * [
+ * 'field' => 'start_date', // required, source column OR accessor name
+ * 'event_type' => 'maintenance.start', // required, filter key
+ * 'end_field' => 'expected_completion_date', // optional, range event's end
+ * 'trigger_fields' => ['status', 'foo_id'], // optional, extra columns that must trigger a re-sync
+ * // (needed when `field` is an accessor derived from
+ * // other columns, since getChanges doesn't see the
+ * // accessor itself)
+ * 'all_day' => true, // optional, explicit all-day flag (overrides the
+ * // controller's cast-based auto-detection - useful when
+ * // `field` is an accessor that returns a bare Carbon
+ * // without a companion cast declaration)
+ * ],
+ * // additional entries per source column that becomes an event
+ * ];
+ * }
+ */
+trait HasCalendarEvents
+{
+ /**
+ * Register the observer bindings on model boot. Runs once per
+ * source model class per request. The class-static approach
+ * lets the observer methods hit $this via the model callback
+ * signature.
+ *
+ * Uses `created` + `updated` separately (not the combined `saved`)
+ * so we can tell an actual INSERT from a later re-save on the
+ * same in-memory instance. wasRecentlyCreated persists on a
+ * model instance across delete/restore cycles, so branching on
+ * it inside a `saved` hook made restores look like inserts and
+ * hit the unique-constraint on updateOrCreate. Hooking the two
+ * distinct events keeps the intent clear at the callsite too.
+ */
+ public static function bootHasCalendarEvents(): void
+ {
+ static::created(function ($model) {
+ $model->forceSyncCalendarEvents();
+ });
+
+ static::updated(function ($model) {
+ $model->syncCalendarEvents();
+ });
+
+ static::deleted(function ($model) {
+ // Soft-deletes cascade to the calendar_events rows too
+ // (CalendarEvent uses SoftDeletes), so the filter WHERE
+ // on the read path skips them automatically. Hard deletes
+ // on the source cascade to a hard delete on the index
+ // rows since the parent record is gone entirely.
+ $usesSoft = in_array(SoftDeletes::class, class_uses_recursive($model), true);
+ if ($usesSoft && $model->isForceDeleting()) {
+ CalendarEvent::withTrashed()
+ ->where('source_type', $model::class)
+ ->where('source_id', $model->getKey())
+ ->forceDelete();
+
+ return;
+ }
+
+ CalendarEvent::where('source_type', $model::class)
+ ->where('source_id', $model->getKey())
+ ->delete();
+ });
+
+ static::registerRestoredIfSoftDeletes();
+ }
+
+ /**
+ * Wire up the restored() hook only when the source model itself
+ * uses SoftDeletes. Calling static::restored() on a model without
+ * the trait would throw at boot time.
+ */
+ protected static function registerRestoredIfSoftDeletes(): void
+ {
+ if (in_array(SoftDeletes::class, class_uses_recursive(static::class), true)) {
+ static::restored(function ($model) {
+ // Undelete any calendar_events rows this source
+ // published before its own soft-delete. Query-builder
+ // restore (not Model::restore) so no cascade of
+ // additional model events fires here - the source's
+ // own save() during restore() already ran through the
+ // saved observer for anything date-related that
+ // changed. Corner case where dates changed between
+ // delete and restore is handled by the reconcile
+ // command.
+ CalendarEvent::withTrashed()
+ ->where('source_type', $model::class)
+ ->where('source_id', $model->getKey())
+ ->restore();
+ });
+ }
+ }
+
+ /**
+ * Upsert the calendar_events row for every declared field with a
+ * populated date, and delete rows whose declared field is now
+ * null. Idempotent - safe to call from the observer on every
+ * save, from the reconcile command, or from a manual backfill.
+ *
+ * Wired into the source model's `updated` observer, so the
+ * change-gate below covers the "renamed but no dates touched"
+ * case. INSERTs go through forceSyncCalendarEvents() from the
+ * `created` observer since getChanges is empty on freshly
+ * inserted rows.
+ */
+ public function syncCalendarEvents(bool $force = false): void
+ {
+ $definitions = $this->calendarEventDefinitions();
+ if (empty($definitions)) {
+ return;
+ }
+
+ if (! $force && ! $this->calendarEventFieldsChanged($definitions)) {
+ return;
+ }
+
+ foreach ($definitions as $definition) {
+ $this->syncCalendarEventDefinition($definition);
+ }
+ }
+
+ /**
+ * Bypass the changes-check so the reconcile command can heal any
+ * date drift caused by direct DB edits, migrations, or missed
+ * observer fires.
+ */
+ public function forceSyncCalendarEvents(): void
+ {
+ $this->syncCalendarEvents(force: true);
+ }
+
+ /**
+ * Whether any of the declared date fields (or their end_field
+ * partners) were touched in the current save. Uses getChanges()
+ * which is set after save() commits, matching where the observer
+ * fires from.
+ */
+ protected function calendarEventFieldsChanged(array $definitions): bool
+ {
+ $changes = $this->getChanges();
+ if (empty($changes)) {
+ return false;
+ }
+
+ foreach ($definitions as $definition) {
+ if (array_key_exists($definition['field'], $changes)) {
+ return true;
+ }
+ if (! empty($definition['end_field']) && array_key_exists($definition['end_field'], $changes)) {
+ return true;
+ }
+ foreach ($definition['trigger_fields'] ?? [] as $triggerField) {
+ if (array_key_exists($triggerField, $changes)) {
+ return true;
+ }
+ }
+ }
+
+ return false;
+ }
+
+ /**
+ * Upsert or delete the calendar_events row for one definition
+ * entry. Deletes when the source's date column is null (the
+ * event no longer exists) and upserts otherwise. Keyed on the
+ * composite unique (source_type, source_id, source_field) so
+ * repeated saves don't create duplicates.
+ *
+ * Lookup uses withTrashed so we find any soft-deleted row that
+ * matches the composite key. Without this, an updateOrCreate
+ * during a restore path finds nothing (soft-deleted row hidden
+ * by default scope), tries INSERT, and trips the unique
+ * constraint. Un-trashes the row inline if it was soft-deleted
+ * so a restored source's events are immediately visible.
+ */
+ protected function syncCalendarEventDefinition(array $definition): void
+ {
+ $field = $definition['field'];
+ $eventType = $definition['event_type'];
+ $endField = $definition['end_field'] ?? null;
+
+ $start = $this->{$field};
+
+ if ($start === null || $start === '') {
+ CalendarEvent::where('source_type', static::class)
+ ->where('source_id', $this->getKey())
+ ->where('source_field', $field)
+ ->delete();
+
+ return;
+ }
+
+ $end = $endField ? $this->{$endField} : null;
+
+ $existing = CalendarEvent::withTrashed()
+ ->where('source_type', static::class)
+ ->where('source_id', $this->getKey())
+ ->where('source_field', $field)
+ ->first();
+
+ if ($existing) {
+ $existing->fill([
+ 'event_type' => $eventType,
+ 'start' => $start,
+ 'end' => $end,
+ 'deleted_at' => null,
+ ])->save();
+
+ return;
+ }
+
+ CalendarEvent::create([
+ 'source_type' => static::class,
+ 'source_id' => $this->getKey(),
+ 'source_field' => $field,
+ 'event_type' => $eventType,
+ 'start' => $start,
+ 'end' => $end,
+ ]);
+ }
+
+ /**
+ * Every declared calendar-event row for this source model
+ * instance. Not eager-loaded anywhere by default; consumers that
+ * need the reverse lookup can ->with('calendarEvents') on their
+ * own query. Uses a polymorphic morphMany scoped to
+ * (source_type, source_id).
+ */
+ public function calendarEvents()
+ {
+ return $this->morphMany(CalendarEvent::class, 'source');
+ }
+
+ /**
+ * Contract for the source model to declare which columns become
+ * calendar_events rows. Return an array of associative arrays;
+ * see the class docblock for the recognized keys.
+ *
+ * @return array<int, array{field: string, event_type: string, end_field?: string, trigger_fields?: array<int, string>, all_day?: bool}>
+ */
+ abstract public function calendarEventDefinitions(): array;
+}