Skip to content

A free open source IT asset/license management system

18.6 KB
Raw Blame
<?php

namespace App\Models;

use App\Enums\CheckoutRequestState;
use App\Exceptions\InvalidCheckoutRequestTransition;
use App\Models\Builders\CheckoutRequestQueryBuilder;
use App\Models\Traits\HasCalendarEvents;
use App\Models\Traits\Searchable;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Database\Eloquent\SoftDeletes;
use Illuminate\Support\Collection;

/**
 * @property \App\Enums\CheckoutRequestState $state
 *
 * @mixin IdeHelperCheckoutRequest
 */
class CheckoutRequest extends Model
{
    use HasCalendarEvents;
    use HasFactory;
    use Searchable;
    use SoftDeletes;

    protected $fillable = [
        'user_id',
        'quantity',
        'fulfilled_quantity',
        'start_date',
        'end_date',
        'notes',
        'state',
    ];

    protected $table = 'checkout_requests';

    /**
     * Direct-column search targets for TextSearch (called by
     * Api\CheckoutRequest::index's ?search= handler).
     */
    protected $searchableAttributes = ['notes'];

    /**
     * Relation-scoped search targets. The requester side goes here;
     * the polymorphic requestable side is handled in
     * advancedTextSearch() below since Searchable doesn't understand
     * morphTo.
     */
    protected $searchableRelations = [
        'user' => ['first_name', 'last_name', 'username', 'email'],
    ];

    protected $casts = [
        'start_date' => 'date',
        'end_date' => 'date',
        'canceled_at' => 'datetime',
        'fulfilled_at' => 'datetime',
        'quantity' => 'integer',
        'fulfilled_quantity' => 'integer',
        'state' => CheckoutRequestState::class,
    ];

    protected $attributes = [
        'state' => 'pending',
        'fulfilled_quantity' => 0,
    ];

    /**
     * Remaining qty on this request. Requested minus fulfilled;
     * capped at 0 so an accidental over-fulfill upstream can't
     * return a negative here. Used by the partial-fulfillment
     * flow to figure out how much of an incoming fulfillment
     * should count against this row.
     */
    public function remainingQuantity(): int
    {
        return max(0, (int) $this->quantity - (int) $this->fulfilled_quantity);
    }

    /**
     * Only pending rows publish a calendar event. Accessors return
     * null once the request has been fulfilled or canceled so the
     * HasCalendarEvents trait's null-check deletes the row on the
     * transition (state is listed in trigger_fields so the observer
     * re-runs the sync when state changes).
     */
    protected function getCalendarStartAttribute(): mixed
    {
        return $this->state === CheckoutRequestState::Pending
            ? $this->start_date
            : null;
    }

    protected function getCalendarEndAttribute(): mixed
    {
        return $this->state === CheckoutRequestState::Pending
            ? $this->end_date
            : null;
    }

    /**
     * Calendar-event URL / color for the requestable this row points
     * at. Reused by CalendarEventsTransformer, which falls back to
     * these methods when a source model isn't wired through the
     * Presenter/Presentable chain (which CheckoutRequest isn't - it
     * extends the plain Eloquent Model, not SnipeModel).
     *
     * Reservations link to the checkout confirmation screen with a
     * `request_id` query hint, so an admin clicking a today-widget
     * row lands on the pre-filled fulfill flow for that specific
     * request. Every checkout controller under Assets / Accessories
     * / Components / Consumables / Licenses honors the hint. Types
     * without a dedicated checkout screen (AssetModel) fall back to
     * the presenter's calendarUrl, which points at the item's show
     * page.
     */
    public function calendarUrl(): ?string
    {
        $item = $this->itemRequested();
        if (! $item) {
            return null;
        }

        $checkoutRoute = match (true) {
            $item instanceof Asset => ['hardware.checkout.create', ['asset' => $item->id]],
            $item instanceof Accessory => ['accessories.checkout.show', ['accessory' => $item->id]],
            $item instanceof Component => ['components.checkout.show', ['componentID' => $item->id]],
            $item instanceof Consumable => ['consumables.checkout.show', ['consumablesID' => $item->id]],
            $item instanceof License => ['licenses.checkout', ['license' => $item->id]],
            // AssetModel reservations point at the multi-fulfill
            // screen where an admin picks specific assets of that
            // model to fulfill the request against.
            $item instanceof AssetModel => ['models.fulfill-requests.create', ['model' => $item->id]],
            default => null,
        };

        if ($checkoutRoute !== null) {
            [$name, $params] = $checkoutRoute;

            return route($name, array_merge($params, ['request_id' => $this->id]));
        }

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

        return null;
    }

