BestowalCreationService
in package
uses
BestowalNotesSupportTrait, LocatorAwareTrait
Creates bestowals from approved recommendations and links grouped recommendations.
Table of Contents
Constants
- EVENT_NAME : mixed = 'Awards.BestowalCreated'
Properties
- $bestowalRecommendationsTable : Table
- $bestowalsTable : Table
- $recommendationsTable : Table
- $todoMaterializationService : BestowalTodoMaterializationService
Methods
- __construct() : mixed
- createFromRecommendation() : array<string, mixed>
- Create a bestowal from a recommendation (or its group head) when eligible.
- createFromRecommendationInCallerTransaction() : array<string, mixed>
- Create a bestowal while the caller owns the surrounding transaction.
- 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.
- buildEventPayload() : array<string, mixed>
- Build the reaction workflow payload for a newly created bestowal.
- chooseHead() : Recommendation
- Choose the grouping head using the same preference rules as recommendation grouping.
- collectGroupRecommendations() : array<int, Recommendation>
- Collect the head and all grouped children for a recommendation.
-
createBestowalForRecommendations()
: Bestowal, recommendationIds: int[], eventPayload: array
- createFromLoadedRecommendation() : array<string, mixed>
- failureResult() : array<string, mixed>
- loadRecommendationForCreation() : Recommendation
- materializeTodos() : void
- Materialize the bestowal's to-do checklist from its award's template.
- resolveActiveBestowalSkipReason() : string|null
- Determine whether an active bestowal already exists for the recommendation group.
- skippedResult() : array<string, mixed>
- withTransaction() : mixed
- Run a callback inside a transaction unless one is already active.
Constants
EVENT_NAME
public
mixed
EVENT_NAME
= 'Awards.BestowalCreated'
Properties
$bestowalRecommendationsTable
private
Table
$bestowalRecommendationsTable
$bestowalsTable
private
Table
$bestowalsTable
$recommendationsTable
private
Table
$recommendationsTable
$todoMaterializationService
private
BestowalTodoMaterializationService
$todoMaterializationService
Methods
__construct()
public
__construct([Table|null $bestowalsTable = null ][, Table|null $recommendationsTable = null ][, Table|null $bestowalRecommendationsTable = null ][, BestowalTodoMaterializationService|null $todoMaterializationService = null ]) : mixed
Parameters
- $bestowalsTable : Table|null = null
-
Optional injected bestowals table.
- $recommendationsTable : Table|null = null
-
Optional injected recommendations table.
- $bestowalRecommendationsTable : Table|null = null
-
Optional injected join table.
- $todoMaterializationService : BestowalTodoMaterializationService|null = null
-
Optional to-do service.
createFromRecommendation()
Create a bestowal from a recommendation (or its group head) when eligible.
public
createFromRecommendation(int $recommendationId, int $actorId[, int|null $gatheringId = null ]) : array<string, mixed>
Parameters
- $recommendationId : int
-
Recommendation ID that triggered creation.
- $actorId : int
-
Current user ID.
- $gatheringId : int|null = null
-
Optional gathering override selected during approval.
Return values
array<string, mixed>createFromRecommendationInCallerTransaction()
Create a bestowal while the caller owns the surrounding transaction.
public
createFromRecommendationInCallerTransaction(int $recommendationId, int $actorId[, int|null $gatheringId = null ]) : array<string, mixed>
Parameters
- $recommendationId : int
-
Recommendation ID that triggered creation.
- $actorId : int
-
Current user ID.
- $gatheringId : int|null = null
-
Optional gathering override selected during approval.
Return values
array<string, mixed>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|nullbuildNobleNotes()
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|nullbuildReasonSummary()
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|nullbuildSpecialtySummary()
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|nullformatAwardLabel()
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
stringformatBestowalAwardLabel()
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
stringbuildEventPayload()
Build the reaction workflow payload for a newly created bestowal.
private
buildEventPayload(Bestowal $bestowal, array<int, int> $recommendationIds, Recommendation $head) : array<string, mixed>
Parameters
- $bestowal : Bestowal
-
Saved bestowal entity.
- $recommendationIds : array<int, int>
-
Linked recommendation IDs.
- $head : Recommendation
-
Primary recommendation.
Return values
array<string, mixed>chooseHead()
Choose the grouping head using the same preference rules as recommendation grouping.
private
chooseHead(array<int, Recommendation> $recommendations) : Recommendation
Parameters
- $recommendations : array<int, Recommendation>
-
Group recommendations.
Return values
RecommendationcollectGroupRecommendations()
Collect the head and all grouped children for a recommendation.
private
collectGroupRecommendations(Recommendation $recommendation) : array<int, Recommendation>
Parameters
- $recommendation : Recommendation
-
Group head or standalone recommendation.
Return values
array<int, Recommendation>createBestowalForRecommendations()
private
createBestowalForRecommendations(array<int, Recommendation> $recommendations, int $actorId[, int|null $gatheringId = null ]) : Bestowal, recommendationIds: int[], eventPayload: array}
Parameters
- $recommendations : array<int, Recommendation>
-
Recommendations for one member/award.
- $actorId : int
-
Current user ID.
- $gatheringId : int|null = null
-
Optional gathering override selected during approval.
Return values
Bestowal, recommendationIds: int[], eventPayload: arraycreateFromLoadedRecommendation()
private
createFromLoadedRecommendation(Recommendation $recommendation, int $actorId[, int|null $gatheringId = null ]) : array<string, mixed>
Parameters
- $recommendation : Recommendation
-
Head or standalone recommendation.
- $actorId : int
-
Current user ID.
- $gatheringId : int|null = null
-
Optional gathering override selected during approval.
Return values
array<string, mixed>failureResult()
private
failureResult(string $error) : array<string, mixed>
Parameters
- $error : string
Return values
array<string, mixed>loadRecommendationForCreation()
private
loadRecommendationForCreation(int $recommendationId) : Recommendation
Parameters
- $recommendationId : int
-
Recommendation ID.
Return values
RecommendationmaterializeTodos()
Materialize the bestowal's to-do checklist from its award's template.
private
materializeTodos(Bestowal $bestowal) : void
Failures are logged but never abort bestowal creation: the checklist is supplemental and can be re-materialized idempotently later.
Parameters
- $bestowal : Bestowal
-
Saved bestowal entity.
resolveActiveBestowalSkipReason()
Determine whether an active bestowal already exists for the recommendation group.
private
resolveActiveBestowalSkipReason(array<int, Recommendation> $recommendations) : string|null
Parameters
- $recommendations : array<int, Recommendation>
-
Group recommendations.
Return values
string|null —Skip reason when an active bestowal exists.
skippedResult()
private
skippedResult(string $reason) : array<string, mixed>
Parameters
- $reason : string
Return values
array<string, mixed>withTransaction()
Run a callback inside a transaction unless one is already active.
private
withTransaction(callable(): mixed $callback) : mixed
Parameters
- $callback : callable(): mixed
-
Work to execute.