RecommendationTransitionService
in package
Applies recommendation state transitions for single and bulk operations.
Uses the Recommendation entity setters/callbacks so transitions consistently update status, state_date, field-set rules, gathering rules, notes, and explicit workflow-owned side effects.
Table of Contents
Constants
- BULK_NOTE_SUBJECT : mixed = 'Recommendation Bulk Updated'
- SINGLE_NOTE_SUBJECT : mixed = 'Recommendation Updated'
Properties
- $bestowalCreationService : BestowalCreationService
- $groupingService : RecommendationGroupingService
- $stateLogService : RecommendationStateLogService
- $statePolicyService : RecommendationBestowalStatePolicyService
Methods
- __construct() : mixed
- resetForBestowalCancellation() : array<string, mixed>
- Reset a bestowal-owned recommendation through the canonical transition path.
- transition() : array<string, mixed>
- Transition a single recommendation and return structured transition data.
- transitionMany() : array<string, mixed>
- Transition multiple recommendations and return structured transition data.
- applyTransition() : array<string, mixed>
- Apply the transition semantics to one recommendation.
- buildChangeSet() : array<string, array{before: mixed, after: mixed}>
- Build a structured before/after diff for transition-relevant fields.
- extractIds() : array<int, string>
- Extract and normalize recommendation IDs from supported input keys.
- extractTargetState() : string
- Extract target state from supported input keys.
- getOptionalValue() : mixed
- Return the first matching value for a set of supported keys.
- hasAnyKey() : bool
- Check whether any of the provided keys exist in the data payload.
- normalizeGiven() : DateTime|null
- Normalize the given date to midnight UTC for storage.
- normalizeOptionalString() : string|null
- Convert blank strings to null.
- resolveHandoffRecommendationIds() : array<int, string>
- Resolve selected handoff IDs to group heads so grouped children are not transitioned independently.
- resolveNoteSubject() : string
- Resolve the note subject from supported input keys.
- runTransitions() : array<string, mixed>
- Execute one or more transitions inside a transaction.
- serializeValue() : mixed
- Serialize values for structured transition output.
Constants
BULK_NOTE_SUBJECT
private
mixed
BULK_NOTE_SUBJECT
= 'Recommendation Bulk Updated'
SINGLE_NOTE_SUBJECT
private
mixed
SINGLE_NOTE_SUBJECT
= 'Recommendation Updated'
Properties
$bestowalCreationService
private
BestowalCreationService
$bestowalCreationService
$groupingService
private
RecommendationGroupingService
$groupingService
$stateLogService
private
RecommendationStateLogService
$stateLogService
$statePolicyService
private
RecommendationBestowalStatePolicyService
$statePolicyService
Methods
__construct()
public
__construct([RecommendationGroupingService|null $groupingService = null ][, RecommendationStateLogService|null $stateLogService = null ][, RecommendationBestowalStatePolicyService|null $statePolicyService = null ][, BestowalCreationService|null $bestowalCreationService = null ]) : mixed
Parameters
- $groupingService : RecommendationGroupingService|null = null
-
Optional grouping service.
- $stateLogService : RecommendationStateLogService|null = null
-
Optional state-log service.
- $statePolicyService : RecommendationBestowalStatePolicyService|null = null
-
Optional state policy.
- $bestowalCreationService : BestowalCreationService|null = null
-
Optional bestowal creation service.
resetForBestowalCancellation()
Reset a bestowal-owned recommendation through the canonical transition path.
public
resetForBestowalCancellation(Table $recommendationsTable, Recommendation $recommendation, string $targetState, int $actorId) : array<string, mixed>
The caller owns the surrounding bestowal transaction. Clearing the link first permits the normal save callbacks, state log, and grouping side effects to run without treating this system transition as a user edit.
Parameters
- $recommendationsTable : Table
-
Recommendations table instance.
- $recommendation : Recommendation
-
Linked recommendation.
- $targetState : string
-
Reconsideration state for the head or child.
- $actorId : int
-
Current user ID.
Return values
array<string, mixed>transition()
Transition a single recommendation and return structured transition data.
public
transition(Table $recommendationsTable, string|int $recommendationId, array<string, mixed> $data, int $actorId) : array<string, mixed>
Parameters
- $recommendationsTable : Table
-
Recommendations table instance.
- $recommendationId : string|int
-
Recommendation ID to transition.
- $data : array<string, mixed>
-
Transition input.
- $actorId : int
-
Current user ID.
Return values
array<string, mixed>transitionMany()
Transition multiple recommendations and return structured transition data.
public
transitionMany(Table $recommendationsTable, array<string, mixed> $data, int $actorId) : array<string, mixed>
Parameters
- $recommendationsTable : Table
-
Recommendations table instance.
- $data : array<string, mixed>
-
Transition input, including ids/recommendationIds.
- $actorId : int
-
Current user ID.
Return values
array<string, mixed>applyTransition()
Apply the transition semantics to one recommendation.
private
applyTransition(Table $recommendationsTable, Recommendation $recommendation, string $targetState, array<string, mixed> $data, int $actorId, string $defaultNoteSubject) : array<string, mixed>
Parameters
- $recommendationsTable : Table
-
Recommendations table instance.
- $recommendation : Recommendation
-
Recommendation to update.
- $targetState : string
-
Target state name.
- $data : array<string, mixed>
-
Transition input.
- $actorId : int
-
Current user ID.
- $defaultNoteSubject : string
-
Default subject for created notes.
Return values
array<string, mixed>buildChangeSet()
Build a structured before/after diff for transition-relevant fields.
private
buildChangeSet(array<string, mixed> $before, Recommendation $recommendation, array<int, string> $ruleFields) : array<string, array{before: mixed, after: mixed}>
Parameters
- $before : array<string, mixed>
-
Previous values.
- $recommendation : Recommendation
-
Saved recommendation.
- $ruleFields : array<int, string>
-
Fields affected by Set rules.
Return values
array<string, array{before: mixed, after: mixed}>extractIds()
Extract and normalize recommendation IDs from supported input keys.
private
extractIds(array<string, mixed> $data) : array<int, string>
Parameters
- $data : array<string, mixed>
-
Transition input.
Return values
array<int, string>extractTargetState()
Extract target state from supported input keys.
private
extractTargetState(array<string, mixed> $data) : string
Parameters
- $data : array<string, mixed>
-
Transition input.
Return values
stringgetOptionalValue()
Return the first matching value for a set of supported keys.
private
getOptionalValue(array<string, mixed> $data, array<int, string> $keys) : mixed
Parameters
- $data : array<string, mixed>
-
Transition input.
- $keys : array<int, string>
-
Candidate keys.
hasAnyKey()
Check whether any of the provided keys exist in the data payload.
private
hasAnyKey(array<string, mixed> $data, array<int, string> $keys) : bool
Parameters
- $data : array<string, mixed>
-
Transition input.
- $keys : array<int, string>
-
Candidate keys.
Return values
boolnormalizeGiven()
Normalize the given date to midnight UTC for storage.
private
normalizeGiven(mixed $given) : DateTime|null
Parameters
- $given : mixed
-
Given date input.
Return values
DateTime|nullnormalizeOptionalString()
Convert blank strings to null.
private
normalizeOptionalString(mixed $value) : string|null
Parameters
- $value : mixed
-
Input value.
Return values
string|nullresolveHandoffRecommendationIds()
Resolve selected handoff IDs to group heads so grouped children are not transitioned independently.
private
resolveHandoffRecommendationIds(Table $recommendationsTable, array<int, string> $ids, bool $normalizeGroupChildren) : array<int, string>
Parameters
- $recommendationsTable : Table
-
Recommendations table instance.
- $ids : array<int, string>
-
Requested recommendation IDs.
- $normalizeGroupChildren : bool
-
Whether child IDs may be normalized to their group head.
Return values
array<int, string>resolveNoteSubject()
Resolve the note subject from supported input keys.
private
resolveNoteSubject(array<string, mixed> $data, string $defaultNoteSubject) : string
Parameters
- $data : array<string, mixed>
-
Transition input.
- $defaultNoteSubject : string
-
Default subject.
Return values
stringrunTransitions()
Execute one or more transitions inside a transaction.
private
runTransitions(Table $recommendationsTable, array<int, string> $ids, array<string, mixed> $data, int $actorId, string $defaultNoteSubject, bool $normalizeHandoffGroupChildren) : array<string, mixed>
Parameters
- $recommendationsTable : Table
-
Recommendations table instance.
- $ids : array<int, string>
-
Recommendation IDs.
- $data : array<string, mixed>
-
Transition input.
- $actorId : int
-
Current user ID.
- $defaultNoteSubject : string
-
Default subject for created notes.
- $normalizeHandoffGroupChildren : bool
-
Whether grouped child IDs should be replaced by their head ID.
Return values
array<string, mixed>serializeValue()
Serialize values for structured transition output.
private
serializeValue(mixed $value) : mixed
Parameters
- $value : mixed
-
Value to serialize.