Documentation: ReplayHistoryRequest.php

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

ReplayHistoryRequest Documentation

Table of Contents

• Introduction
• Constructor
• Validation Rules

Introduction

The ReplayHistoryRequest.php file defines the ReplayHistoryRequest class, which serves as a Data Transfer Object (DTO) for fetching the transition history of a Finite State Machine (FSM) instance in a Laravel application. The class encapsulates the necessary parameters for retrieving the FSM transition history, such as the model class name, model ID, and column name. It implements validation logic to ensure that the parameters passed during instantiation meet specified requirements, making it a robust and reliable component of the FSM system.

Constructor

__construct

public function __construct(
    string|array $modelClass,
    string $modelId = '',
    string $columnName = '',
)

Purpose

The constructor initializes a new instance of the ReplayHistoryRequest class, either with an associative array of parameters or directly with positional string parameters. This method validates the input and ensures that the required fields are present and correctly formatted.

Parameters

• $modelClass (string|array): The name of the model class involved in the FSM transition. This can be passed either as a string or an associative array containing the keys modelClass, modelId, and columnName.

• $modelId (string): The unique identifier of the model instance. Default value is an empty string.

• $columnName (string): The name of the column that contains the state information for the FSM. Default value is an empty string.

Functionality

• If the $modelClass parameter is provided as an associative array, the constructor converts snake_case keys to camelCase and validates their presence.
• It checks if the class specified in modelClass exists and is a subclass of Laravel's Model class.
• If positional parameters are provided instead of an array, it also validates them similarly.
• Upon successful validation, it initializes the parent Dto class with the validated parameters.

If any required field is missing or invalid, an \InvalidArgumentException is thrown.

Validation Rules

rules

public static function rules(): array

Purpose

This method defines the validation rules for the parameters of the ReplayHistoryRequest instance. It returns an array containing the required validation criteria for each of the properties.

Return Value

• array<string, array<int, string|callable>>: An associative array where each key corresponds to a property of the class (modelClass, modelId, columnName) and each value is an array of validation rules for that property.

Functionality

• The method specifies that:
  • modelClass is required to be a non-empty string and must point to a valid class that is an Eloquent model.
  • modelId is required to be a non-empty string.
  • columnName is required to be a non-empty string.

The validation rules will be utilized by any service or controller that processes instances of ReplayHistoryRequest, ensuring that any data fetched from the database adheres to the expected schema.

By following this documentation, developers will have a clear understanding of how to utilize the ReplayHistoryRequest class and the validations enforced to maintain data integrity within the FSM framework.