<?php

declare(strict_types=1);

namespace SecurWP\Includes\Interfaces;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Interface for modules that expose settings to the global Settings page.
 *
 * Modules implementing this interface register their settings keys, defaults,
 * and validation rules so the SettingsService can aggregate them.
 *
 * @since 2.0.0
 */
interface SettingsProvider {

	/**
	 * Return the schema for settings owned by this provider.
	 *
	 * Each key maps to an array with:
	 *   - 'type'     => 'string'|'integer'|'boolean'|'email'
	 *   - 'default'  => mixed
	 *   - 'readonly' => bool (optional, defaults to false)
	 *
	 * @return array<string, array{type: string, default: mixed, readonly?: bool}>
	 */
	public function get_settings_schema(): array;

	/**
	 * Return current values for all settings owned by this provider.
	 *
	 * @return array<string, mixed>
	 */
	public function get_settings(): array;

	/**
	 * Persist validated settings. Only writable keys will be passed.
	 *
	 * @param array<string, mixed> $values Sanitized key-value pairs.
	 * @return bool True on success.
	 */
	public function save_settings( array $values ): bool;
}
