KMP PHP API Reference

CoreActions
in package
uses QueuedMailerAwareTrait, WorkflowActionTrait, WorkflowContextAwareTrait

Core workflow actions: email, notes, entity updates, role assignment, variable setting, and ActiveWindow temporal management.

Table of Contents

Properties

$mailer  : Mailer
$activeWindowManager  : ActiveWindowManagerInterface
$expressionEvaluator  : ExpressionEvaluator

Methods

__construct()  : mixed
assignRole()  : array<string|int, mixed>
Assign a role to a member, optionally using ActiveWindow for temporal bounds.
createNote()  : array<string|int, mixed>
Create a note on an entity.
getObjectById()  : array<string|int, mixed>
Get one registered workflow object by primary key.
sendEmail()  : array<string|int, mixed>
Send an email notification.
setVariable()  : array<string|int, mixed>
Set a variable in the workflow context.
startActiveWindow()  : array<string|int, mixed>
Start temporal management (active window) for an entity.
stopActiveWindow()  : array<string|int, mixed>
Stop temporal management (active window) for an entity.
syncActiveWindowStatuses()  : array<string|int, mixed>
Batch sync all temporal statuses (Upcoming→Current, Current→Expired).
updateEntity()  : array<string|int, mixed>
Update fields on an entity.
coerceDateTime()  : DateTime|null
Normalize date-like action input values.
guard()  : array{success: bool, data: array, error: string|null}
Run action code and return a standard ActionResult envelope.
queueMail()  : Mailer
Returns a mailer instance.
queueMailJob()  : void
Queues a mail job to be processed later.
resolveValue()  : mixed
Resolve a config value from context if it starts with '$.'.
sendMailNow()  : Mailer
Returns a mailer instance.
discoverActiveWindowAliases()  : array<string|int, string>
Discover table aliases whose entities extend ActiveWindowBaseEntity.
scanTableDir()  : array<string|int, string>
Scan a directory for Table classes and return aliases of ActiveWindow tables.
syncTable()  : void
Synchronize statuses for a single table.
tableAliasForRegisteredEntity()  : string
Resolve a workflow entity registration to a Cake table alias.
variableResult()  : array<string|int, mixed>
Build the assign-variable action result and context update payload.

Properties

Methods

assignRole()

Assign a role to a member, optionally using ActiveWindow for temporal bounds.

