KMP PHP API Reference

RecommendationsTable extends BaseTable
in package

Application

Manages award recommendations and their workflow-facing persistence rules.

Handles the core recommendation record, associations, validation, and field-level persistence constraints. Workflow mutation services own audit logging, grouping side effects, and delete orchestration.

See /docs/5.2.4-awards-recommendations-table.md for complete documentation.

Constants

CACHE_GROUPS_TO_CLEAR : array<string|int, string> = []
CACHES_TO_CLEAR : array<string|int, array{string, string}> = []
ID_CACHES_TO_CLEAR : array<string|int, array{string, string}> = []

Properties

$AssignedEvent : EventsTable|BelongsTo
$Awards : AwardsTable|BelongsTo
$Bestowals : BestowalsTable|BelongsTo
$Branches : BranchesTable|BelongsTo
$CurrentApprovalRun : RecommendationApprovalRunsTable|HasOne
$Events : EventsTable|BelongsToMany
$Footprint : FootprintBehavior|Behavior
$Members : MembersTable|BelongsTo
$Notes : NotesTable|HasMany
$RecommendationStateLogs : RecommendationsStatesLogsTable|HasMany
$Requesters : MembersTable|BelongsTo
$ScheduledEvent : EventsTable|BelongsTo
$Timestamp : TimestampBehavior|Behavior
$Trash : TrashBehavior|Behavior

Methods

addBranchScopeQuery() : SelectQuery: Apply branch-based filtering to a recommendations query.
afterDelete() : void: After delete hook to capture impersonation audit trail entries.
afterSave() : void: After-save handler for automatic cache invalidation.
beforeSave() : void: Enforce recommendation workflow constraints before persisting changes.
buildRules() : RulesChecker: Business rules for referential integrity validation.
deleteMany() : iterable<string|int, Recommendation>|ResultSetInterface<string|int, Recommendation>|false
deleteManyOrFail() : iterable<string|int, Recommendation>|ResultSetInterface<string|int, Recommendation>
findOrCreate() : Recommendation
get() : Recommendation
initialize() : void: Configure the Recommendations table: table name, display/primary fields, behaviors, and associations.
newEmptyEntity() : Recommendation
newEntities() : array<string|int, Recommendation>
newEntity() : Recommendation
patchEntities() : array<string|int, Recommendation>
patchEntity() : Recommendation
save() : Recommendation|false
saveMany() : iterable<string|int, Recommendation>|ResultSetInterface<string|int, Recommendation>|false
saveManyOrFail() : iterable<string|int, Recommendation>|ResultSetInterface<string|int, Recommendation>
saveOrFail() : Recommendation
validationDefault() : Validator: Default validation rules for recommendation data.
isAwardSelectableForRecommendation() : bool: Allow inactive awards only when an existing recommendation keeps its current award.
logImpersonationAction() : void: Record impersonated writes to audit log table.
setJsonColumnTypesIfPresent() : void: Mark JSON columns when the table schema is available.
shouldRejectLockedUserChange() : bool: Whether a user-initiated save should be rejected due to bestowal lock.

CACHE_GROUPS_TO_CLEAR


    protected
        array<string|int, string>
    CACHE_GROUPS_TO_CLEAR
    = []

Cache groups to clear entirely on save

CACHES_TO_CLEAR


    protected
        array<string|int, array{string, string}>
    CACHES_TO_CLEAR
    = []

Static cache entries to clear on save

ID_CACHES_TO_CLEAR


    protected
        array<string|int, array{string, string}>
    ID_CACHES_TO_CLEAR
    = []

Entity-ID cache prefixes to clear on save

$AssignedEvent


        public
            EventsTable|BelongsTo
    $AssignedEvent

$Awards


        public
            AwardsTable|BelongsTo
    $Awards

$Bestowals


        public
            BestowalsTable|BelongsTo
    $Bestowals

$Branches


        public
            BranchesTable|BelongsTo
    $Branches

$CurrentApprovalRun


        public
            RecommendationApprovalRunsTable|HasOne
    $CurrentApprovalRun

$Events


        public
            EventsTable|BelongsToMany
    $Events

$Footprint


        public
            FootprintBehavior|Behavior
    $Footprint

$Members


        public
            MembersTable|BelongsTo
    $Members

$Notes


        public
            NotesTable|HasMany
    $Notes

$RecommendationStateLogs


        public
            RecommendationsStatesLogsTable|HasMany
    $RecommendationStateLogs

$Requesters


        public
            MembersTable|BelongsTo
    $Requesters

$ScheduledEvent


        public
            EventsTable|BelongsTo
    $ScheduledEvent

$Timestamp


        public
            TimestampBehavior|Behavior
    $Timestamp

