RecommendationGroupingService
in package
uses
LocatorAwareTrait
Encapsulates recommendation grouping mechanics and origin-state restoration.
Table of Contents
Constants
- LINKED_STATES : array<int, string> = ['Linked', 'Linked - Closed']
Properties
- $approvalLifecycleService : RecommendationApprovalWorkflowLifecycleService
- $approvalRunsTable : Table
- $recommendationsTable : Table
- $stateLogService : RecommendationStateLogService
- $workflowApprovalsTable : Table
Methods
- __construct() : mixed
- groupRecommendations() : Recommendation
- Group recommendations under a shared head and snapshot each child origin state.
- removeFromGroup() : int
- Remove only the selected child, preserving the head and all remaining children.
- restoreChildrenForDeletedHead() : array<int, Recommendation>
- Restore children when a group head is deleted.
- syncLinkedChildrenState() : int
- Keep linked children aligned with the current head open/closed state.
- ungroupRecommendations() : array<int, Recommendation>
- Ungroup all children from the supplied head.
- applyActor() : void
- Apply the actor ID to a recommendation so downstream logs are attributed.
- assertCompatibleMembers() : void
- Validate that grouped recommendations point at the same member or no member.
- assertGroupingPermitted() : void
- Assert that the selected recommendations are still groupable.
- captureOriginSnapshot() : void
- Snapshot the child's current non-linked state for future restoration.
- chooseHead() : Recommendation
- Choose the grouping head using the existing controller preference rules.
- clearOriginSnapshot() : void
- Clear any persisted origin snapshot after a child leaves a group.
- collectChildIdsForGrouping() : array<string|int, int>
- determineLinkedStateForHead() : string
- Convert a head recommendation into the appropriate linked child state.
- findLegacyOriginSnapshot() : array{state: string, status: string|null}|null
- Find the most recent non-linked origin for a legacy grouped child.
- isLinkedState() : bool
- Determine whether a recommendation is already in a synthetic linked state.
- linkRecommendationToHead() : Recommendation
- Link a recommendation to the supplied head and capture its pre-group state.
- resolveOriginSnapshot() : array{state: string, status: string|null}
- Resolve the best available origin snapshot for a grouped child.
- restoreRecommendationToOrigin() : Recommendation
- Restore one recommendation to the origin snapshot captured at grouping time.
- withTransaction() : mixed
- Run a callback inside a transaction unless one is already active.
Constants
LINKED_STATES
private
array<int, string>
LINKED_STATES
= ['Linked', 'Linked - Closed']
Properties
$approvalLifecycleService
private
RecommendationApprovalWorkflowLifecycleService
$approvalLifecycleService
$approvalRunsTable
private
Table
$approvalRunsTable
$recommendationsTable
private
Table
$recommendationsTable
$stateLogService
private
RecommendationStateLogService
$stateLogService
$workflowApprovalsTable
private
Table
$workflowApprovalsTable
Methods
__construct()
public
__construct([Table|null $recommendationsTable = null ][, RecommendationStateLogService|null $stateLogService = null ][, Table|null $approvalRunsTable = null ][, Table|null $workflowApprovalsTable = null ][, RecommendationApprovalWorkflowLifecycleService|null $approvalLifecycleService = null ]) : mixed
Parameters
- $recommendationsTable : Table|null = null
-
Optional injected recommendations table.
- $stateLogService : RecommendationStateLogService|null = null
-
Optional injected state-log service.
- $approvalRunsTable : Table|null = null
-
Optional injected approval runs table.
- $workflowApprovalsTable : Table|null = null
-
Optional injected workflow approvals table.
- $approvalLifecycleService : RecommendationApprovalWorkflowLifecycleService|null = null
-
Optional lifecycle service.
groupRecommendations()
Group recommendations under a shared head and snapshot each child origin state.
public
groupRecommendations(array<int, int|string> $recommendationIds[, int|null $actorId = null ]) : Recommendation
Parameters
- $recommendationIds : array<int, int|string>
-
Recommendation IDs to group.
- $actorId : int|null = null
-
Current user ID.
Return values
RecommendationremoveFromGroup()
Remove only the selected child, preserving the head and all remaining children.
public
removeFromGroup(int $childId[, int|null $actorId = null ]) : int
Parameters
- $childId : int
-
Child recommendation ID.
- $actorId : int|null = null
-
Current user ID.
Return values
int —Former head recommendation ID.
restoreChildrenForDeletedHead()
Restore children when a group head is deleted.
public
restoreChildrenForDeletedHead(Recommendation|int $head[, int|null $actorId = null ]) : array<int, Recommendation>
Parameters
- $head : Recommendation|int
-
Group head entity or ID.
- $actorId : int|null = null
-
Current user ID.
Return values
array<int, Recommendation>syncLinkedChildrenState()
Keep linked children aligned with the current head open/closed state.
public
syncLinkedChildrenState(Recommendation|int $head[, int|null $actorId = null ]) : int
Parameters
- $head : Recommendation|int
-
Group head entity or ID.
- $actorId : int|null = null
-
Current user ID.
Return values
int —Number of children updated.
ungroupRecommendations()
Ungroup all children from the supplied head.
public
ungroupRecommendations(int $headId[, int|null $actorId = null ]) : array<int, Recommendation>
Parameters
- $headId : int
-
Group head recommendation ID.
- $actorId : int|null = null
-
Current user ID.
Return values
array<int, Recommendation>applyActor()
Apply the actor ID to a recommendation so downstream logs are attributed.
private
applyActor(Recommendation $recommendation, int|null $actorId) : void
Parameters
- $recommendation : Recommendation
-
Recommendation being saved.
- $actorId : int|null
-
Current user ID.
assertCompatibleMembers()
Validate that grouped recommendations point at the same member or no member.
private
assertCompatibleMembers(array<int, Recommendation> $recommendations) : void
Parameters
- $recommendations : array<int, Recommendation>
-
Selected recommendations.
assertGroupingPermitted()
Assert that the selected recommendations are still groupable.
private
assertGroupingPermitted(array<string|int, int> $ids) : void
Parameters
- $ids : array<string|int, int>
-
Recommendation IDs to check.
Tags
captureOriginSnapshot()
Snapshot the child's current non-linked state for future restoration.
private
captureOriginSnapshot(Recommendation $recommendation) : void
Parameters
- $recommendation : Recommendation
-
Recommendation being grouped.
chooseHead()
Choose the grouping head using the existing controller preference rules.
private
chooseHead(array<int, Recommendation> $recommendations) : Recommendation
Parameters
- $recommendations : array<int, Recommendation>
-
Selected recommendations.
Return values
RecommendationclearOriginSnapshot()
Clear any persisted origin snapshot after a child leaves a group.
private
clearOriginSnapshot(Recommendation $recommendation) : void
Parameters
- $recommendation : Recommendation
-
Recommendation being cleared.
collectChildIdsForGrouping()
private
collectChildIdsForGrouping(array<int, Recommendation> $recommendations, int $headId) : array<string|int, int>
Parameters
- $recommendations : array<int, Recommendation>
-
Selected recommendations.
- $headId : int
-
Chosen group head ID.
Return values
array<string|int, int>determineLinkedStateForHead()
Convert a head recommendation into the appropriate linked child state.
private
determineLinkedStateForHead(Recommendation $head) : string
Parameters
- $head : Recommendation
-
Group head.
Return values
stringfindLegacyOriginSnapshot()
Find the most recent non-linked origin for a legacy grouped child.
private
findLegacyOriginSnapshot(int $recommendationId) : array{state: string, status: string|null}|null
Parameters
- $recommendationId : int
-
Recommendation ID.
Return values
array{state: string, status: string|null}|nullisLinkedState()
Determine whether a recommendation is already in a synthetic linked state.
private
isLinkedState(string $state) : bool
Parameters
- $state : string
-
State name.
Return values
boollinkRecommendationToHead()
Link a recommendation to the supplied head and capture its pre-group state.
private
linkRecommendationToHead(Recommendation $recommendation, int $headId, string $targetState[, int|null $actorId = null ][, bool $preserveExistingOrigin = false ]) : Recommendation
Parameters
- $recommendation : Recommendation
-
Recommendation to link.
- $headId : int
-
Group head ID.
- $targetState : string
-
Linked state to apply.
- $actorId : int|null = null
-
Current user ID.
- $preserveExistingOrigin : bool = false
-
Keep a previously captured origin snapshot.
Return values
RecommendationresolveOriginSnapshot()
Resolve the best available origin snapshot for a grouped child.
private
resolveOriginSnapshot(Recommendation $recommendation) : array{state: string, status: string|null}
Parameters
- $recommendation : Recommendation
-
Grouped child.
Return values
array{state: string, status: string|null}restoreRecommendationToOrigin()
Restore one recommendation to the origin snapshot captured at grouping time.
private
restoreRecommendationToOrigin(Recommendation $recommendation[, int|null $actorId = null ]) : Recommendation
Parameters
- $recommendation : Recommendation
-
Child recommendation.
- $actorId : int|null = null
-
Current user ID.
Return values
RecommendationwithTransaction()
Run a callback inside a transaction unless one is already active.
private
withTransaction(callable(): mixed $callback) : mixed
Parameters
- $callback : callable(): mixed
-
Work to execute.