<?php

declare(strict_types=1);

namespace App\Form\ParticipantFieldHandler;

use App\Form\Model\BookingCreateDto;

/**
 * Abstract base class providing common functionality for participant field handlers.
 *
 * This class implements common patterns used across participant field handlers,
 * including default implementations for field state modification methods.
 * Reduces boilerplate code in concrete implementations.
 */
abstract class AbstractParticipantFieldHandler implements ParticipantFieldHandlerInterface
{
    /**
     * Returns the field names this handler depends on.
     *
     * Default implementation returns an empty array, meaning no dependencies.
     * Override this method in concrete handlers that depend on other fields
     * being processed first (e.g., a meal preference handler might depend on
     * the room assignment being processed first).
     *
     * @return string[] Array of field names that must be processed before this handler
     */
    public function getDependencies(): array
    {
        return [];
    }

    /**
     * Determines if this handler should process the field based on submitted data.
     *
     * Default implementation checks if the field exists in the submitted data.
     * Override this method for more complex processing conditions (e.g., only
     * process if certain other conditions are met).
     *
     * @param array<string, mixed> $submittedData    The submitted participant form data
     * @param int                  $participantIndex The index of the participant being processed
     *
     * @return bool True if the handler should process this field, false otherwise
     */
    public function shouldProcess(array $submittedData, int $participantIndex): bool
    {
        return isset($submittedData[$this->getFieldName()]);
    }

    /**
     * Safely retrieves a participant object from the booking DTO.
     *
     * This helper method provides safe access to participant data by checking
     * if the participant exists at the given index. Returns null if the
     * participant doesn't exist, preventing array access errors.
     *
     * @param BookingCreateDto $bookingDto       The booking DTO containing participants
     * @param int              $participantIndex The index of the participant to retrieve
     *
     * @return object|null The participant object, or null if not found
     */
    protected function getParticipant(BookingCreateDto $bookingDto, int $participantIndex): ?object
    {
        return $bookingDto->participants[$participantIndex] ?? null;
    }

    /**
     * Safely extracts a field value from submitted participant data.
     *
     * This helper method provides safe access to form field values using
     * the null coalescing operator. Useful for extracting field values
     * without worrying about undefined array keys.
     *
     * @param array<string, mixed> $submittedData The submitted participant form data
     * @param string               $fieldName     The name of the field to retrieve
     * @param mixed                $default       The default value to return if field is not set
     *
     * @return mixed The field value, or the default value if not found
     */
    protected function getFieldValue(array $submittedData, string $fieldName, mixed $default = null): mixed
    {
        return $submittedData[$fieldName] ?? $default;
    }

    /**
     * Normalizes empty string values to null.
     *
     * Form inputs often submit empty strings for unselected/empty fields.
     * This helper converts those empty strings to null values, which is
     * typically more appropriate for database storage and business logic.
     *
     * @param mixed $value The value to normalize
     *
     * @return mixed The normalized value (null if empty, original value otherwise)
     */
    protected function normalizeEmptyValue(mixed $value): mixed
    {
        return empty($value) ? null : $value;
    }

    /**
     * Converts and normalizes string values to integers.
     *
     * Form inputs submit all values as strings. This helper safely converts
     * string values to integers while handling empty strings and non-numeric
     * values gracefully by returning null.
     *
     * @param mixed $value The value to convert to integer
     *
     * @return int|null The integer value, or null if empty/non-numeric
     */
    protected function normalizeIntValue(mixed $value): ?int
    {
        if (empty($value)) {
            return null;
        }

        return is_numeric($value) ? (int) $value : null;
    }

    /**
     * Returns field state modifications that should be applied after processing.
     *
     * Default implementation returns no state modifications. Override this method
     * in concrete handlers that need to modify field states based on their
     * processing results.
     *
     * @param array<string, mixed> $submittedData    The submitted participant form data
     * @param BookingCreateDto     $bookingDto       The booking DTO (potentially modified by processing)
     * @param int                  $participantIndex The participant index being processed
     *
     * @return array<string, array<string, mixed>> Empty array (no state modifications by default)
     */
    public function getFieldStateModifications(array $submittedData, BookingCreateDto $bookingDto, int $participantIndex): array
    {
        return [];
    }

    /**
     * Returns field names whose state is affected by this handler's processing.
     *
     * Default implementation returns an empty array, meaning this handler doesn't
     * affect the state of any fields. Override this method in concrete handlers
     * that modify field states.
     *
     * @return string[] Empty array (no affected fields by default)
     */
    public function getAffectedFieldNames(): array
    {
        return [];
    }
}