    public function calendarColor(): ?string
    {
        $item = $this->itemRequested();
        if ($item && method_exists($item, 'present')) {
            $presenter = $item->present();
            if (method_exists($presenter, 'calendarColor')) {
                return $presenter->calendarColor();
            }
        }

        return null;
    }

    /**
     * Emit the reservation window as a single all-day range event.
     * Uses the calendar_start / calendar_end accessors above so
     * fulfilled + canceled rows drop off the calendar without
     * touching the underlying date columns (which the notification
     * templates and admin queue still read from).
     *
     * @return array<int, array<string, mixed>>
     */
    public function calendarEventDefinitions(): array
    {
        return [
            [
                'field' => 'calendar_start',
                'end_field' => 'calendar_end',
                'event_type' => 'request.reservation',
                'trigger_fields' => ['state', 'start_date', 'end_date'],
                'all_day' => true,
            ],
        ];
    }

    /**
     * True when at least one unit has been fulfilled but the row
     * hasn't been fully satisfied yet. Renders as an in-between
     * badge on the admin queue + requester tab so both parties
     * see "partial" as distinct from "untouched pending".
     */
    public function isPartiallyFulfilled(): bool
    {
        return $this->state === CheckoutRequestState::Pending
            && $this->fulfilled_quantity > 0
            && $this->fulfilled_quantity < $this->quantity;
    }

    /**
     * Keep canceled_at + state in lockstep for the "one field says
     * WHEN, the other says WHAT" pattern the migration comment
     * calls out. Anyone assigning canceled_at directly (factories
     * with legacy `'canceled_at' => now()` shape, older callsites
     * that predate the state machine) gets state=canceled for free
     * so the pending-state scopes stay accurate.
     *
     * fulfilled_at is deliberately NOT mirrored here. FulfillCheckoutRequestAction
     * is the only fulfillment path (via the checkout-hook listener)
     * and sets both explicitly, so a synthetic mutator would just
     * hide bugs where someone reaches around the action.
     */
    protected static function booted(): void
    {
        static::saving(function (self $request): void {
            if ($request->canceled_at !== null
                && $request->state === CheckoutRequestState::Pending
            ) {
                $request->state = CheckoutRequestState::Canceled;
            }
        });
    }

    /**
     * Flip the row to canceled without firing the full model-event
     * cascade (archive-time cleanup paths on Accessory / Component /
     * Consumable rely on this so a parent-entity update does not
     * trigger a storm of per-request notification observers), but
     * still explicitly re-sync the calendar_events index so the
     * reservation drops off the calendar on cancel. The persistent-
     * calendar-event bug reported against the archive and user-
     * initiated cancel paths traced back to a saveQuietly() /
     * query-builder update() combination that bypassed the
     * HasCalendarEvents observer entirely.
     */
    public function cancelAndSync(): bool
    {
        $this->canceled_at = now();
        $this->state = CheckoutRequestState::Canceled;
        $saved = $this->saveQuietly();

        if ($saved) {
            $this->forceSyncCalendarEvents();
        }

        return $saved;
    }

    /**
     * @return BelongsTo<User, $this>
     */
    public function user(): BelongsTo
    {
        return $this->belongsTo(User::class, 'user_id', 'id');
    }

    public function requestingUser()
    {
        return $this->user()->withTrashed()->first();
    }

    public function requestedItem(): \Illuminate\Database\Eloquent\Relations\MorphTo
    {
        return $this->morphTo('requestable');
    }

