KMP PHP API Reference

Recommendation extends BaseEntity
in package

Recommendation Entity - Award recommendation workflow with state machine.

Implements dual status/state tracking:

  • Status: high-level category (In Progress, Scheduling, To Give, Closed)
  • State: specific workflow position within the status category

Table of Contents

Constants

GATHERING_ASSIGNABLE_STATES  : mixed = ['Need to Schedule', 'Scheduled', 'Given']
States that support assigning a scheduled gathering.

Properties

$award  : Award
$award_id  : int
$bestowal  : Bestowal|null
$bestowal_id  : int|null
$branch  : Branch
$branch_id  : int|null
$call_into_court  : string|null
$close_reason  : string|null
$contact_email  : string|null
$contact_number  : string
$court_availability  : string|null
$created  : DateTime
$created_by  : int|null
$current_approval_run  : RecommendationApprovalRun|null
$deleted  : DateTime|null
$event  : Event
$event_id  : int|null
$gathering_id  : int|null
$given  : DateTime|null
$group_children  : array<string|int, Recommendation>
$group_head  : Recommendation|null
$group_origin_state  : string|null
$group_origin_status  : string|null
$id  : int
$member  : Member
$member_id  : int|null
$member_sca_name  : string
$modified  : DateTime|null
$modified_by  : int|null
$person_to_notify  : string|null
$reason  : string|null
$recommendation_group_id  : int|null
$requester  : Member
$requester_id  : int
$requester_sca_name  : string
$specialty  : string|null
$stack_rank  : int|null
$state  : string
$state_date  : DateTime|null
$status  : string
$_accessible  : array<string, bool>

Methods

clearCache()  : void
Preserve the state-machine cache reset contract used by tests/services.
getBranchId()  : int|null
Get the branch ID from the associated award.
getHiddenStates()  : array<int, string>
Get hidden states that require ViewHidden permission.
getStateRules()  : array<string, array<string, mixed>>
Get field rules grouped by state name from configuration.
getStates()  : array<int, string>
Get valid states, optionally filtered by status.
getStatuses()  : array<string, array<int, string>>
Get status categories and their state mappings from configuration.
getValidTransitionsFrom()  : array<int, string>
Get valid transitions from a given state.
isGroupChild()  : bool
Whether this recommendation is a child in a group.
isGroupHead()  : bool
Whether this recommendation is a group head (has children grouped under it).
isLockedByBestowal()  : bool
Whether this recommendation is locked because it is linked to a bestowal.
supportsGatheringAssignmentForState()  : bool
Determine whether a recommendation state supports a scheduled gathering assignment.
_setGiven()  : DateTimeInterface|null
Handle date format conversion for given date.
_setState()  : string
State machine setter - validates state and auto-updates status.

Constants

GATHERING_ASSIGNABLE_STATES

States that support assigning a scheduled gathering.

private mixed GATHERING_ASSIGNABLE_STATES = ['Need to Schedule', 'Scheduled', 'Given']

Properties

$recommendation_group_id

public int|null $recommendation_group_id

$_accessible

protected array<string, bool> $_accessible = [ 'recommendation_group_id' => true, 'group_origin_state' => true, 'group_origin_status' => true, 'requester_id' => true, 'stack_rank' => true, 'member_id' => true, 'branch_id' => true, 'award_id' => true, 'event_id' => true, // Deprecated - kept for migration compatibility, use gathering_id instead 'gathering_id' => true, 'bestowal_id' => true, 'given' => true, 'status' => true, 'state' => true, 'state_date' => true, 'stack_rank' => true, 'requester_sca_name' => true, 'member_sca_name' => true, 'contact_number' => true, 'contact_email' => true, 'reason' => true, 'specialty' => true, 'call_into_court' => true, 'court_availability' => true, 'modified' => true, 'created' => true, 'created_by' => true, 'modified_by' => true, 'deleted' => true, 'member' => true, 'events' => true, 'gatherings' => true, 'person_to_notify' => true, 'close_reason' => true, ]

Methods

clearCache()

Preserve the state-machine cache reset contract used by tests/services.

public static clearCache() : void

Recommendation states are YAML-backed app settings, so there is no entity-local cache to clear.

getBranchId()

Get the branch ID from the associated award.

public getBranchId() : int|null
Return values
int|null —

Branch ID or null if not determinable

getHiddenStates()

Get hidden states that require ViewHidden permission.

public static getHiddenStates() : array<int, string>
Return values
array<int, string> —

List of hidden state names

getStateRules()

Get field rules grouped by state name from configuration.

public static getStateRules() : array<string, array<string, mixed>>

Returns an array keyed by state name where each value contains rule type groups: Visible, Optional, Required, Disabled, Set.

Return values
array<string, array<string, mixed>> —

State name => rules

getStates()

Get valid states, optionally filtered by status.

public static getStates([string|null $status = null ]) : array<int, string>
Parameters
$status : string|null = null

Optional status filter

Return values
array<int, string> —

Valid states list

getStatuses()

Get status categories and their state mappings from configuration.

public static getStatuses() : array<string, array<int, string>>
Return values
array<string, array<int, string>> —

Status name => [state names]

getValidTransitionsFrom()

Get valid transitions from a given state.

public static getValidTransitionsFrom(string $fromState) : array<int, string>

The YAML-based state machine permits transitioning from any state to any other state, so this returns every configured state except the current one.

Parameters
$fromState : string

The current state name

Return values
array<int, string> —

List of state names that can be transitioned to

isGroupChild()

Whether this recommendation is a child in a group.

public isGroupChild() : bool
Return values
bool

isGroupHead()

Whether this recommendation is a group head (has children grouped under it).

public isGroupHead() : bool
Return values
bool

isLockedByBestowal()

Whether this recommendation is locked because it is linked to a bestowal.

public isLockedByBestowal() : bool

Linked recommendations are read-only in the recommendation UI; changes flow through the bestowal workflow until the link is cleared (e.g. cancellation).

Return values
bool

supportsGatheringAssignmentForState()

Determine whether a recommendation state supports a scheduled gathering assignment.

public static supportsGatheringAssignmentForState(string $state) : bool
Parameters
$state : string

Workflow state name.

Return values
bool

_setGiven()

Handle date format conversion for given date.

protected _setGiven(mixed $value) : DateTimeInterface|null
Parameters
$value : mixed

Date value

Return values
DateTimeInterface|null

_setState()

State machine setter - validates state and auto-updates status.

protected _setState(string $value) : string

Reads valid states and field rules from Awards.* YAML app settings.

Parameters
$value : string

New state value

Tags
throws
InvalidArgumentException

When state is invalid

Return values
string —

Validated state value

On this page

Search results