Documentation: HierarchicalStateDefinition.php

Original file: src/Fsm/Data/HierarchicalStateDefinition.php

HierarchicalStateDefinition Documentation

Table of Contents

• Introduction
• Constructor

Introduction

The HierarchicalStateDefinition class extends the functionality of the StateDefinition class within the finite state machine (FSM) framework. This class is designed to support nested state machines, enabling complex hierarchical state representations. This capability is crucial for applications that require a structured approach to managing state transitions in various contexts, exemplified by user interfaces, workflows, and complex data processing.

By allowing the inclusion of child state machines, this class enriches the FSM implementation with the ability to encapsulate related states and transitions, promoting reusability and separation of concerns.

Constructor

public function __construct(
    FsmStateEnum|string $name,
    array|Collection $onEntryCallbacks = [],
    array|Collection $onExitCallbacks = [],
    ?string $description = null,
    string $type = self::TYPE_INTERMEDIATE,
    ?string $category = null,
    string $behavior = self::BEHAVIOR_PERSISTENT,
    array $metadata = [],
    bool $isTerminal = false,
    int $priority = 50,
    public readonly ?FsmRuntimeDefinition $childStateMachine = null,
    public readonly ?string $parentState = null,
)

Purpose

The constructor initializes a new instance of the HierarchicalStateDefinition class, setting the parameters that define the state, its transitions, and any hierarchical relationships.

Parameters

Functionality

The constructor sets the initial state properties and establishes relationships with potential child and parent states. Upon calling the constructor, the following actions are performed:

1. It invokes the parent class's constructor, passing along parameters related to the state setup.
2. Initializes the additional properties specific to hierarchical state management, including any defined child state machines and relationships to parent states.

This structure not only organizes state-related information but also effectively manages complex state transition scenarios, making it particularly useful for developers building dynamic applications that rely on an FSM framework.

Example Usage

use Fsm\Data\HierarchicalStateDefinition;
use Fsm\Contracts\MyStateEnum;

$state = new HierarchicalStateDefinition(
    name: MyStateEnum::INITIAL,
    onEntryCallbacks: [$this->handleInitialEntry()],
    onExitCallbacks: [$this->handleInitialExit()],
    description: 'The initial state of the workflow.',
    childStateMachine: $childStateDefinition, // Assuming $childStateDefinition is defined
    parentState: null  // This is a root state
);

Conclusion

The HierarchicalStateDefinition class serves as a foundational component in building complex state machines that require organized and manageable state hierarchies. By leveraging this class, developers can create robust applications that effectively handle various states and transitions, enhancing the overall software architecture.