$Trash


        public
            TrashBehavior|Behavior
    $Trash

addBranchScopeQuery()

Apply branch-based filtering to a recommendations query.


    public
                    addBranchScopeQuery(SelectQuery $query, array<string|int, int> $branchIDs) : SelectQuery

Filters the provided query so only records whose associated Awards.branch_id is contained in $branchIDs are returned. If $branchIDs is empty, the query is returned unchanged.

Parameters

$query : SelectQuery: The query to modify.
$branchIDs : array<string|int, int>: Array of branch IDs to restrict Awards.branch_id to.

Return values

SelectQuery —

The query with branch filtering applied.

afterDelete()

After delete hook to capture impersonation audit trail entries.


    public
                    afterDelete(EventInterface $event, EntityInterface $entity, ArrayObject $options) : void

Parameters

$event : EventInterface: Delete event
$entity : EntityInterface: Entity being deleted
$options : ArrayObject: Delete options

afterSave()

After-save handler for automatic cache invalidation.


    public
                    afterSave(EventInterface $event, EntityInterface $entity, ArrayObject $options) : void

Parameters

$event : EventInterface: The afterSave event
$entity : EntityInterface: The saved entity
$options : ArrayObject: Save options

beforeSave()

Enforce recommendation workflow constraints before persisting changes.


    public
                    beforeSave(EventInterface $event, EntityInterface $entity, ArrayObject $options) : void

Parameters

$event : EventInterface: The beforeSave event.
$entity : EntityInterface: The entity being persisted.
$options : ArrayObject: Save operation options.

buildRules()

Business rules for referential integrity validation.


    public
                    buildRules(RulesChecker $rules) : RulesChecker

Parameters

$rules : RulesChecker: The rules object to be modified.

Return values

RulesChecker

deleteMany()


    public
                    deleteMany(iterable<string|int, mixed> $entities[, array<string|int, mixed> $options =  = '[]' ]) : iterable<string|int, Recommendation>|ResultSetInterface<string|int, Recommendation>|false

Parameters

$entities : iterable<string|int, mixed>
$options : array<string|int, mixed> = = '[]'

Return values

iterable<string|int, Recommendation>|ResultSetInterface<string|int, Recommendation>|false

deleteManyOrFail()


    public
                    deleteManyOrFail(iterable<string|int, mixed> $entities[, array<string|int, mixed> $options =  = '[]' ]) : iterable<string|int, Recommendation>|ResultSetInterface<string|int, Recommendation>

Parameters

$entities : iterable<string|int, mixed>
$options : array<string|int, mixed> = = '[]'

Return values

iterable<string|int, Recommendation>|ResultSetInterface<string|int, Recommendation>

findOrCreate()


    public
                    findOrCreate(mixed $search[, callable|null $callback =  = 'null' ][, array<string|int, mixed> $options =  = '[]' ]) : Recommendation

Parameters

$search : mixed
$callback : callable|null = = 'null'
$options : array<string|int, mixed> = = '[]'

Return values

Recommendation

get()


    public
                    get(mixed $primaryKey[, array<string|int, mixed>|string $finder =  = '\'all\'' ][, CacheInterface|string|null $cache =  = 'null' ][, Closure|string|null $cacheKey =  = 'null' ], mixed ...$args) : Recommendation

Parameters

$primaryKey : mixed
$finder : array<string|int, mixed>|string = = '\'all\''
$cache : CacheInterface|string|null = = 'null'
$cacheKey : Closure|string|null = = 'null'
$args : mixed

Return values

Recommendation

initialize()

Configure the Recommendations table: table name, display/primary fields, behaviors, and associations.


    public
                    initialize(array<string, mixed> $config) : void

Sets the database table and primary/display fields, attaches timestamp, footprint, and trash behaviors, and defines associations used for member links, awards, events/gatherings, notes, and state logs.

Parameters

$config : array<string, mixed>: Table configuration options.

newEmptyEntity()


    public
                    newEmptyEntity() : Recommendation

Return values

Recommendation

newEntities()


    public
                    newEntities(array<string|int, mixed> $data[, array<string|int, mixed> $options =  = '[]' ]) : array<string|int, Recommendation>

Parameters

$data : array<string|int, mixed>
$options : array<string|int, mixed> = = '[]'

Return values

array<string|int, Recommendation>

newEntity()


    public
                    newEntity(array<string|int, mixed> $data[, array<string|int, mixed> $options =  = '[]' ]) : Recommendation

Parameters

$data : array<string|int, mixed>
$options : array<string|int, mixed> = = '[]'

Return values

Recommendation

patchEntities()


    public
                    patchEntities(iterable<string|int, mixed> $entities, array<string|int, mixed> $data[, array<string|int, mixed> $options =  = '[]' ]) : array<string|int, Recommendation>

