A free open source IT asset/license management system
Added calendar events API
snipe5811e333d62f
diff --git a/app/Http/Controllers/Api/CalendarEventsController.php b/app/Http/Controllers/Api/CalendarEventsController.phpnew file mode 100644index 0000000000..98dacb50e4--- /dev/null+++ b/app/Http/Controllers/Api/CalendarEventsController.php@@ -0,0 +1,314 @@+<?php++namespace App\Http\Controllers\Api;++use App\Http\Controllers\Controller;+use App\Http\Transformers\CalendarEventsTransformer;+use App\Models\Asset;+use App\Models\CalendarEvent;+use Carbon\Carbon;+use Illuminate\Http\JsonResponse;+use Illuminate\Http\Request;++/**+ * Unified read endpoint for the calendar page. Queries the+ * calendar_events index table (populated by the HasCalendarEvents+ * trait's observer) and hydrates each row from its live source+ * model, so titles / urls / colors reflect current source state+ * rather than a denormalized snapshot.+ *+ * Filtering:+ * - `start`, `end` (ISO-8601) - FullCalendar's visible range.+ * Defaults to a wide six-month window centered on today.+ * - `event_type[]` - array of allowed event_type values. Empty+ * means "all types". Frontend filter buttons flip these on and+ * off.+ * - `limit` - hard cap on returned events. Defaults to 500 for the+ * full calendar page and gets overridden downward for the+ * dashboard "Today" widget. Guards the browser from a 10k-row+ * JSON blob when a big install's calendar range straddles a+ * dense date. Response is `{ events, truncated, total }` so the+ * frontend can render a "narrow filters" banner when truncated.+ *+ * Access control:+ * - The base `view Asset` gate governs whether the endpoint+ * responds at all. Source-specific access is enforced per-row+ * via each source's own view policy - if the actor can't view+ * the underlying model (FMCS mismatch, location scoping, etc.),+ * the event is filtered out before it hits the response.+ */+class CalendarEventsController extends Controller+{+ public function index(Request $request): JsonResponse+ {+ // Base gate. Calendar as a whole is asset-adjacent, so tie+ // to view-Asset; source-specific gates below narrow per row.+ $this->authorize('view', Asset::class);++ $rangeStart = $request->filled('start')+ ? Carbon::parse($request->input('start'))+ : now()->subMonths(3)->startOfDay();+ $rangeEnd = $request->filled('end')+ ? Carbon::parse($request->input('end'))+ : now()->addMonths(3)->endOfDay();++ // event_type filter comes as either ?event_type[]=a&event_type[]=b+ // (repeatable) or ?event_type=a,b (single param, comma-split).+ // Empty or missing means "all types allowed".+ $eventTypes = $request->input('event_type');+ if (is_string($eventTypes)) {+ $eventTypes = array_filter(array_map('trim', explode(',', $eventTypes)));+ }+ $eventTypes = is_array($eventTypes) ? array_values(array_filter($eventTypes)) : [];++ // Hard cap on returned rows. Two calendar contexts hit this+ // endpoint: the full calendar page (default 500) and the+ // dashboard's Today widget (much smaller, sends ?limit=25). A+ // request that asks for more than the ceiling silently gets+ // capped so the browser can't be exhausted.+ $ceiling = 500;+ $limit = (int) $request->input('limit', $ceiling);+ $limit = max(1, min($limit, $ceiling));++ // FullCalendar's fetchInfo passes ranges as [start, end)+ // (end exclusive) so a listDay view of today = start=today+ // 00:00, end=tomorrow 00:00. whereBetween is inclusive on+ // BOTH sides though, which was pulling tomorrow's midnight+ // events into today's listDay widget and inflating the+ // truncation count. Use explicit >= start / < end to match+ // FC's half-open interval semantics.+ $baseQuery = CalendarEvent::query()+ ->where(function ($q) use ($rangeStart, $rangeEnd) {+ $q->where(function ($inner) use ($rangeStart, $rangeEnd) {+ $inner->where('start', '>=', $rangeStart)+ ->where('start', '<', $rangeEnd);+ })+ ->orWhere(function ($inner) use ($rangeStart, $rangeEnd) {+ $inner->where('end', '>=', $rangeStart)+ ->where('end', '<', $rangeEnd);+ })+ ->orWhere(function ($inner) use ($rangeStart, $rangeEnd) {+ $inner->where('start', '<', $rangeStart)+ ->where('end', '>=', $rangeEnd);+ });+ })+ ->when(! empty($eventTypes), fn ($q) => $q->whereIn('event_type', $eventTypes));++ $total = (clone $baseQuery)->count();++ $rows = $baseQuery+ ->orderBy('start')+ ->limit($limit)+ ->get();++ // Whether we hit the query limit. This is the honest signal for+ // "there might be more events after this batch". The alternative+ // (comparing $total to count($events) post-per-row-filter) reports+ // truncated=true any time an FMCS-filtered event brings the+ // returned count below $total, which was misleading users into+ // clicking "+N more on calendar" links for events they never had+ // permission to see in the first place.+ $hitLimit = $rows->count() >= $limit;++ // Batch-load source models per source_type in one query per+ // type. Groups rows by source_type, whereIn's the ids, and+ // key-lookups them from the resulting collection. Avoids the+ // N+1 that a naive $row->source access would produce.+ $rowsByType = $rows->groupBy('source_type');+ $sourcesByType = [];+ foreach ($rowsByType as $sourceType => $typeRows) {+ if (! class_exists($sourceType)) {+ continue;+ }+ $ids = $typeRows->pluck('source_id')->unique()->all();+ $sourcesByType[$sourceType] = $sourceType::query()+ ->when(+ in_array(\Illuminate\Database\Eloquent\SoftDeletes::class, class_uses_recursive($sourceType), true),+ fn ($q) => $q->withTrashed(),+ )+ ->whereIn('id', $ids)+ ->get()+ ->keyBy('id');+ }++ $events = [];+ foreach ($rows as $row) {+ $source = $sourcesByType[$row->source_type][$row->source_id] ?? null;+ if (! $source) {+ // Source disappeared between the index write and now+ // (mid-request delete without a completed observer+ // cascade). Skip the row so the client doesn't see a+ // ghost event; the reconcile command will clean up+ // the orphan on its next pass.+ continue;+ }++ // Per-row access check via each source's own policy.+ // Without this, a user with view-Asset but no access to+ // a particular license (FMCS mismatch) would still see+ // its expiration event on the calendar. Any source that+ // doesn't have a view policy is treated as visible; add+ // policies to lock down access.+ if (! $request->user()?->can('view', $source)) {+ continue;+ }++ $allDay = $this->isAllDayField($source, $row->source_field);++ $events[] = [+ 'id' => $row->id,+ 'title' => $this->titleFor($source, $row->event_type),+ 'start' => $this->formatDate($row->start, $allDay),+ 'end' => $this->formatDate($row->end, $allDay),+ 'allDay' => $allDay,+ 'url' => $this->urlFor($source),+ 'color' => $this->colorFor($source),+ 'extendedProps' => [+ 'source_type' => $row->source_type,+ 'source_id' => $row->source_id,+ 'source_field' => $row->source_field,+ 'event_type' => $row->event_type,+ ],+ ];+ }++ return response()->json([+ 'events' => (new CalendarEventsTransformer)->transformCalendarEvents($events),+ 'total' => $total,+ 'truncated' => $hitLimit,+ ]);+ }++ /**+ * Resolve a display name from the source model, prefixed with a+ * human-readable label for the event_type so a viewer can tell at+ * a glance why a row is on the calendar (e.g. "Audit due: Laptop+ * #7" vs. just "Laptop #7"). Presenter's name() is the canonical+ * Snipe-IT accessor; falls through to common attribute names for+ * models that don't have a presenter wired up yet.+ */+ protected function titleFor($source, string $eventType): string+ {+ if (method_exists($source, 'present')) {+ $presenter = $source->present();+ if (method_exists($presenter, 'name')) {+ $name = (string) $presenter->name();+ }+ }++ $name ??= (string) ($source->display_name ?? $source->name ?? (class_basename($source).'#'.$source->getKey()));++ $label = $this->eventTypeLabel($eventType);++ return $label ? sprintf('%s: %s', $label, $name) : $name;+ }++ /**+ * Human-readable label for an event_type. Keyed on the canonical+ * event_type strings emitted by each model's+ * calendarEventDefinitions(); unknown types fall through to the+ * event_type itself so a new source at least reads coherently+ * before its label is registered.+ */+ protected function eventTypeLabel(string $eventType): string+ {+ $keys = [+ 'maintenance.start' => 'general.calendar_event_maintenance',+ 'asset.audit_due' => 'general.calendar_event_asset_audit_due',+ 'asset.expected_checkin' => 'general.calendar_event_asset_expected_checkin',+ 'asset.checkout' => 'general.calendar_event_asset_checkout',+ 'asset.eol' => 'general.calendar_event_asset_eol',+ 'asset.warranty_expiration' => 'general.calendar_event_asset_warranty_expiration',+ 'license.expiration' => 'general.calendar_event_license_expiration',+ 'license.termination' => 'general.calendar_event_license_termination',+ 'user.end_date' => 'general.calendar_event_user_end_date',+ ];++ if (! array_key_exists($eventType, $keys)) {+ return $eventType;+ }++ return trans($keys[$eventType]);+ }++ /**+ * True when the underlying source field is cast as a bare date+ * (not a datetime). Rendering these on a timegrid as ISO-8601 with+ * a T00:00:00 component stacks the whole day's events at midnight;+ * FullCalendar's `allDay: true` mode turns them into a solid bar+ * across the day instead. Also flips the payload's start/end to+ * YYYY-MM-DD so FullCalendar doesn't reinterpret the missing time+ * as UTC midnight.+ */+ protected function isAllDayField($source, ?string $field): bool+ {+ if (! $field) {+ return false;+ }++ if (method_exists($source, 'calendarEventDefinitions')) {+ foreach ($source->calendarEventDefinitions() as $definition) {+ if (($definition['field'] ?? null) === $field && array_key_exists('all_day', $definition)) {+ return (bool) $definition['all_day'];+ }+ }+ }++ if (! method_exists($source, 'getCasts')) {+ return false;+ }++ $cast = $source->getCasts()[$field] ?? null;++ return in_array($cast, ['date', 'immutable_date'], true);+ }++ protected function formatDate(mixed $date, bool $allDay): ?string+ {+ if ($date === null || $date === '') {+ return null;+ }++ if (! $date instanceof \DateTimeInterface) {+ $date = Carbon::parse($date);+ }++ return $allDay ? $date->format('Y-m-d') : $date->toIso8601String();+ }++ /**+ * Resolve a link to the source model. Presenter's route() (or+ * similar) is preferred so each source owns its own routing+ * conventions; falls back to a source-type-keyed default when+ * absent.+ */+ protected function urlFor($source): ?string+ {+ if (method_exists($source, 'present')) {+ $presenter = $source->present();+ if (method_exists($presenter, 'calendarUrl')) {+ return $presenter->calendarUrl();+ }+ }++ return null;+ }++ /**+ * Resolve a color for the event via the source model's+ * presenter. Null means "no per-event color" - frontend paints+ * from a per-event_type CSS palette so uncolored installs still+ * read cleanly.+ */+ protected function colorFor($source): ?string+ {+ if (method_exists($source, 'present')) {+ $presenter = $source->present();+ if (method_exists($presenter, 'calendarColor')) {+ return $presenter->calendarColor();+ }+ }++ return null;+ }+}diff --git a/app/Http/Transformers/CalendarEventsTransformer.php b/app/Http/Transformers/CalendarEventsTransformer.phpnew file mode 100644index 0000000000..fb65e59a3a--- /dev/null+++ b/app/Http/Transformers/CalendarEventsTransformer.php@@ -0,0 +1,81 @@+<?php++namespace App\Http\Transformers;++use Carbon\CarbonInterface;+use DateTimeInterface;++/**+ * Normalizes a collection of pre-shaped event arrays into+ * FullCalendar-v6 Event Object format.+ *+ * Callers build one array per event with keys mirroring FullCalendar's+ * own shape (id, title, start, end, url, color, extendedProps); this+ * transformer handles the last-mile bits every calendar endpoint would+ * otherwise duplicate:+ *+ * - Carbon / DateTime values get ISO-8601 stringified (FullCalendar+ * parses ISO-8601 reliably; passing raw Carbon objects works via+ * PHP's json_encode but drifts across projects).+ * - Missing keys default to null / empty string / empty array so+ * client-side never has to guard on shape.+ * - Unknown keys pass through untouched under extendedProps so a+ * caller can hand any per-entity metadata to a custom+ * eventClick handler without needing this transformer to know+ * about it.+ *+ * Used by:+ * - Api\CalendarEventsController::index (unified calendar page)+ *+ * Any new calendar-adjacent endpoint should route through this same+ * transformer so every calendar payload looks identical from the+ * client's perspective.+ */+class CalendarEventsTransformer+{+ /**+ * @param iterable<array<string, mixed>> $events+ * @return array<int, array<string, mixed>>+ */+ public function transformCalendarEvents(iterable $events): array+ {+ $out = [];+ foreach ($events as $event) {+ $out[] = $this->transformCalendarEvent($event);+ }++ return $out;+ }++ /**+ * @param array<string, mixed> $event+ * @return array<string, mixed>+ */+ public function transformCalendarEvent(array $event): array+ {+ return [+ 'id' => $event['id'] ?? null,+ 'title' => $event['title'] ?? '',+ 'start' => $this->normalizeDate($event['start'] ?? null),+ 'end' => $this->normalizeDate($event['end'] ?? null),+ 'url' => $event['url'] ?? null,+ 'color' => $event['color'] ?? null,+ 'extendedProps' => $event['extendedProps'] ?? [],+ ];+ }++ private function normalizeDate(mixed $date): ?string+ {+ if ($date === null || $date === '') {+ return null;+ }+ if ($date instanceof CarbonInterface) {+ return $date->toIso8601String();+ }+ if ($date instanceof DateTimeInterface) {+ return $date->format(DateTimeInterface::ATOM);+ }++ return (string) $date;+ }+}diff --git a/routes/api.php b/routes/api.phpindex ac63f7b138..8d3ff3fb4f 100644--- a/routes/api.php+++ b/routes/api.php@@ -654,6 +654,24 @@ Route::group(['prefix' => 'v1', 'middleware' => ['api', 'api-throttle:api']], fu]); // end assets API routes+ /**+ * Unified calendar events API. Reads from the calendar_events+ * index (populated by every HasCalendarEvents source model)+ * and hydrates titles / urls / colors live from the source.+ */+ Route::get('/calendar/events',+ [Api\CalendarEventsController::class, 'index']+ )->name('api.calendar.events');++ /**+ * Low-stock unified endpoint for the dashboard widget. Delegates to+ * Helper::checkLowInventory so this and the top-nav alert bell+ * share a single source of truth.+ */+ Route::get('/low-stock',+ [Api\LowStockController::class, 'index']+ )->name('api.low-stock.index');+/*** Asset maintenances API routes*/