Documentation: StateTimelineEntryData.php

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

StateTimelineEntryData Documentation

Table of Contents

1. Introduction
2. Class Overview
3. Constructor
4. Properties
5. Usage Examples

Introduction

StateTimelineEntryData.php defines the StateTimelineEntryData class, which represents a Data Transfer Object (DTO) for individual state transitions within a finite state machine (FSM) context. The class encapsulates details pertinent to a state transition event—such as transition timestamps, state details, and additional context—that can be useful for logging, debugging, or analysis purposes.

This class is designed to be versatile, acting as both a structure for direct instantiation with named parameters or associative arrays, making it easier to construct instances with varying requirements.

Class Overview

Namespace

namespace Fsm\Data;

The StateTimelineEntryData class is part of the Fsm\Data namespace, organizing it within the broader finite state machine module.

Extends

class StateTimelineEntryData extends Dto

This class extends the base Dto class, inheriting its properties and functionalities, while providing additional specific properties and behaviors suited for handling state transition data.

Constructor

public function __construct(
    string|array $id,
    ?string $model_id = null,
    ?string $model_type = null,
    ?string $fsm_column = null,
    ?string $from_state = null,
    ?string $to_state = null,
    ?string $transition_event = null,
    ?array $context_snapshot = null,
    ?string $exception_details = null,
    ?int $duration_ms = null,
    ?CarbonImmutable $happened_at = null,
    ?string $subject_id = null,
    ?string $subject_type = null,
)

Purpose

The constructor initializes a new instance of StateTimelineEntryData, accepting a variety of parameters for the different aspects of the state transition event. It allows for flexibility in constructing instances either via individual arguments or an associative array.

Parameters

Functionality

The constructor contains logic that distinguishes between array-based construction and named parameter initialization. If an array is passed as the first argument:

• The method checks if it is associative and prepares attributes using a private method prepareAttributes().
• It validates the presence of required keys (only id is mandatory) and prepares the properties for the object.
• If an SDK-compliant associative array is not passed, an exception will be thrown to ensure clarity about expected input.

For named parameter initialization, it directly prepares and assigns attributes using prepareAttributes().

Properties

The class defines several public properties that store the details of the state transition. All properties are initialized to null by default except for $id, which is mandatory (type string).

Property Table

Usage Examples

To create a new instance of StateTimelineEntryData, you can do so either through named parameters or by passing an associative array:

Named Parameter Initialization

$entry = new StateTimelineEntryData(
    id: 'transition_1',
    model_id: 'model_1',
    from_state: 'initial',
    to_state: 'completed',
    transition_event: 'start_process',
    duration_ms: 200,
    happened_at: Carbon\CarbonImmutable::now()
);

Associative Array Initialization

$entry = new StateTimelineEntryData([
    'id' => 'transition_1',
    'model_id' => 'model_1',
    'from_state' => 'initial