<?php
/**
 * Form Handler Interface
 *
 * This interface defines the contract that all form handler classes must implement
 * to provide OTP verification functionality for various WordPress forms.
 *
 * @package miniorange-sms-order-notification-otp-verification/objects
 */

namespace WCSMSOTP\Objects;

if ( ! defined( 'ABSPATH' ) ) {
	exit; // Exit if accessed directly.
}

/**
 * Form Handler Interface
 *
 * This interface defines the contract that all form handler classes must implement
 * to provide OTP verification functionality for various WordPress forms.
 */
interface IFormHandler {


	/**
	 * Unset OTP session variables.
	 *
	 * Clears all OTP-related session variables when verification is complete or cancelled.
	 *
	 * @return void
	 */
	public function unset_otp_session_variables();

	/**
	 * This function hooks into the otp_verification_successful hook. This function
	 * defines what needs to be done if OTP Verification is successful.
	 *
	 * @param string $redirect_to the redirect to URL after new user registration.
	 * @param string $user_login the username posted by the user.
	 * @param string $user_email the email posted by the user.
	 * @param string $password the password posted by the user.
	 * @param string $phone_number the phone number posted by the user.
	 * @param string $extra_data any extra data posted by the user.
	 * @param string $otp_type the verification type.
	 * @return void
	 */
	public function handle_post_verification( $redirect_to, $user_login, $user_email, $password, $phone_number, $extra_data, $otp_type );

	/**
	 * This function hooks into the otp_verification_failed hook. This function
	 * details what is done if the OTP verification fails.
	 *
	 * @param string|array $user_login the username posted by the user.
	 * @param string|array $user_email the email posted by the user.
	 * @param string|array $phone_number the phone number posted by the user.
	 * @param string|array $otp_type the verification type.
	 * @return void
	 */
	public function handle_failed_verification( $user_login, $user_email, $phone_number, $otp_type );

	/**
	 * Function checks if form has been enabled by the admin and initializes
	 * all the class variables. This function also defines all the hooks to
	 * hook into to make OTP Verification possible.
	 *
	 * @throws \ReflectionException If reflection fails during initialization.
	 * @return void
	 */
	public function handle_form();

	/**
	 * Handles saving all the Form related options by the admin.
	 *
	 * @return void
	 */
	public function handle_form_options();

	/**
	 * This function is called by the filter mo_phone_dropdown_selector
	 * to return the Jquery selector of the phone field. The function will
	 * push the formID to the selector array if OTP Verification for the
	 * form has been enabled.
	 *
	 * @param  array $selector - the Jquery selector to be modified.
	 * @return array
	 */
	public function get_phone_number_selector( $selector );

	/**
	 * Check if the form is a login or social login form.
	 *
	 * @param bool $is_login_or_social_form Whether the form is a login or social form.
	 * @return bool Whether the form is a login or social form.
	 */
	public function is_login_or_social_form( $is_login_or_social_form );

	/**
	 * Check if the form is an AJAX form.
	 *
	 * This function is called by the filter is_ajax_form to check if OTP Verification
	 * has started for this form and if it's an Ajax form.
	 *
	 * @param bool $is_ajax Whether the form is an AJAX form.
	 * @return bool Whether the form is an AJAX form.
	 */
	public function is_ajax_form_in_play( $is_ajax );

	/**
	 * Get the phone HTML tag.
	 *
	 * @return string The phone HTML tag.
	 */
	public function get_phone_html_tag();

	/**
	 * Get the email HTML tag.
	 *
	 * @return string The email HTML tag.
	 */
	public function get_email_html_tag();

	/**
	 * Get the phone and email HTML tag.
	 *
	 * @return string The phone and email HTML tag.
	 */
	public function get_both_html_tag();

	/**
	 * Get the form key.
	 *
	 * @return string The form key identifier.
	 */
	public function get_form_key();

	/**
	 * Get the form name.
	 *
	 * @return string The form name.
	 */
	public function get_form_name();

	/**
	 * Check which OTP type is enabled.
	 *
	 * @return string The enabled OTP type.
	 */
	public function get_otp_type_enabled();

	/**
	 * Check if auto activation is disabled.
	 *
	 * @return bool Whether auto activation is disabled.
	 */
	public function disable_auto_activation();

	/**
	 * Get phone key details.
	 *
	 * @return string The phone key details.
	 */
	public function get_phone_key_details();

	/**
	 * Check if form is enabled.
	 *
	 * @return bool Whether the form is enabled.
	 */
	public function is_form_enabled();

	/**
	 * Get email key details.
	 *
	 * @return string The email key details.
	 */
	public function get_email_key_details();

	/**
	 * Get button texts.
	 *
	 * @return string The button text.
	 */
	public function get_button_text();

	/**
	 * Get form details.
	 *
	 * @return array The form details.
	 */
	public function get_form_details();

	/**
	 * Get verification type.
	 *
	 * @return string|false The verification type or false if not set.
	 */
	public function get_verification_type();

	/**
	 * Get form documents.
	 *
	 * @return array The form documents array.
	 */
	public function get_form_documents();
}
