Documentation: FsmServiceProvider.php

Original file: src/Fsm/FsmServiceProvider.php

FsmServiceProvider Documentation

Table of Contents

• Introduction
• Methods
  • register
  • boot
  • generateMigrationName
  • registerEventListeners

Introduction

The FsmServiceProvider is an essential component of the finite state machine (FSM) functionality within a Laravel application. This service provider is responsible for registering various services, commands, and configurations pertinent to the FSM package. It serves as the central hub for initializing the FSM services during the bootstrapping process of the Laravel application, ensuring that dependencies are appropriately managed and configuration files are published.

Methods

register

public function register(): void

Purpose: The register method is responsible for binding various services and classes into the Laravel service container. This method ensures that all necessary components of the FSM are available for dependency injection throughout the application.

Parameters:

• This method does not accept any parameters.

Return Values:

• This method does not return any value.

Functionality:

• Merges the FSM configuration file located at ../../config/fsm.php into the application's configuration files under the 'fsm' key.
• Registers the following services as singletons:
  • Services\BootstrapDetector
  • FsmRegistry, initialized with dependencies from the application’s Config\Repository.
  • FsmEngineService, initialized with dependencies including FsmRegistry, FsmLogger, and FsmMetricsService, among others.
  • Services\FsmMetricsService and Services\FsmLogger, which depend on the application's event dispatcher and configuration repository respectively.
  • Guards\PolicyGuard, initialized with the application's authorization Gate.
  • FsmExtensionRegistry, using the configuration repository.
  • Services\FsmReplayService which may have its own initialization logic in the future.

boot

public function boot(): void

Purpose: The boot method is invoked after all services have been registered. It is used to perform actions such as publishing configuration files, running migrations, and registering console commands, which should only occur once all dependencies are in place.

Parameters:

• This method does not accept any parameters.

Return Values:

• This method does not return any value.

Functionality:

• Publishes the configuration file fsm.php to config_path('fsm.php') using the tag 'fsm-config'.
• If the application is running in console mode, it publishes migration files to the designated migrations directory and registers console commands: FsmDiagramCommand and FsmCacheCommand.
• If not in the testing environment, it will initiate the discovery of FSM definitions via the FsmRegistry.
• Registers event listeners for FSM event logging if enabled in the application configuration.

generateMigrationName

protected function generateMigrationName(string $migrationName, ?string $path = null): string

Purpose: Creates a migration file name with a current timestamp, ensuring unique naming to avoid collisions.

Parameters:

• string $migrationName: The base name for the migration file.
• ?string $path: Optional. The directory path where migration files are stored. Defaults to the standard Laravel migrations directory.

Return Values:

• Returns a string that represents the full path to the unique migration file name.

Functionality:

• Checks if a migration file with the same base name already exists in the provided path.
• If an existing file is found, returns the name of that file.
• If no existing file is found, constructs a new migration file name using the current timestamp and the provided base name.

registerEventListeners

protected function registerEventListeners(): void

Purpose: Registers event listeners for FSM events, conditionally based on the configuration settings regarding event logging.

Parameters:

• This method does not accept any parameters.

Return Values:

• This method does not return any value.

Functionality:

• It retrieves the configuration for event logging.
• If auto-registering of listeners is enabled, it listens for the Events\StateTransitioned event and ties it to the Listeners\PersistStateTransitionedEvent class. This helps in automating logging or handling actions triggered by state transitions within the FSM.

This documentation serves as a comprehensive guide to understanding the FsmServiceProvider, its methods and the role they play in the overall functioning of the FSM package within your Laravel application. Developers should utilize this resource to grasp how dependencies are managed and configured, ensuring smooth integration and extensibility within their own projects.