DefaultWorkflowVersionManager
in package
implements
WorkflowVersionManagerInterface
Manages workflow version lifecycle: drafting, publishing, archiving, instance migration, and version comparison.
Table of Contents
Interfaces
- WorkflowVersionManagerInterface
- Contract for managing workflow version lifecycle.
Methods
- archive() : ServiceResult
- Archive a version. If it is the current published version, also clears the definition's current_version_id.
- compareVersions() : array{added: array, removed: array, modified: array}
- Compare two versions and return structural differences.
- createDraft() : ServiceResult
- Create a new draft version for a workflow definition.
- getCurrentVersion() : WorkflowVersion|null
- Get the currently published version for a definition.
- getVersionHistory() : array<string|int, WorkflowVersion>
- Get all versions for a definition, ordered newest first.
- migrateInstance() : ServiceResult
- Migrate a running instance to a target version.
- publish() : ServiceResult
- Publish a draft version within a transaction.
- updateDraft() : ServiceResult
- Update an existing draft version.
- validateDefinition() : array<string|int, string>
- Validate a workflow definition structure.
- detectCycles() : array<string|int, array<string|int, string>>
- Detect cycles in the workflow graph using DFS.
- dfsDetectCycles() : void
- Recursive DFS helper for cycle detection.
- findReachableNodes() : array<string|int, string>
- Find all nodes reachable from a starting node via BFS.
- isSchemaFieldHidden() : bool
- Check whether a schema field is internal-only and should be skipped by user-facing validation.
- normalizeLegacyDefinition() : array<string|int, mixed>
- Add the current schema envelope to definitions saved before it was required.
Methods
archive()
Archive a version. If it is the current published version, also clears the definition's current_version_id.
public
archive(int $versionId) : ServiceResult
Parameters
- $versionId : int
-
Version to archive
Return values
ServiceResultcompareVersions()
Compare two versions and return structural differences.
public
compareVersions(int $versionId1, int $versionId2) : array{added: array, removed: array, modified: array}
Parameters
- $versionId1 : int
-
First version ID
- $versionId2 : int
-
Second version ID
Return values
array{added: array, removed: array, modified: array}createDraft()
Create a new draft version for a workflow definition.
public
createDraft(int $definitionId, array<string|int, mixed> $definition[, array<string|int, mixed>|null $canvasLayout = null ][, string|null $changeNotes = null ]) : ServiceResult
Parameters
- $definitionId : int
-
Workflow definition to version
- $definition : array<string|int, mixed>
-
Workflow graph
- $canvasLayout : array<string|int, mixed>|null = null
-
Visual layout data
- $changeNotes : string|null = null
-
Description of changes
Return values
ServiceResultgetCurrentVersion()
Get the currently published version for a definition.
public
getCurrentVersion(int $definitionId) : WorkflowVersion|null
Parameters
- $definitionId : int
-
Workflow definition ID
Return values
WorkflowVersion|nullgetVersionHistory()
Get all versions for a definition, ordered newest first.
public
getVersionHistory(int $definitionId) : array<string|int, WorkflowVersion>
Parameters
- $definitionId : int
-
Workflow definition ID
Return values
array<string|int, WorkflowVersion>migrateInstance()
Migrate a running instance to a target version.
public
migrateInstance(int $instanceId, int $targetVersionId, int|null $migratedBy[, array<string|int, mixed>|null $nodeMapping = null ]) : ServiceResult
Auto-generates node mapping if not provided by matching node keys. Creates an audit record of the migration.
Parameters
- $instanceId : int
-
Instance to migrate
- $targetVersionId : int
-
Target version (must be published)
- $migratedBy : int|null
-
User performing the migration, or null for a system migration
- $nodeMapping : array<string|int, mixed>|null = null
-
Explicit old-key => new-key mapping
Return values
ServiceResultpublish()
Publish a draft version within a transaction.
public
publish(int $versionId, int $publishedBy) : ServiceResult
Archives any existing published version, marks this version published, and updates the definition's current_version_id.
Parameters
- $versionId : int
-
Draft version to publish
- $publishedBy : int
-
User ID publishing the version
Return values
ServiceResultupdateDraft()
Update an existing draft version.
public
updateDraft(int $versionId, array<string|int, mixed> $definition[, array<string|int, mixed>|null $canvasLayout = null ][, string|null $changeNotes = null ]) : ServiceResult
Parameters
- $versionId : int
-
Draft version to update
- $definition : array<string|int, mixed>
-
Updated workflow graph
- $canvasLayout : array<string|int, mixed>|null = null
-
Visual layout data
- $changeNotes : string|null = null
-
Description of changes
Return values
ServiceResultvalidateDefinition()
Validate a workflow definition structure.
protected
validateDefinition(array<string|int, mixed> $definition) : array<string|int, string>
Parameters
- $definition : array<string|int, mixed>
-
Workflow graph to validate
Return values
array<string|int, string> —Array of error messages; empty if valid
detectCycles()
Detect cycles in the workflow graph using DFS.
private
detectCycles(string $startKey, array<string|int, mixed> $nodes) : array<string|int, array<string|int, string>>
Loop nodes with 'continue' port back-edges are excluded since they are bounded by maxIterations.
Parameters
- $startKey : string
-
Starting node key
- $nodes : array<string|int, mixed>
-
All nodes in the definition
Return values
array<string|int, array<string|int, string>> —Each element is an array of node keys forming a cycle
dfsDetectCycles()
Recursive DFS helper for cycle detection.
private
dfsDetectCycles(string $nodeKey, array<string|int, mixed> $nodes, array<string|int, mixed> &$visited, array<string|int, mixed> &$stack, array<string|int, mixed> &$cycles) : void
Parameters
- $nodeKey : string
- $nodes : array<string|int, mixed>
- $visited : array<string|int, mixed>
- $stack : array<string|int, mixed>
- $cycles : array<string|int, mixed>
findReachableNodes()
Find all nodes reachable from a starting node via BFS.
private
findReachableNodes(string $startKey, array<string|int, mixed> $nodes) : array<string|int, string>
Parameters
- $startKey : string
-
Starting node key
- $nodes : array<string|int, mixed>
-
All nodes in the definition
Return values
array<string|int, string> —Keys of reachable nodes
isSchemaFieldHidden()
Check whether a schema field is internal-only and should be skipped by user-facing validation.
private
isSchemaFieldHidden(array<string|int, mixed> $paramMeta) : bool
Parameters
- $paramMeta : array<string|int, mixed>
-
Schema metadata
Return values
boolnormalizeLegacyDefinition()
Add the current schema envelope to definitions saved before it was required.
private
normalizeLegacyDefinition(array<string|int, mixed> $definition) : array<string|int, mixed>
Explicit values are preserved so unsupported schema versions still fail publish validation instead of being silently rewritten.
Parameters
- $definition : array<string|int, mixed>
-
Workflow graph