BestowalTodoMaterializationService
in package
uses
LocatorAwareTrait
Builds a bestowal's parallel to-do checklist from its award's assigned bestowal to-do template and materializes them as core ActionItems.
This is the bridge between the Awards-specific template configuration and the reusable action-item subsystem. Each template item becomes an ActionItem:
- member items map to the core
memberassignee type (no branch needed); - role / permission / office items map to the core
dynamictype backed by BestowalTodoAssigneeResolver, with the branch scope resolved here (award branch, or an ancestor branch of a configured type) and stored on the ActionItem so eligibility is recomputed live.
Materialization is idempotent on the template item key, so re-running for an existing bestowal will not duplicate checklist items.
Table of Contents
Constants
- SYNC_FAILURE_REASON : mixed = 'Bestowal to-do synchronization failed. Review...
Properties
- $actionItemService : ActionItemService
- $ancestorBranchMemo : array<string, EntityInterface|null>
Methods
- __construct() : mixed
- countOutdatedOpenBestowals() : int
- Count open bestowals assigned to a template that were materialized from a different version of that template.
- materializeForBestowal() : ServiceResult
- Materialize the to-do checklist for a saved bestowal.
- syncForBestowal() : ServiceResult
- Reconcile one open bestowal's to-dos with its award's current template.
- syncOpenBestowalsForTemplate() : ServiceResult
- Synchronize only outdated open bestowals assigned to one template.
- buildDefinition() : array<string, mixed>
- Convert a template item into an ActionItemService definition.
- buildTemplateSignature() : string
- Build a stable fingerprint of the template fields that control ActionItems.
- canonicalizeSignatureValue() : mixed
- Recursively sort associative JSON fields before hashing.
- emptySyncSummary() : array<string, int|bool|null>
- emptyTemplateContext() : array<string, mixed>
- findAncestorBranchByType() : EntityInterface|null
- Walk parent branches until a branch of the requested type is found.
- findOutdatedOpenBestowalIds() : array<int, int>
- Find open bestowals assigned to the selected template whose stored materialization signature differs from the current template.
- loadTemplate() : BestowalTodoTemplate|null
- Load an assigned template with its items in display order.
- lockPersistedBestowal() : Bestowal|null
- Serialize checklist work on the persisted bestowal when it exists.
- markTemplateSignatureCurrent() : void
- Record that a bestowal's ActionItems reflect the current template.
- resolveBranchId() : int|null
- Resolve the branch scope for a branch-scoped item.
- resolveTemplateContext() : ServiceResult
- Resolve the assigned template and convert its items to action definitions.
- syncBestowalIds() : ServiceResult
- Aggregate independent per-bestowal synchronization results.
- syncForBestowalInTransaction() : ServiceResult
- Reconcile one bestowal inside the caller's transaction.
- syncPersistedOpenBestowal() : ServiceResult
- Lock one open bestowal so concurrent bulk requests remain idempotent.
Constants
SYNC_FAILURE_REASON
private
mixed
SYNC_FAILURE_REASON
= 'Bestowal to-do synchronization failed. Review server logs for details.'
Properties
$actionItemService
private
ActionItemService
$actionItemService
$ancestorBranchMemo
private
array<string, EntityInterface|null>
$ancestorBranchMemo
= []
Methods
__construct()
public
__construct([ActionItemService|null $actionItemService = null ]) : mixed
Parameters
- $actionItemService : ActionItemService|null = null
-
Optional injected service.
countOutdatedOpenBestowals()
Count open bestowals assigned to a template that were materialized from a different version of that template.
public
countOutdatedOpenBestowals(int $templateId) : int
Parameters
- $templateId : int
-
Template ID.
Return values
intmaterializeForBestowal()
Materialize the to-do checklist for a saved bestowal.
public
materializeForBestowal(Bestowal $bestowal) : ServiceResult
Returns a successful (no-op) result when the bestowal's award has no assigned template, so callers can invoke this unconditionally.
Parameters
- $bestowal : Bestowal
-
Saved bestowal entity.
Return values
ServiceResult —Data is the array of created ActionItem entities.
syncForBestowal()
Reconcile one open bestowal's to-dos with its award's current template.
public
syncForBestowal(Bestowal $bestowal[, int|null $actorId = null ]) : ServiceResult
Parameters
- $bestowal : Bestowal
-
Saved bestowal entity.
- $actorId : int|null = null
-
Member initiating the synchronization, if any.
Return values
ServiceResult —Data contains item mutation counts and skip metadata.
syncOpenBestowalsForTemplate()
Synchronize only outdated open bestowals assigned to one template.
public
syncOpenBestowalsForTemplate(int $templateId[, int|null $actorId = null ]) : ServiceResult
Parameters
- $templateId : int
-
Template ID.
- $actorId : int|null = null
-
Member initiating the synchronization, if any.
Return values
ServiceResultbuildDefinition()
Convert a template item into an ActionItemService definition.
private
buildDefinition(BestowalTodoTemplateItem $item, int|null $awardBranchId) : array<string, mixed>
Parameters
- $item : BestowalTodoTemplateItem
-
Template item.
- $awardBranchId : int|null
-
The award's branch ID.
Return values
array<string, mixed>buildTemplateSignature()
Build a stable fingerprint of the template fields that control ActionItems.
private
buildTemplateSignature(BestowalTodoTemplate $template) : string
Parameters
- $template : BestowalTodoTemplate
-
Loaded template and items.
Return values
stringcanonicalizeSignatureValue()
Recursively sort associative JSON fields before hashing.
private
canonicalizeSignatureValue(mixed $value) : mixed
Parameters
- $value : mixed
-
Signature input.
emptySyncSummary()
private
emptySyncSummary(bool $skipped[, int|null $templateId = null ]) : array<string, int|bool|null>
Parameters
- $skipped : bool
-
Whether synchronization was intentionally skipped.
- $templateId : int|null = null
-
Assigned template ID, when available.
Return values
array<string, int|bool|null>emptyTemplateContext()
private
emptyTemplateContext([int|null $templateId = null ]) : array<string, mixed>
Parameters
- $templateId : int|null = null
-
Assigned template ID, when available.
Return values
array<string, mixed>findAncestorBranchByType()
Walk parent branches until a branch of the requested type is found.
private
findAncestorBranchByType(int $branchId, string $branchType) : EntityInterface|null
Parameters
- $branchId : int
-
Starting branch ID.
- $branchType : string
-
Target branch type.
Return values
EntityInterface|nullfindOutdatedOpenBestowalIds()
Find open bestowals assigned to the selected template whose stored materialization signature differs from the current template.
private
findOutdatedOpenBestowalIds(int $templateId, string $templateSignature) : array<int, int>
Parameters
- $templateId : int
-
Template ID.
- $templateSignature : string
-
Current template signature.
Return values
array<int, int>loadTemplate()
Load an assigned template with its items in display order.
private
loadTemplate(int $templateId) : BestowalTodoTemplate|null
Parameters
- $templateId : int
-
Template ID.
Return values
BestowalTodoTemplate|nulllockPersistedBestowal()
Serialize checklist work on the persisted bestowal when it exists.
private
lockPersistedBestowal(Bestowal $bestowal) : Bestowal|null
A missing row means the supplied entity is stale or was never saved; in either case checklist writes must not proceed without a lockable owner.
Parameters
- $bestowal : Bestowal
-
Bestowal context.
Return values
Bestowal|nullmarkTemplateSignatureCurrent()
Record that a bestowal's ActionItems reflect the current template.
private
markTemplateSignatureCurrent(int $bestowalId, string $templateSignature) : void
Parameters
- $bestowalId : int
-
Bestowal ID.
- $templateSignature : string
-
Materialized template signature.
resolveBranchId()
Resolve the branch scope for a branch-scoped item.
private
resolveBranchId(BestowalTodoTemplateItem $item, int|null $awardBranchId) : int|null
Parameters
- $item : BestowalTodoTemplateItem
-
Template item.
- $awardBranchId : int|null
-
The award's branch ID.
Return values
int|null —Concrete branch ID, or null when it cannot be resolved.
resolveTemplateContext()
Resolve the assigned template and convert its items to action definitions.
private
resolveTemplateContext(Bestowal $bestowal) : ServiceResult
Inactive templates remain authoritative when they are still assigned to an award. Missing templates are safe no-ops; a deliberately empty assigned template is an authoritative zero-item definition.
Parameters
- $bestowal : Bestowal
-
Saved bestowal entity.
Return values
ServiceResultsyncBestowalIds()
Aggregate independent per-bestowal synchronization results.
private
syncBestowalIds(array<int, int> $bestowalIds, int|null $actorId[, int|null $expectedTemplateId = null ][, string|null $expectedTemplateSignature = null ]) : ServiceResult
Parameters
- $bestowalIds : array<int, int>
-
Bestowal IDs selected for synchronization.
- $actorId : int|null
-
Member initiating synchronization, if any.
- $expectedTemplateId : int|null = null
-
Template assignment expected by a scoped scan.
- $expectedTemplateSignature : string|null = null
-
Template version expected by a scoped scan.
Return values
ServiceResultsyncForBestowalInTransaction()
Reconcile one bestowal inside the caller's transaction.
private
syncForBestowalInTransaction(Bestowal $bestowal, int|null $actorId) : ServiceResult
Parameters
- $bestowal : Bestowal
-
Saved bestowal entity.
- $actorId : int|null
-
Member initiating the synchronization, if any.
Return values
ServiceResultsyncPersistedOpenBestowal()
Lock one open bestowal so concurrent bulk requests remain idempotent.
private
syncPersistedOpenBestowal(int $bestowalId, int|null $actorId[, int|null $expectedTemplateId = null ][, string|null $expectedTemplateSignature = null ]) : ServiceResult
Parameters
- $bestowalId : int
-
Bestowal ID selected by the bulk scan.
- $actorId : int|null
-
Member initiating the synchronization, if any.
- $expectedTemplateId : int|null = null
- $expectedTemplateSignature : string|null = null