<?php
/**
 * Module With Settings Interface
 *
 * Extends ModuleInterface for modules that have configurable settings.
 * Provides methods for accessing and managing module-specific settings.
 *
 * @package     WPUltimateSecurity\UltimateSecurity\Contracts
 * @since       2.0.0
 * @author      Ultimate Security Team
 * @license     GPL-2.0-or-later
 */

declare(strict_types=1);

namespace WPUltimateSecurity\UltimateSecurity\Contracts;

/**
 * Interface ModuleWithSettingsInterface
 *
 * Contract for modules that have user-configurable settings.
 * Extends the base ModuleInterface with settings-specific methods.
 *
 * Example implementation:
 * ```php
 * class RateLimiterModule implements ModuleWithSettingsInterface {
 *     public static function getSettingsKey(): string {
 *         return 'security.rate_limiter';
 *     }
 *
 *     public static function getDefaultSettings(): array {
 *         return [
 *             'enable' => '0',
 *             'requests_per_minute' => 60,
 *             'block_duration' => 3600,
 *         ];
 *     }
 *
 *     public static function getSetting(string $key, mixed $default = null): mixed {
 *         $settings = Utils::ultimate_security_get_option(self::getSettingsKey(), []);
 *         return $settings[$key] ?? $default ?? self::getDefaultSettings()[$key] ?? null;
 *     }
 * }
 * ```
 *
 * @since 2.0.0
 */
interface ModuleWithSettingsInterface extends ModuleInterface
{
    /**
     * Get the settings key path for this module.
     *
     * Returns the dot-notation path to this module's settings
     * within the plugin's settings array.
     *
     * Example: 'security.rate_limiter' for rate limiter settings
     *
     * @since 2.0.0
     *
     * @return string The settings key path.
     */
    public static function getSettingsKey(): string;

    /**
     * Get the default settings for this module.
     *
     * Returns an array of default values for all module settings.
     * Used during installation and when settings are missing.
     *
     * @since 2.0.0
     *
     * @return array<string, mixed> Default settings array.
     */
    public static function getDefaultSettings(): array;

    /**
     * Get a specific setting value.
     *
     * Retrieves a single setting value with optional default fallback.
     *
     * @since 2.0.0
     *
     * @param string $key     The setting key within this module's settings.
     * @param mixed  $default Optional default value if setting not found.
     *
     * @return mixed The setting value or default.
     */
    public static function getSetting(string $key, mixed $default = null): mixed;
}
