Validation for State Machine Configuration Structure

[deligoez]

Introduces strict validation for state machine configurations through the new StateConfigValidator class, ensuring consistency and early error detection.

Key Changes

• Add validation for root-level machine configuration
• Validate state properties and transitions
• Enforce proper structure for guards and actions
• Improve error messages for configuration issues

Example usage in machine definitions:

MachineDefinition::define([
    'id' => 'order',
    'initial' => 'pending',
    'states' => [
        'pending' => [
            'on' => {
                'APPROVE' => [
                    'target' => 'approved',
                    'guards' => 'isValid'  // Now validated
                ]
            }
        ]
    ]
]);

The validator checks for:

• Valid keys at each configuration level
• Proper structure for transitions and guards
• Correct state type definitions
• Valid entry/exit actions format

Any configuration issues now throw InvalidArgumentException with clear error messages, helping developers catch problems early in development rather than at runtime. For example:

// Invalid configuration - will throw exception
MachineDefinition::define([
    'states' => [
        'pending' => [
            'invalid_key' => 'value',  // Invalid state key
            'on' => [
                '@always' => 'next'    // Must be under 'on'
            ]
        ]
    ]
]);

This enhancement improves developer experience by providing immediate feedback on configuration errors and enforcing consistent machine definitions across your application.