KMP PHP API Reference

BestowalFinalizationService
in package
uses LocatorAwareTrait

BestowalFinalizationService - shared "Mark Given" finalization for bestowals.

Terminal completion finalizes inside the ActionItem transaction and audit-closes unfinished siblings, including required tasks. Without a terminal snapshot, all gating items must be completed. Linked recommendations synchronize in the same transaction; completed checklist history remains unchanged.

Table of Contents

Constants

FINALIZATION_SKIP_NOTE  : mixed = 'Bestowal marked given; remaining to-do is not...

Properties

$actionItemService  : ActionItemService
$bestowals  : Table
$syncService  : BestowalRecommendationSyncService

Methods

__construct()  : mixed
finalizeFromGatingCompletion()  : ServiceResult
Auto-finalize a bestowal because its gating to-do(s) just completed.
finalizeTerminalCompletion()  : ServiceResult
Called inside the owner-locked ActionItem transaction.
markGiven()  : ServiceResult
Explicitly finalize a bestowal (the user-driven "Mark Given" action).
terminalItem()  : ActionItem|null
Find the terminal snapshot, not the live template definition.
applyGiven()  : ServiceResult
Apply the lifecycle flip + recommendation sync for an open bestowal.
loadBestowal()  : Bestowal|null
Load a bestowal by id, returning null when it does not exist.
assignedTemplateHasNoGatingItems()  : bool
Whether the assigned, existing template intentionally defines no gates.
closeRemainingTodos()  : void
Audit-close unfinished work that no longer applies after finalization.
finalizeWithLockedRecheck()  : ServiceResult
Serialize finalization with workflow synchronization and recheck readiness.

Constants

FINALIZATION_SKIP_NOTE

private mixed FINALIZATION_SKIP_NOTE = 'Bestowal marked given; remaining to-do is not applicable.'

Properties

Methods

finalizeFromGatingCompletion()

Auto-finalize a bestowal because its gating to-do(s) just completed.

public finalizeFromGatingCompletion(int $bestowalId, int $actorId) : ServiceResult

Lenient: benign states (gating still incomplete, bestowal missing, or already given/cancelled) return success no-ops so the best-effort listener stays quiet. Only a genuine save failure returns a failure result.

Parameters
$bestowalId : int

Bestowal id.

$actorId : int

Member who completed the gating to-do.

Return values
ServiceResult

markGiven()

Explicitly finalize a bestowal (the user-driven "Mark Given" action).

public markGiven(int $bestowalId, int $actorId[, DateTimeInterface|null $bestowedAt = null ]) : ServiceResult

Strict: surfaces a user-facing failure reason when the bestowal is not ready, missing, or cancelled.

Parameters
$bestowalId : int

Bestowal id.

$actorId : int

Member performing the action.

$bestowedAt : DateTimeInterface|null = null

Optional bestowed timestamp (defaults to now).

Return values
ServiceResult —

Success carries the saved bestowal.

applyGiven()

Apply the lifecycle flip + recommendation sync for an open bestowal.

protected applyGiven(Bestowal $bestowal, int $actorId, DateTimeInterface|null $bestowedAt) : ServiceResult
Parameters
$bestowal : Bestowal

Open bestowal to finalize.

$actorId : int

Member performing the action.

$bestowedAt : DateTimeInterface|null

Optional bestowed timestamp.

Return values
ServiceResult

loadBestowal()

Load a bestowal by id, returning null when it does not exist.

protected loadBestowal(int $bestowalId[, bool $forUpdate = false ]) : Bestowal|null
Parameters
$bestowalId : int

Bestowal id.

$forUpdate : bool = false

Whether to acquire a row lock.

Return values
Bestowal|null

assignedTemplateHasNoGatingItems()

Whether the assigned, existing template intentionally defines no gates.

private assignedTemplateHasNoGatingItems(Bestowal $bestowal) : bool

No assigned template (or a deleted/missing template) remains not ready so a bestowal cannot bypass a checklist that was never configured.

Parameters
$bestowal : Bestowal

Bestowal being finalized.

Return values
bool

closeRemainingTodos()

Audit-close unfinished work that no longer applies after finalization.

private closeRemainingTodos(int $bestowalId, int $actorId) : void

The owner is still open and locked when this runs, allowing the shared ActionItem transition service to preserve one log per skipped to-do. The surrounding transaction rolls every cancellation back if marking the bestowal Given or synchronizing its recommendations fails.

Parameters
$bestowalId : int

Bestowal being finalized.

$actorId : int

Member performing or causing finalization.

finalizeWithLockedRecheck()

Serialize finalization with workflow synchronization and recheck readiness.

private finalizeWithLockedRecheck(int $bestowalId, int $actorId, DateTimeInterface|null $bestowedAt, bool $strict[, bool $terminalAction = false ][, bool $explicitAction = false ][, int|null $terminalItemId = null ]) : ServiceResult
Parameters
$bestowalId : int

Bestowal id.

$actorId : int

Member performing or causing the action.

$bestowedAt : DateTimeInterface|null

Optional bestowed timestamp.

$strict : bool

Whether readiness failures should be surfaced.

$terminalAction : bool = false

Whether a terminal task may finalize the bestowal.

$explicitAction : bool = false

Whether to authorize and complete the current terminal task.

$terminalItemId : int|null = null

Expected terminal task for a lifecycle callback.

Return values
ServiceResult
On this page

Search results