    /**
     * Standard-name morphTo. Same shape as requestedItem() above;
     * exists so Eloquent morph helpers (whereHasMorph, morphEager
     * loads) that infer the relation name from the column pair
     * requestable_type/requestable_id find it under the expected
     * key. Older callers keep using requestedItem() unchanged.
     */
    public function requestable(): \Illuminate\Database\Eloquent\Relations\MorphTo
    {
        return $this->morphTo();
    }

    public function itemRequested() // Workaround for laravel polymorphic issue that's not being solved :(
    {
        return $this->requestedItem()->first();
    }

    public function itemType()
    {
        return snake_case(class_basename($this->requestable_type));
    }

    public function location()
    {
        return $this->itemRequested()->location;
    }

    public function name()
    {
        $item = $this->itemRequested();

        if (! $item) {
            return '';
        }

        return $item->display_name;
    }

    /**
     * Accessor mirror of name() so property-style access (`->name`) doesn't
     * fall through Eloquent's __get to `getRelationValue('name')`, which
     * treats the plain name() method as a candidate relation and throws
     * `LogicException: name must return a relationship instance` when it
     * gets a string back. `hasGetMutator('name')` fires first and returns
     * this accessor's value before relation resolution ever runs.
     *
     * The specific symptom is `CalendarEventsTransformer::titleFor()` which
     * coalesces `$source->display_name ?? $source->name ?? ...` for any
     * source without a Presentable presenter (CheckoutRequest doesn't have
     * one); pre-accessor, that crashed the calendar API for any install
     * with a reservation-shape CheckoutRequest on the calendar.
     */
    public function getNameAttribute(): ?string
    {
        return $this->name();
    }

    public function fulfilledBy(): BelongsTo
    {
        return $this->belongsTo(User::class, 'fulfilled_by', 'id');
    }

    public function checkoutActionlog(): BelongsTo
    {
        return $this->belongsTo(Actionlog::class, 'checkout_actionlog_id', 'id');
    }

    /**
     * Open = still awaiting resolution. Drives the admin queue
     * default filter, the /account/requested tab default, and the
     * Requestable::isRequestedBy() gate. Terminal-state rows (
     * fulfilled, canceled) are excluded.
     */
    public function newEloquentBuilder($query): CheckoutRequestQueryBuilder
    {
        return new CheckoutRequestQueryBuilder($query);
    }

    public function isReservation(): bool
    {
        return $this->start_date !== null || $this->end_date !== null;
    }

    /**
     * Extend TextSearch with the polymorphic requestable side. The
     * standard Searchable trait only understands direct columns and
     * named relations; it has no way to spell "search the .name of
     * whatever requestable this row points at." This override adds
     * an orWhereHasMorph across the six requestable types so a
     * search hits the requestable name, location, category, and
     * company in the same query as the notes / requester side.
     *
     * Per-morph-type branching is needed because:
     *   - Asset uses display_name AND asset_tag AND serial as its
     *     primary identifiers; the rest use `name`.
     *   - Asset's category is nested through model.category; every
     *     other type has a direct category relation.
     *   - AssetModel has no company relation (asset models are
     *     shared across companies), so its branch skips company.
     */
    public function advancedTextSearch(Builder $outer, Builder $nested, array $terms): void
    {
        if (empty($terms)) {
            return;
        }

        $morphTypes = [
            Asset::class,
            AssetModel::class,
            Accessory::class,
            Consumable::class,
            Component::class,
            License::class,
        ];

        $nested->orWhereHasMorph('requestable', $morphTypes, function (Builder $q, string $type) use ($terms): void {
            $q->where(function (Builder $inner) use ($type, $terms): void {
                foreach ($terms as $term) {
                    $like = '%'.$term.'%';

                    // Primary name column varies by type. Asset uses
                    // display_name (computed) so we search the
                    // underlying storage columns instead.
                    if ($type === Asset::class) {
                        $inner->orWhere('name', 'LIKE', $like)
                            ->orWhere('asset_tag', 'LIKE', $like)
                            ->orWhere('serial', 'LIKE', $like);
                    } else {
                        $inner->orWhere('name', 'LIKE', $like);
                    }

                    // Category path is nested through model on Asset,
                    // direct on every other type.
                    if ($type === Asset::class) {
                        $inner->orWhereHas('model.category', fn (Builder $r) => $r->where('name', 'LIKE', $like));
                    } else {
                        $inner->orWhereHas('category', fn (Builder $r) => $r->where('name', 'LIKE', $like));
                    }

                    // Location is only on the physical types (asset,
                    // accessory, consumable, component). License is
                    // intangible (no location); AssetModel is a
                    // template (no location either).
                    if (in_array($type, [Asset::class, Accessory::class, Consumable::class, Component::class], true)) {
                        $inner->orWhereHas('location', fn (Builder $r) => $r->where('name', 'LIKE', $like));
                    }

                    // Company is direct on every FMCS-scoped type
                    // (all except AssetModel, which is shared across
                    // companies).
                    if ($type !== AssetModel::class) {
                        $inner->orWhereHas('company', fn (Builder $r) => $r->where('name', 'LIKE', $like));
                    }
                }
            });
        });
    }