public assignRole(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string|int, mixed>

When entityType+entityId+startOn are all provided, delegates to ActiveWindowManager so the role assignment is linked to the granting entity with temporal lifecycle.

Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Action configuration with 'memberId', 'roleId', optional date/entity fields

Return values
array<string|int, mixed> —

Output with 'memberRoleId'

createNote()

Create a note on an entity.

public createNote(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string|int, mixed>
Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Action configuration with 'entityType', 'entityId', 'subject', 'body'

Return values
array<string|int, mixed> —

Output with 'noteId'

getObjectById()

Get one registered workflow object by primary key.

public getObjectById(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string|int, mixed>

Only workflow-safe entity fields are returned so this action cannot expose columns filtered out by the workflow entity registry.

Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Action configuration with 'entityType' and 'entityId'

Return values
array<string|int, mixed> —

Output with 'found', 'record', and diagnostic fields

sendEmail()

Send an email notification.

public sendEmail(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string|int, mixed>

The action requires a 'template' value, which is normally a stable slug such as "warrant-issued". Numeric IDs are still accepted for migration compatibility and route through the same KMPMailer::sendFromTemplate path.

Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Action configuration

Return values
array<string|int, mixed> —

Output with 'sent' boolean

setVariable()

Set a variable in the workflow context.

public setVariable(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string|int, mixed>

Values prefixed with '=' are evaluated as expressions (date math, templates, etc.). All other values use standard context path resolution for backward compatibility.

Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Action configuration with 'name' and 'value'

Return values
array<string|int, mixed> —

Output with the variable name and value

startActiveWindow()

Start temporal management (active window) for an entity.

public startActiveWindow(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string|int, mixed>
Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Action configuration with 'entityType', 'entityId', optional dates and roleId

Return values
array<string|int, mixed> —

Output with 'memberRoleId' and 'status'

stopActiveWindow()

Stop temporal management (active window) for an entity.

public stopActiveWindow(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string|int, mixed>
Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Action configuration with 'entityType', 'entityId', 'newStatus'

Return values
array<string|int, mixed> —

Output with 'stopped' boolean

syncActiveWindowStatuses()

Batch sync all temporal statuses (Upcoming→Current, Current→Expired).

public syncActiveWindowStatuses(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string|int, mixed>

Mirrors the logic in SyncActiveWindowStatusesCommand for use from workflows.

Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Action configuration with optional 'entityType' filter

Return values
array<string|int, mixed> —

Output with transition counts

updateEntity()

Update fields on an entity.

public updateEntity(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string|int, mixed>
Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Action configuration with 'entityType', 'entityId', 'fields'

Return values
array<string|int, mixed> —

Output with 'updated' boolean

coerceDateTime()

Normalize date-like action input values.

protected coerceDateTime(mixed $value[, string|null $default = null ]) : DateTime|null
Parameters
$value : mixed

DateTime, string, or null

$default : string|null = null

Default date/time expression for null input

Return values
DateTime|null

guard()

Run action code and return a standard ActionResult envelope.

protected guard(string $name, callable $fn) : array{success: bool, data: array, error: string|null}
Parameters
$name : string

Action name for logging

$fn : callable

Action implementation

Return values
array{success: bool, data: array, error: string|null}

queueMail()

Returns a mailer instance.

protected queueMail(string $name, mixed $action, mixed $to, mixed $vars) : Mailer
Parameters
$name : string

Mailer's name.

$action : mixed
$to : mixed
$vars : mixed
Tags
throws
MissingMailerException

if undefined mailer class.

Return values
Mailer

queueMailJob()

Queues a mail job to be processed later.

protected queueMailJob(array<string|int, mixed> $data) : void
Parameters
$data : array<string|int, mixed>

Data to be passed to the mailer.

resolveValue()

Resolve a config value from context if it starts with '$.'.

protected resolveValue(mixed $value, array<string|int, mixed> $context) : mixed
Parameters
$value : mixed

Raw value or context path (e.g. '$.trigger.memberId')

$context : array<string|int, mixed>

Current workflow context

Return values
mixed —

Resolved value

sendMailNow()

Returns a mailer instance.

protected sendMailNow(array<string|int, mixed> $data) : Mailer
Parameters
$data : array<string|int, mixed>
Tags
throws
MissingMailerException

if undefined mailer class.

Return values
Mailer

discoverActiveWindowAliases()

Discover table aliases whose entities extend ActiveWindowBaseEntity.

private discoverActiveWindowAliases(TableLocator $tableLocator) : array<string|int, string>
Parameters
$tableLocator : TableLocator

Table locator instance

Return values
array<string|int, string>

scanTableDir()

Scan a directory for Table classes and return aliases of ActiveWindow tables.

private scanTableDir(string $path, TableLocator $tableLocator[, string|null $plugin = null ]) : array<string|int, string>
Parameters
$path : string

Directory path

$tableLocator : TableLocator

Table locator

$plugin : string|null = null

Plugin prefix

Return values
array<string|int, string>

syncTable()

Synchronize statuses for a single table.

private syncTable(Table $table, DateTime $now, array<string|int, mixed> &$transitioned) : void
Parameters
$table : Table

Table to sync

$now : DateTime

Current timestamp

$transitioned : array<string|int, mixed>

Transition counters (modified by reference)

tableAliasForRegisteredEntity()

Resolve a workflow entity registration to a Cake table alias.

private tableAliasForRegisteredEntity(array<string|int, mixed> $registeredEntity) : string
Parameters
$registeredEntity : array<string|int, mixed>

Workflow entity registration

Return values
string —

Table alias for TableLocator

variableResult()

Build the assign-variable action result and context update payload.

private variableResult(string $name, mixed $value) : array<string|int, mixed>
Parameters
$name : string

Variable name

$value : mixed

Variable value

Return values
array<string|int, mixed>
On this page

Search results