Skip to content

A free open source IT asset/license management system

8.3 KB
Raw Blame
<?php

namespace App\Http\Transformers;

use App\Models\CalendarEvent;
use Carbon\Carbon;
use DateTimeInterface;
use Illuminate\Database\Eloquent\Model;

/**
 * Turns `calendar_events` rows + their resolved source models into the
 * FullCalendar-v6 Event Object payloads the calendar endpoint returns.
 *
 * Takes over both the shape (title with event-type label, all-day
 * detection from cast / definition, url + color from source presenter,
 * extendedProps) and the last-mile date formatting so the controller
 * doesn't have to know about any of it.
 *
 * The controller batch-loads sources per source_type (to avoid N+1)
 * and hands the pre-loaded map + filtered rows to
 * transformCalendarEvents(). Anything with no matching source or that
 * fails the per-row view policy is filtered out by the controller
 * before it reaches this transformer.
 */
class CalendarEventsTransformer
{
    /**
     * Human-readable labels for each `event_type` string emitted by
     * source models' `calendarEventDefinitions()`. Unknown types fall
     * through to the raw string so a new source at least reads
     * coherently before its label is wired up.
     *
     * @var array<string, string>
     */
    private const EVENT_TYPE_LABEL_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.start_date' => 'general.calendar_event_user_start_date',
        'user.end_date' => 'general.calendar_event_user_end_date',
        'request.reservation' => 'general.calendar_event_request_reservation',
    ];

    /**
     * @param  iterable<CalendarEvent>  $rows
     * @param  array<class-string, \Illuminate\Support\Collection>  $sourcesByType
     * @return array<int, array<string, mixed>>
     */
    public function transformCalendarEvents(iterable $rows, array $sourcesByType): array
    {
        $out = [];
        foreach ($rows as $row) {
            $source = $sourcesByType[$row->source_type][$row->source_id] ?? null;
            if (! $source) {
                continue;
            }
            $out[] = $this->transformCalendarEvent($row, $source);
        }

        return $out;
    }

    /**
     * @return array<string, mixed>
     */
    public function transformCalendarEvent(CalendarEvent $row, Model $source): array
    {
        $allDay = $this->isAllDayField($source, $row->source_field);

        return [
            'id' => $row->id,
            'title' => $this->titleFor($source, $row->event_type),
            'start' => $this->formatDate($row->start, $allDay),
            'end' => $this->formatDate($row->end, $allDay, isEnd: true),
            '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,
            ],
        ];
    }

    /**
     * Display name prefixed with the human-readable event-type label
     * so a viewer can tell why a row is on the calendar ("Audit due:
     * Laptop #7" vs. just "Laptop #7"). Presenter's name() is the
     * canonical Snipe-IT accessor, with a fallback to common attribute
     * names for models without a presenter wired up yet.
     *
     * Source models can expose a `calendarTitlePrefix()` method to
     * stamp a state marker at the front of the title (completed
     * maintenances use "✓ ", for example). Returning null or an
     * empty string leaves the title untouched.
     */
    private function titleFor(Model $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);
        $title = $label ? sprintf('%s: %s', $label, $name) : $name;

        $prefix = method_exists($source, 'calendarTitlePrefix') ? (string) $source->calendarTitlePrefix() : '';

        return $prefix.$title;
    }

    private function eventTypeLabel(string $eventType): string
    {
        if (! array_key_exists($eventType, self::EVENT_TYPE_LABEL_KEYS)) {
            return $eventType;
        }

        return trans(self::EVENT_TYPE_LABEL_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.
     */
    private function isAllDayField(Model $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'];
                }
            }
        }

        $cast = $source->getCasts()[$field] ?? null;

        return in_array($cast, ['date', 'immutable_date'], true);
    }

    /**
     * Normalize to Carbon so we get toIso8601String() (Carbon-only,
     * not on DateTimeInterface). All-day events serialize as
     * `YYYY-MM-DD` (no time component) so FullCalendar doesn't
     * reinterpret them as UTC midnight in the browser's local zone.
     *
     * FullCalendar treats all-day `end` as EXCLUSIVE: an event with
     * end=2026-10-15 renders only through 2026-10-14. Range events
     * (maintenance, request reservations) therefore need end+1 so a
     * same-day completion still paints on that day. Only applied
     * when $isEnd is true so starts stay anchored on the day they
     * actually begin.
     */
    private function formatDate(mixed $date, bool $allDay, bool $isEnd = false): ?string
    {
        if ($date === null || $date === '') {
            return null;
        }

        $date = $date instanceof Carbon
            ? $date
            : ($date instanceof DateTimeInterface ? Carbon::instance($date) : Carbon::parse($date));

        if ($allDay && $isEnd) {
            $date = $date->copy()->addDay();
        }

        return $allDay ? $date->format('Y-m-d') : $date->toIso8601String();
    }

    private function urlFor(Model $source): ?string
    {
        // Source model can expose calendarUrl() directly (used by
        // CheckoutRequest which doesn't ride the Presenter/Presentable
        // chain) or via its presenter (Asset/License/etc use the
        // presenter path).
        if (method_exists($source, 'calendarUrl')) {
            return $source->calendarUrl();
        }

        if (method_exists($source, 'present')) {
            $presenter = $source->present();
            if (method_exists($presenter, 'calendarUrl')) {
                return $presenter->calendarUrl();
            }
        }

        return null;
    }

    /**
     * Null means "no per-event color". The frontend paints from a
     * per-event_type CSS palette so uncolored installs still read
     * cleanly.
     */
    private function colorFor(Model $source): ?string
    {
        if (method_exists($source, 'calendarColor')) {
            return $source->calendarColor();
        }

        if (method_exists($source, 'present')) {
            $presenter = $source->present();
            if (method_exists($presenter, 'calendarColor')) {
                return $presenter->calendarColor();
            }
        }

        return null;
    }
}