    /**
     * Transition guard. Throws when the caller tries to move a row
     * from a terminal state OR to a state that the current state
     * doesn't permit. Every state-machine Action calls this before
     * writing. Terminal states (fulfilled, canceled) are irreversible.
     */
    public function assertCanTransitionTo(CheckoutRequestState $target): void
    {
        // Same-state writes are a no-op transition and shouldn't
        // throw - callers rely on idempotent semantics for retry
        // safety (e.g. the fulfillment hook firing twice for a race
        // during a rapid double-submit).
        if ($this->state === $target) {
            return;
        }

        if ($this->state->isTerminal()) {
            throw new InvalidCheckoutRequestTransition($this, $this->state, $target);
        }

        // Currently only pending -> fulfilled and pending -> canceled
        // are legal. If more states land later (approved / denied /
        // expired), extend this matrix instead of dropping the guard.
        $legal = [
            CheckoutRequestState::Pending->value => [
                CheckoutRequestState::Fulfilled,
                CheckoutRequestState::Canceled,
            ],
        ];

        $permitted = $legal[$this->state->value] ?? [];
        if (! in_array($target, $permitted, true)) {
            throw new InvalidCheckoutRequestTransition($this, $this->state, $target);
        }
    }

    /**
     * Resolve the context needed to render the "you got here from a
     * /requests row" panel on the various checkout screens. Guards
     * against URL twiddling: the request row has to exist, be open
     * (pending state), target THIS specific requestable (both id and
     * polymorphic type), and belong to a still-existing user. Any
     * miss returns nulls / empty so callers can render nothing.
     *
     * @return array{checkoutRequest: ?self, requestingUserId: ?int, otherPendingRequests: Collection<int, self>}
     */
    public static function contextForCheckout(?int $requestId, string $requestableType, int $requestableId): array
    {
        $empty = [
            'checkoutRequest' => null,
            'requestingUserId' => null,
            'otherPendingRequests' => collect(),
        ];

        if (! $requestId) {
            return $empty;
        }

        $checkoutRequest = static::where('id', $requestId)
            ->where('requestable_id', $requestableId)
            ->where('requestable_type', $requestableType)
            ->pending()
            ->with('user')
            ->first();

        if (! $checkoutRequest || ! $checkoutRequest->user) {
            return $empty;
        }

        // Every other open request for the same requestable, oldest
        // first (waiting-list semantic). Drops the current row and
        // any rows whose requester has since been hard-deleted.
        $otherPendingRequests = static::where('requestable_id', $requestableId)
            ->where('requestable_type', $requestableType)
            ->where('id', '!=', $checkoutRequest->id)
            ->pending()
            ->with('user')
            ->orderBy('created_at')
            ->orderBy('id')
            ->get()
            ->filter(fn (self $r) => $r->user !== null)
            ->values();

        return [
            'checkoutRequest' => $checkoutRequest,
            'requestingUserId' => $checkoutRequest->user->id,
            'otherPendingRequests' => $otherPendingRequests,
        ];
    }
}