<?php
/**
 * Extension Interface
 *
 * Defines the contract for Pro modules that extend Free module functionality.
 * This interface establishes a clear pattern for how Pro plugin features
 * should extend and enhance the Free plugin's modules.
 *
 * @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 ExtensionInterface
 *
 * Contract for Pro extension modules that enhance Free modules.
 * Provides a standardized way for Pro features to hook into
 * and extend Free module functionality without tight coupling.
 *
 * Design principles:
 * - Pro extensions should NEVER require modifying Free code
 * - Extensions use hooks/filters to add functionality
 * - Extensions can be enabled/disabled independently
 * - Extensions declare their base module dependency clearly
 *
 * Example implementation:
 * ```php
 * class SaltChangeProExtension implements ExtensionInterface {
 *     public static function getBaseModule(): string {
 *         return \WPUltimateSecurity\UltimateSecurity\Modules\Maintenance\SaltChange::class;
 *     }
 *
 *     public static function extend(): void {
 *         // Add scheduled salt changes
 *         add_filter('ultimate_security_handle_salt_change', [self::class, 'handleScheduled']);
 *
 *         // Add notification on salt change
 *         add_action('ultimate_security_after_salt_change', [self::class, 'sendNotification']);
 *
 *         // Add history tracking
 *         add_action('ultimate_security_after_salt_change', [self::class, 'logChange']);
 *     }
 *
 *     public static function isExtensionEnabled(): bool {
 *         return defined('ULTIMATE_SECURITY_PRO') &&
 *                class_exists(self::getBaseModule()) &&
 *                Settings::isEnabled('security.salt_change.pro_features');
 *     }
 * }
 * ```
 *
 * @since 2.0.0
 */
interface ExtensionInterface
{
    /**
     * Get the base module class that this extension enhances.
     *
     * Returns the fully-qualified class name of the Free module
     * that this Pro extension builds upon. Used for:
     * - Dependency checking
     * - Documentation
     * - Ensuring base module is loaded before extension
     *
     * @since 2.0.0
     *
     * @return string Fully-qualified class name of the base module.
     */
    public static function getBaseModule(): string;

    /**
     * Register extension hooks and filters.
     *
     * This method registers all hooks and filters that extend
     * the base module's functionality. Should use WordPress hooks
     * rather than direct class modifications.
     *
     * Guidelines:
     * - Use hooks defined in Config\Hooks class
     * - Check isExtensionEnabled() before registering hooks
     * - Prefer filters over direct function overrides
     * - Document what functionality each hook adds
     *
     * @since 2.0.0
     *
     * @return void
     */
    public static function extend(): void;

    /**
     * Check if this extension should be active.
     *
     * Determines whether the extension should register its hooks.
     * Should check:
     * - Pro plugin is active
     * - Base module exists and is enabled
     * - Extension-specific settings are enabled
     *
     * @since 2.0.0
     *
     * @return bool True if extension should be active.
     */
    public static function isExtensionEnabled(): bool;
}
