<?php
/**
 * Standard Hook Names
 *
 * Centralized definition of all hook names used by the plugin.
 * Using constants ensures consistency and enables IDE autocompletion.
 *
 * @package     WPUltimateSecurity\UltimateSecurity\Config
 * @since       2.0.0
 * @author      Ultimate Security Team
 * @license     GPL-2.0-or-later
 */

declare(strict_types=1);

namespace WPUltimateSecurity\UltimateSecurity\Config;

/**
 * Hook name constants.
 *
 * All action and filter hook names used by Ultimate Security.
 * Pro plugin should use these constants to hook into Free plugin functionality.
 *
 * Naming conventions:
 * - Actions: ultimate_security_{when}_{what}
 * - Filters: ultimate_security_filter_{what} or ultimate_security_{what}
 *
 * Example usage:
 * ```php
 * use WPUltimateSecurity\UltimateSecurity\Config\Hooks;
 *
 * // In Free plugin - fire an action
 * do_action(Hooks::AFTER_SALT_CHANGE, $result);
 *
 * // In Pro plugin - hook into the action
 * add_action(Hooks::AFTER_SALT_CHANGE, [self::class, 'logSaltChange']);
 * ```
 *
 * @since 2.0.0
 */
final class Hooks
{
    // =========================================================================
    // PLUGIN LIFECYCLE HOOKS
    // =========================================================================

    /**
     * Fires when the plugin has fully loaded.
     *
     * @since 2.0.0
     */
    public const PLUGIN_LOADED = 'ultimate_security_loaded';

    /**
     * Fires after all modules have been registered.
     *
     * @since 2.0.0
     */
    public const MODULES_REGISTERED = 'ultimate_security_modules_registered';

    /**
     * Fires during plugin activation.
     *
     * @since 2.0.0
     */
    public const PLUGIN_ACTIVATED = 'ultimate_security_activated';

    /**
     * Fires during plugin deactivation.
     *
     * @since 2.0.0
     */
    public const PLUGIN_DEACTIVATED = 'ultimate_security_deactivated';

    // =========================================================================
    // MODULE LIFECYCLE HOOKS
    // =========================================================================

    /**
     * Fires after a module is registered.
     *
     * @since 2.0.0
     * @param string $identifier Module identifier.
     * @param string $class      Module class name.
     */
    public const MODULE_REGISTERED = 'ultimate_security_module_registered';

    /**
     * Fires when a module is skipped (disabled).
     *
     * @since 2.0.0
     * @param string $identifier Module identifier.
     */
    public const MODULE_SKIPPED = 'ultimate_security_module_skipped';

    // =========================================================================
    // AUTHENTICATION HOOKS
    // =========================================================================

    /**
     * Fires before 2FA validation.
     *
     * @since 2.0.0
     * @param WP_User $user     The user being validated.
     * @param string  $provider The 2FA provider being used.
     */
    public const BEFORE_2FA_VALIDATE = 'ultimate_security_before_2fa_validate';

    /**
     * Fires after successful 2FA validation.
     *
     * @since 2.0.0
     * @param WP_User $user     The authenticated user.
     * @param string  $provider The 2FA provider used.
     */
    public const AFTER_2FA_VALIDATED = 'ultimate_security_2fa_validated';

    /**
     * Fires when 2FA validation fails.
     *
     * @since 2.0.0
     * @param WP_User $user     The user.
     * @param string  $provider The 2FA provider.
     * @param string  $reason   Failure reason.
     */
    public const TWO_FA_FAILED = 'ultimate_security_2fa_failed';

    /**
     * Filter to modify available 2FA providers.
     *
     * @since 2.0.0
     * @param array $providers Array of provider class names.
     * @return array Modified providers array.
     */
    public const FILTER_TWO_FA_PROVIDERS = 'ultimate_security_2fa_providers';

    /**
     * Fires when a login is blocked.
     *
     * @since 2.0.0
     * @param string $username The username.
     * @param string $reason   Block reason.
     * @param string $ip       Client IP address.
     */
    public const LOGIN_BLOCKED = 'ultimate_security_login_blocked';

    /**
     * Fires after successful login.
     *
     * @since 2.0.0
     * @param WP_User $user The logged in user.
     */
    public const LOGIN_SUCCESS = 'ultimate_security_login_success';

    /**
     * Fires after failed login attempt.
     *
     * @since 2.0.0
     * @param string $username The username attempted.
     * @param string $ip       Client IP address.
     */
    public const LOGIN_FAILED = 'ultimate_security_login_failed';

    // =========================================================================
    // SECURITY FEATURE HOOKS
    // =========================================================================

    /**
     * Fires before salt keys are changed.
     *
     * @since 2.0.0
     */
    public const BEFORE_SALT_CHANGE = 'ultimate_security_before_salt_change';

    /**
     * Fires after salt keys are changed.
     *
     * @since 2.0.0
     * @param array $result Result of the salt change operation.
     */
    public const AFTER_SALT_CHANGE = 'ultimate_security_after_salt_change';

    /**
     * Filter to handle salt change (allows Pro to override).
     *
     * @since 2.0.0
     * @param false|array $result Return array to skip default handling.
     * @return false|array
     */
    public const FILTER_HANDLE_SALT_CHANGE = 'ultimate_security_handle_salt_change';

    /**
     * Fires when a request is blocked by URL Guard.
     *
     * @since 2.0.0
     * @param array $request_data Request details.
     */
    public const URL_GUARD_BLOCKED = 'ultimate_security_urlguard_blocked';

    /**
     * Filter URL Guard block types.
     *
     * @since 2.0.0
     * @param array $types Block type configuration.
     * @return array
     */
    public const FILTER_URL_GUARD_TYPES = 'ultimate_security_urlguard_block_types';

