KMP PHP API Reference

BestowalHandoffService
in package
uses BestowalNotesSupportTrait, LocatorAwareTrait

Workflow-aware bestowal handoff service.

Validates recommendation eligibility for bestowal creation:

  • Blocks creation when a recommendation is under active approval review.
  • Blocks direct handoff of grouped child recommendations.
  • Records the source approval run ID for provenance.

Routes all eligibility checks before delegating to BestowalCreationService.

Table of Contents

Properties

$approvalLifecycleService  : RecommendationApprovalWorkflowLifecycleService
$approvalRunsTable  : Table
$bestowalsTable  : Table
$creationService  : BestowalCreationService
$recommendationsTable  : Table

Methods

__construct()  : mixed
assertHandoffEligible()  : void
Assert that a recommendation is eligible for bestowal handoff.
createBestowal()  : array<string, mixed>
Create a bestowal from a single recommendation, validating approval eligibility.
createBestowals()  : array<string, mixed>
Create bestowals for multiple recommendations, validating each one's eligibility.
findLatestApprovedRunId()  : int|null
Find the most recently completed (approved) approval run ID for a recommendation.
hasActiveApprovalRun()  : bool
Check whether a recommendation has any active approval run (in_progress or changes_requested).
buildHeraldNotes()  : string|null
Build herald-oriented call text from linked recommendations.
buildNobleNotes()  : string|null
Summarize recommendation reasons for crown-facing notes.
buildReasonSummary()  : string|null
Build a persisted summary of linked recommendation reasons and submitters.
buildSpecialtySummary()  : string|null
Build the bestowal specialty from unique linked recommendation specialties.
formatAwardLabel()  : string
Format an award label with optional level for note text.
formatBestowalAwardLabel()  : string
Format the award selected on a bestowal for note and notification text.
failureResult()  : array<string, mixed>
recordSourceApprovalRun()  : void
refreshReasonSummary()  : void
Ensure approval-created handoffs persist linked recommendation planning details.

Properties

Methods

__construct()

public __construct([Table|null $recommendationsTable = null ][, Table|null $approvalRunsTable = null ][, Table|null $bestowalsTable = null ][, BestowalCreationService|null $creationService = null ][, RecommendationApprovalWorkflowLifecycleService|null $approvalLifecycleService = null ]) : mixed
Parameters
$recommendationsTable : Table|null = null

Optional injected recommendations table.

$approvalRunsTable : Table|null = null

Optional injected approval runs table.

$bestowalsTable : Table|null = null

Optional injected bestowals table.

$creationService : BestowalCreationService|null = null

Optional injected creation service.

$approvalLifecycleService : RecommendationApprovalWorkflowLifecycleService|null = null

Optional lifecycle service.

assertHandoffEligible()

Assert that a recommendation is eligible for bestowal handoff.

public assertHandoffEligible(int $recommendationId) : void
Parameters
$recommendationId : int

Recommendation ID.

Tags
throws
RuntimeException

when the recommendation is under active approval review.

createBestowal()

Create a bestowal from a single recommendation, validating approval eligibility.

public createBestowal(int $recommendationId, int $actorId[, int|null $gatheringId = null ]) : array<string, mixed>

Returns a standardized result array:

  • success (bool)
  • skipped (bool) when the recommendation is a group child or already linked
  • error (string) on failure
  • data (array) on success: bestowalId, recommendationIds, sourceApprovalRunId
Parameters
$recommendationId : int

Recommendation ID.

$actorId : int

Current user ID.

$gatheringId : int|null = null

Optional gathering override selected during approval.

Return values
array<string, mixed>

createBestowals()

Create bestowals for multiple recommendations, validating each one's eligibility.

public createBestowals(array<string|int, int> $recommendationIds, int $actorId[, int|null $gatheringId = null ]) : array<string, mixed>
Parameters
$recommendationIds : array<string|int, int>

Recommendation IDs.

$actorId : int

Current user ID.

$gatheringId : int|null = null

Optional gathering override selected during approval.

Return values
array<string, mixed>

findLatestApprovedRunId()

Find the most recently completed (approved) approval run ID for a recommendation.

public findLatestApprovedRunId(int $recommendationId) : int|null
Parameters
$recommendationId : int

Recommendation ID.

Return values
int|null

hasActiveApprovalRun()

Check whether a recommendation has any active approval run (in_progress or changes_requested).

public hasActiveApprovalRun(int $recommendationId) : bool
Parameters
$recommendationId : int

Recommendation ID.

Return values
bool

buildHeraldNotes()

Build herald-oriented call text from linked recommendations.

protected buildHeraldNotes(array<int, Recommendation> $recommendations, string $memberScaName) : string|null
Parameters
$recommendations : array<int, Recommendation>

Linked recommendations.

$memberScaName : string

Recipient SCA name.

Return values
string|null

buildNobleNotes()

Summarize recommendation reasons for crown-facing notes.

protected buildNobleNotes(array<int, Recommendation> $recommendations) : string|null
Parameters
$recommendations : array<int, Recommendation>

Linked recommendations.

Return values
string|null

buildReasonSummary()

Build a persisted summary of linked recommendation reasons and submitters.

protected buildReasonSummary(array<int, Recommendation> $recommendations) : string|null
Parameters
$recommendations : array<int, Recommendation>

Linked recommendations.

Return values
string|null

buildSpecialtySummary()

Build the bestowal specialty from unique linked recommendation specialties.

protected buildSpecialtySummary(array<int, Recommendation> $recommendations) : string|null
Parameters
$recommendations : array<int, Recommendation>

Linked recommendations.

Return values
string|null

formatAwardLabel()

Format an award label with optional level for note text.

protected formatAwardLabel(Recommendation $recommendation) : string
Parameters
$recommendation : Recommendation

Recommendation with optional award contain.

Return values
string

formatBestowalAwardLabel()

Format the award selected on a bestowal for note and notification text.

protected formatBestowalAwardLabel(Bestowal $bestowal) : string
Parameters
$bestowal : Bestowal

Bestowal with optional award contain.

Return values
string

failureResult()

private failureResult(string $message) : array<string, mixed>
Parameters
$message : string

Error message.

Return values
array<string, mixed>

recordSourceApprovalRun()

private recordSourceApprovalRun(int $bestowalId, int $sourceApprovalRunId, int $actorId) : void
Parameters
$bestowalId : int

Bestowal ID.

$sourceApprovalRunId : int

Source approval run ID.

$actorId : int

Actor ID.

refreshReasonSummary()

Ensure approval-created handoffs persist linked recommendation planning details.

private refreshReasonSummary(int $bestowalId, int $actorId) : void
Parameters
$bestowalId : int

Bestowal ID.

$actorId : int

Actor ID.

On this page

Search results