Parameters

$entities : iterable<string|int, mixed>
$data : array<string|int, mixed>
$options : array<string|int, mixed> = = '[]'

Return values

array<string|int, Recommendation>

patchEntity()


    public
                    patchEntity(EntityInterface $entity, array<string|int, mixed> $data[, array<string|int, mixed> $options =  = '[]' ]) : Recommendation

Parameters

$entity : EntityInterface
$data : array<string|int, mixed>
$options : array<string|int, mixed> = = '[]'

Return values

Recommendation

save()


    public
                    save(EntityInterface $entity[, array<string|int, mixed> $options =  = '[]' ]) : Recommendation|false

Parameters

$entity : EntityInterface
$options : array<string|int, mixed> = = '[]'

Return values

Recommendation|false

saveMany()


    public
                    saveMany(iterable<string|int, mixed> $entities[, array<string|int, mixed> $options =  = '[]' ]) : iterable<string|int, Recommendation>|ResultSetInterface<string|int, Recommendation>|false

Parameters

$entities : iterable<string|int, mixed>
$options : array<string|int, mixed> = = '[]'

Return values

iterable<string|int, Recommendation>|ResultSetInterface<string|int, Recommendation>|false

saveManyOrFail()


    public
                    saveManyOrFail(iterable<string|int, mixed> $entities[, array<string|int, mixed> $options =  = '[]' ]) : iterable<string|int, Recommendation>|ResultSetInterface<string|int, Recommendation>

Parameters

$entities : iterable<string|int, mixed>
$options : array<string|int, mixed> = = '[]'

Return values

iterable<string|int, Recommendation>|ResultSetInterface<string|int, Recommendation>

saveOrFail()


    public
                    saveOrFail(EntityInterface $entity[, array<string|int, mixed> $options =  = '[]' ]) : Recommendation

Parameters

$entity : EntityInterface
$options : array<string|int, mixed> = = '[]'

Return values

Recommendation

validationDefault()

Default validation rules for recommendation data.


    public
                    validationDefault(Validator $validator) : Validator

Parameters

$validator : Validator: Validator instance.

Return values

Validator

isAwardSelectableForRecommendation()

Allow inactive awards only when an existing recommendation keeps its current award.


    protected
                    isAwardSelectableForRecommendation(EntityInterface $entity) : bool

Parameters

$entity : EntityInterface: Recommendation entity being saved

Return values

bool

logImpersonationAction()

Record impersonated writes to audit log table.


    protected
                    logImpersonationAction(string $defaultOperation, EntityInterface $entity) : void

Parameters

$defaultOperation : string: Operation fallback (save/delete)
$entity : EntityInterface: Affected entity

setJsonColumnTypesIfPresent()

Mark JSON columns when the table schema is available.


    protected
                    setJsonColumnTypesIfPresent(array<int, string> $columns) : void

Some reset/migration flows instantiate table classes before every table exists. JSON type mapping is optional metadata, so skip it until the schema can be described instead of failing application bootstrap.

Parameters

$columns : array<int, string>: JSON column names.

shouldRejectLockedUserChange()

Whether a user-initiated save should be rejected due to bestowal lock.


    protected
                    shouldRejectLockedUserChange(Recommendation $entity, ArrayObject $options) : bool

Parameters

$entity : Recommendation: Recommendation being saved
$options : ArrayObject: Save operation options

Return values

bool

RecommendationsTable extends BaseTable in package Application

Tags

Table of Contents

Constants

Properties

Methods

Constants

CACHE_GROUPS_TO_CLEAR

CACHES_TO_CLEAR

ID_CACHES_TO_CLEAR

Properties

$AssignedEvent

$Awards

$Bestowals

$Branches

$CurrentApprovalRun

$Events

$Footprint

$Members

$Notes

$RecommendationStateLogs

$Requesters

$ScheduledEvent

$Timestamp

$Trash

Methods

addBranchScopeQuery()

Parameters

Return values

afterDelete()

Parameters

afterSave()

Parameters

beforeSave()

Parameters

buildRules()

Parameters

Return values

deleteMany()

Parameters

Return values

deleteManyOrFail()

Parameters

Return values

findOrCreate()

Parameters

Return values

get()

Parameters

Return values

initialize()

Parameters

newEmptyEntity()

Return values

newEntities()

Parameters

Return values

newEntity()

Parameters

Return values

patchEntities()

Parameters

Return values

patchEntity()

Parameters

Return values

save()

Parameters

Return values

saveMany()

Parameters

Return values

saveManyOrFail()

Parameters

Return values

saveOrFail()

Parameters

Return values

validationDefault()

Parameters

RecommendationsTable extends BaseTable
in package

Application