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.phpnew file mode 100644index 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;+}