<?php

namespace WPUltimateSecurity\UltimateSecurity\Infrastructure\Settings;

/**
 * Settings Interface
 *
 * Defines the contract for settings repository implementations.
 * Provides a consistent API for accessing and modifying plugin settings.
 *
 * @package WPUltimateSecurity\UltimateSecurity\Infrastructure\Settings
 * @since 1.0.0
 */
interface SettingsInterface
{
    /**
     * Get a settings value by key.
     *
     * Supports dot notation for nested keys (e.g., 'security.2fa_authentication.enabled').
     *
     * @param string $key     The settings key to retrieve.
     * @param mixed  $default Default value if key doesn't exist.
     *
     * @return mixed The settings value or default.
     */
    public function get(string $key, mixed $default = null): mixed;

    /**
     * Set a settings value by key.
     *
     * Supports dot notation for nested keys (e.g., 'security.2fa_authentication.enabled').
     *
     * @param string $key   The settings key to set.
     * @param mixed  $value The value to set.
     *
     * @return bool True on success, false on failure.
     */
    public function set(string $key, mixed $value): bool;

    /**
     * Get all settings.
     *
     * Returns the complete settings array merged with defaults.
     *
     * @return array The complete settings array.
     */
    public function all(): array;

    /**
     * Refresh the settings cache.
     *
     * Forces a reload of settings from the database on next access.
     *
     * @return void
     */
    public function refresh(): void;
}