    /**
     * Fires when rate limit is exceeded.
     *
     * @since 2.0.0
     * @param string $ip      Client IP address.
     * @param string $context Rate limit context.
     */
    public const RATE_LIMIT_EXCEEDED = 'ultimate_security_rate_limit_exceeded';

    /**
     * Fires when IP is blocked/restricted.
     *
     * @since 2.0.0
     * @param string $ip     The blocked IP.
     * @param string $reason Block reason.
     */
    public const IP_BLOCKED = 'ultimate_security_ip_blocked';

    /**
     * Filter IP whitelist.
     *
     * @since 2.0.0
     * @param array $whitelist Array of whitelisted IPs.
     * @return array
     */
    public const FILTER_IP_WHITELIST = 'ultimate_security_ip_whitelist';

    /**
     * Filter IP blacklist.
     *
     * @since 2.0.0
     * @param array $blacklist Array of blacklisted IPs.
     * @return array
     */
    public const FILTER_IP_BLACKLIST = 'ultimate_security_ip_blacklist';

    // =========================================================================
    // SETTINGS HOOKS
    // =========================================================================

    /**
     * Fires after settings are updated.
     *
     * @since 2.0.0
     * @param array $old_settings Previous settings.
     * @param array $new_settings Updated settings.
     */
    public const SETTINGS_UPDATED = 'ultimate_security_settings_updated';

    /**
     * Fires when a specific module's settings are saved.
     *
     * @since 2.0.0
     * @param string $module   Module identifier.
     * @param array  $settings The saved settings.
     */
    public const MODULE_SETTINGS_SAVED = 'ultimate_security_module_settings_saved';

    /**
     * Filter default options.
     *
     * @since 2.0.0
     * @param array $defaults Default options array.
     * @return array
     */
    public const FILTER_DEFAULT_OPTIONS = 'ultimate_security_default_options';

    /**
     * Filter settings before save.
     *
     * @since 2.0.0
     * @param array $settings Settings to be saved.
     * @return array
     */
    public const FILTER_SETTINGS_BEFORE_SAVE = 'ultimate_security_settings_before_save';

    // =========================================================================
    // UI/ADMIN HOOKS
    // =========================================================================

    /**
     * Filter admin menu items.
     *
     * @since 2.0.0
     * @param array $items Menu items array.
     * @return array
     */
    public const FILTER_MENU_ITEMS = 'ultimate_security_menu_items';

    /**
     * Filter settings sections (for admin pages).
     *
     * @since 2.0.0
     * @param array $sections Settings sections.
     * @return array
     */
    public const FILTER_SETTINGS_SECTIONS = 'ultimate_security_settings_sections';

    /**
     * Filter dashboard widgets.
     *
     * @since 2.0.0
     * @param array $widgets Dashboard widget configuration.
     * @return array
     */
    public const FILTER_DASHBOARD_WIDGETS = 'ultimate_security_dashboard_widgets';

    // =========================================================================
    // EVENT/LOGGING HOOKS
    // =========================================================================

    /**
     * Fires when a security event is logged.
     *
     * @since 2.0.0
     * @param string $event_type Event type identifier.
     * @param array  $data       Event data.
     */
    public const EVENT_LOGGED = 'ultimate_security_event_logged';

    /**
     * Filter event data before logging.
     *
     * @since 2.0.0
     * @param array  $data       Event data.
     * @param string $event_type Event type.
     * @return array
     */
    public const FILTER_EVENT_DATA = 'ultimate_security_filter_event_data';

    // =========================================================================
    // CAPABILITY/PERMISSION HOOKS
    // =========================================================================

    /**
     * Filter available capabilities.
     *
     * @since 2.0.0
     * @param array $capabilities Array of capability names.
     * @return array
     */
    public const FILTER_CAPABILITIES = 'ultimate_security_capabilities';

    /**
     * Filter role-capability mapping.
     *
     * @since 2.0.0
     * @param array $mapping Role => capabilities mapping.
     * @return array
     */
    public const FILTER_ROLE_CAPABILITIES = 'ultimate_security_role_capabilities';

    // =========================================================================
    // PRO EXTENSION HOOKS
    // =========================================================================

    /**
     * Fires to allow Pro extensions to register.
     *
     * @since 2.0.0
     */
    public const REGISTER_PRO_EXTENSIONS = 'ultimate_security_register_pro_extensions';

    /**
     * Filter to check if Pro is available.
     *
     * @since 2.0.0
     * @param bool $is_pro Whether Pro is active.
     * @return bool
     */
    public const FILTER_IS_PRO = 'ultimate_security_is_pro';

    /**
     * Filter Pro features list.
     *
     * @since 2.0.0
     * @param array $features Array of Pro feature identifiers.
     * @return array
     */
    public const FILTER_PRO_FEATURES = 'ultimate_security_pro_features';

    // =========================================================================
    // REST API HOOKS
    // =========================================================================

    /**
     * Fires before REST API response is sent.
     *
     * @since 2.0.0
     * @param WP_REST_Response $response The response object.
     * @param string           $endpoint The endpoint path.
     */
    public const BEFORE_REST_RESPONSE = 'ultimate_security_before_rest_response';

    /**
     * Filter REST API response data.
     *
     * @since 2.0.0
     * @param array  $data     Response data.
     * @param string $endpoint Endpoint path.
     * @return array
     */
    public const FILTER_REST_RESPONSE = 'ultimate_security_filter_rest_response';

    /**
     * Private constructor to prevent instantiation.
     */
    private function __construct()
    {
    }
}
