WordPress OTP Verification Plugin Developer Guide

The purpose of this guide is to list all the Hooks and Filters available in the plugin and provide a step by step guide on how to integrate forms or modify functionality of the plugin.

Email Verification / SMS Verification / OTP Verification

FORM INTEGRATION GUIDE

STEP 1. SET A SESSION VARIABLE

Set a session variable indicating that the OTP Verification has started for your form.

$_SESSION['<your_session_variable>'] = 'started';

STEP 2. DOES THE FORM DO AJAX CALLS?

Add the following filter to denote if you current form submits the form using an AJAX call. The function should check if otp verification has been started for a form and if that form makes an AJAX call. Should return TRUE or FALSE.

add_filter( 'is_ajax_form', array($this,'is_ajax_form_in_play'), 1,1);

public function is_ajax_form_in_play($isAjax){

     // Check if there's an active session.

     if (session_id() == '' || !isset($_SESSION)) session_start();

     // If the current form makes an AJAX call to submit the form

     return isset($_SESSION['<your_session_variable>']) ? TRUE : $isAjax; 

     //If the current form makes an AJAX call to submit the form

     return isset($_SESSION['<your_session_variable>']) ? FALSE : $isAjax;

}

STEP 3. ADD CODE TO INITIATE OTP VERIFICATION

// For Phone/Mobile Verification
do_action('mo_generate_otp',NULL,NULL,NULL, $phone_number,”phone”, NULL,NULL,NULL);

// For Email Verification
do_action('mo_generate_otp',NULL,$email,NULL, NULL,”email”, NULL,NULL,NULL);

STEP 4. ADD CODE TO VALIDATE THE OTP ( FOR AJAX FORMS )

Add the following code only if you are integrating with an AJAX form to validate the OTP entered by the user after form submission.

do_action('mo_validate_otp',NULL,$otpEnteredByUser);

STEP 5. ADD ACTION TO HANDLE SUCCESSFUL VALIDATION

Use the following action hook to determine what needs to be done after user has successfully validated the OTP sent to his phone or email.

add_action( 'otp_verification_successful',array($this,'handle_post_verification'),10,6);

function handle_post_verification($redirect_to,$user_login,$user_email, $password,
                                  $phone_number,$extra_data){

    // Check if there's an active session.

    if (session_id() == '' || !isset($_SESSION)) session_start();

    // return if otp verification was not started

    if(!isset($_SESSION['<your_session_variable>'])) return;

    //enter your code below to process the form submitted

    .

    .

    .

}

STEP 6. ADD ACTION TO HANDLE FAILED VALIDATION

Use the following action hook to determine what needs to be done after user has fails to validate the OTP sent to his phone or email. Either the user has entered an invalid OTP or there was some other error.

add_action( 'otp_verification_failed',array($this,'handle_failed_verification'),10,3);

function handle_failed_verification($user_login,$user_email,$phone_number){

    // Check if there's an active session.

    if (session_id() == '' || !isset($_SESSION)) session_start();

    // return if otp verification was not started

    if(!isset($_SESSION['<your_session_variable>'])) return;

    // this action is called to unset the session variable
    do_action('unset_session_variable'); 

    // enter your code below to process the failed validation

    .

    .

    .

}

STEP 7. ADD ACTION TO UNSET SESSION VARIABLES

Use the following action hook to unset the session variables you had set earlier. This is important because this is called from a variety of places by the plugin to unset session variables.

add_action( 'unset_session_variable', array( $this, 'unsetSessionVariables'), 1, 0);

public function unsetSessionVariables(){

    unset($_SESSION['mo_customer_validation_site_txID']);

    unset($_SESSION['<your_session_variable>']);

}

PLUGIN HOOKS AND FILTERS

ACTIONS

>> otp_verification_successful

/**
 * This hook is triggered after OTP entered by the user is validated successfully. 
 * Use this hook to modify/decide the functionality after user has entered the 
 * correct OTP and the system has validated it successfully. 
 * @param $redirect_to  the redirect to URL after new user registration
 * @param $user_login   the username posted by the user
 * @param $user_email   the email posted by the user
 * @param $password     the password posted by the user 
 * @param $phone_number the phone number posted by the user
 * @param $extra_data   any extra data posted by the user  
 */
 add_action( 
    'otp_verification_successful', 
    function ($redirect_to,$user_login,$user_email,$password,$phone_number,$extra_data){
       // your code goes here 
    },10,6
 );

>> otp_verification_failed

/** 
 * This hook is triggered after OTP entered by the user is validated successfully.  
 * Use this hook to modify/decide the functionality after user has entered the 
 * wrong OTP and the system has validated it successfully.  
 * @param $user_login   the username posted by the user 
 * @param $user_email   the email posted by the user 
 * @param $phone_number the phone number posted by the user 
 */
 add_action( 
    'otp_verification_failed',
    function handle_failed_verification($user_login,$user_email,$phone_number){
       //your code goes here
    },10,3
 );

>> unset_session_variable

/**
 * This hook is triggered to unset all the session variables so that a 
 * new form submission starts a fresh process of OTP verification. 
 * Use this hook to modify or add your own code for clear user activity
 * from session. 
 */
 add_action( 
    'unset_session_variable',
    function(){
       // your code goes here
    }
 );

>> mo_registration_show_message

/**
 * The hook is triggered to show a plugin generated message to the user in 
 * the admin dashboard. Use this hook to modify the messages being shown 
 * to the user in the admin dashboard.
 * @param $content refers to the message content
 * @param $type    refers to the type of message
 */
 add_action( 
    'mo_registration_show_message',
    function($content,$type) {
        // your code here
    },10,2
 );

>> mo_generate_otp

/**
 * This hook is triggered to start the OTP Verification process. 
 * Use this hook to modify the process of sending OTP to a 
 * user's phone or email address. You can even call this hook to
 * initiate an OTP request to a user's phone or email of your own.
 * @param string    $user_login    username submitted by the user
 * @param string    $user_email    email submitted by the user
 * @param string    $errors        error variable ( currently not being used )
 * @param string    $phone_number  phone number submitted by the user
 * @param string    $otp_type      email or sms verification
 * @param string    $password      password submitted by the user
 * @param string    $extra_data    an array containing all the extra data submitted by the user
 * @param bool      $from_both     denotes if user has a choice between email and phone verification
 */
 add_action(
    'mo_generate_otp',
    function($user_login, $user_email, $errors, $phone_number = "",
             $otp_type="email",$password = '', $extra_data = null, $from_both = false){
        // your code goes here
    }, 1,8
 );

>> mo_validate_otp

/**
 * This hook is triggered to start the OTP Verification validation process. 
 * Use this hook to modify the process of validating the OTP Token submitted
 * by the user. You can even initiated this action to validate an OTP 
 * submitted by the user.
 * @param string $requestVariable   the otp token key in the post parameter
 * @param string $otp_token         otp token submitted
 */
 add_action(
    'mo_validate_otp',
    function($requestVariable,$otp_token){
       // your code goes here
    },1,8
 );

>> mo_otp_verification_add_on_controller

/**
 * This hook is triggered to show add-on settings. If you want to build a 
 * custom add-on then use this hook to control the data & view shown by 
 * your add-on.
 */
 add_action( 
    'mo_otp_verification_add_on_controller',
    function(){
        // your code goes here
    }
 );

>> mo_otp_verification_delete_addon_options

/**
 * This hook is triggered to delete add-on settings. If you want to build a 
 * custom add-on then use this hook to trigger your add-on settings to be 
 * deleted when the plugin is deleted.
 */
 add_action( 
    'mo_otp_verification_delete_addon_options',
    function(){
       // your code goes here
    }
 );

 

FILTERS

>> get_mo_option

/**
 * This filter is applied on each value coming from the database. 
 * Hook into this filter to modify the values coming from the database. 
 * @param  $key    the option_name to fetch the value from the database
 * @param  $prefix the string value to be prefixed to the option_name before fetching data
 * @return String
 */
 add_filter(
    'get_mo_option', 
    function($key,$prefix) {
       // your code goes here
       // return a value from database
    },10,2
 );

>> update_mo_option

/**  
 * This filter is applied on each value before it's put in the database. 
 * Hook into this filter to modify the values before they are saved in the 
 * WordPress database.
 * @param $key    the option_name to fetch the value from the database
 * @param $value  the value to be saved in the database
 * @param $prefix the string value to be prefixed to the option_name before fetching data
 * @return String
 */ 
 add_filter(
    'update_mo_option', 
    function($key,$value,$prefix) { 
       // your code goes here
       // return a value from database
    },10,3
 );

>> mo_phone_dropdown_selector

/**
 * A filter to modify the array of jQuery selectors to show the 
 * phone field drop-down on. Hook into this filter to modify or 
 * your own form's phone field as a selector to show the country
 * drop-down on.
 * @param  array $selector array of jQuery selectors
 * @return array
 */
 add_filter( 
    'mo_phone_dropdown_selector', 
    function($selector){
        // your code goes here
        // return $selector
    },10,1
 );

>> mo_template_defaults

/**
 * This filter is triggered before each default pop-up template is saved in the
 * plugin. Hook into this filter to modify the default pop-up template before 
 * they are saved in the database.
 * @param  array $templates a key value pair array consisting of all the HTML templates for the pop-ups
 * @return array
 */
 add_filter( 
    'mo_template_defaults', 
    function($templates) {
        // your code goes here
        // return $templates
    }
 );
>> mo_template_build
/**
 * This filter is triggered to build each pop-up template and replace the 
 * tags with HTML code before showing it on the screen to the users. 
 * Hook into this filter to modify or add your own content to the pop-ups.
 * Return the HTML content for the particular pop-up.
 * @param $template     the template content to be modified
 * @param $templateType the template type
 * @param $message      the message to be shown in the popup
 * @param $otp_type     the otp type invoked
 * @param $from_both    does user have the option to choose b/w email and sms verification
 * @return String
 */
 add_filter( 
    'mo_template_build',
    function($template,$templateType,$message,$otp_type,$from_both){
       // your code goes here
       // return HTML content
    },1,5
 );

>> mo_blocked_email_domains

/**
 * Hook into this filter to modify the blocked email domains list.
 * This filter is called before an attempt to send an OTP to the user's 
 * email address to check if the email entered has been blacklisted 
 * by the admin of the site.
 * @param array $blocked_email_domains a list of blocked email domains
 * @return array
 */
 add_filter( 
    'mo_blocked_email_domains', 
    function($blocked_email_domains) {
        // your code goes here
        // return $blocked_email_domains
    },10,1
 );

>> mo_blocked_phones

/**
 * Hook into this filter to modify the blocked phone number list.
 * This filter is called before an attempt to send an OTP to the user's 
 * phone to check if the phone number has been blacklisted 
 * by the admin of the site. Make sure that the phone number is in the
 * international format e.g: +1xxxxxxxxx
 * @param  array $blocked_phones a list of blocked email domains
 * @return array
 */
 add_filter( 
    'mo_blocked_phones', 
    function($blocked_phones) {
      // your code goes here
      // return $blocked_phones
    },10,1
 );

>> mo_filter_phone_before_api_call

/**
 * This filter is called before the phone number is passed to the 
 * Gateway API to send an OTP message to the user. Hook into this 
 * filter to make any modifications to the phone number before it 
 * is sent to the SMS Gateway for OTP delivery. 
 * @param  String $phone the phone number to be processed
 * @return String
 * 
 * @note This filter is only available for the Your Gateway Plan
 */
 add_filter(
    'mo_filter_phone_before_api_call', 
    function($phone_number){
       // your code goes here
       // return $phone_number
    },10,1
 );

>> customize_otp_url_before_api_call

/**
 * This filter is called before the API call is made to send an OTP message 
 * to the user. Hook into this filter to make any modifications to the URL 
 * before it is used to make the API call.
 * @param  String $url     the SMS Gateway URL
 * @param  String $message the OTP message to be sent to the user's phone
 * @param  String $phone   the phone number to be processed
 * @return String
 * 
 * @note This filter is only available for the Your Gateway Plan
 */
 add_filter(
    'customize_otp_url_before_api_call', 
    function($url,$message,$phone){
       // your code goes here
       // return $url
    },10,3
  );

>> mo_process_phone

/**
 * This filter is called to process the phone number immediately after form
 * submission. Hook into this filter if you want to modify the phone
 * number before it is processed by the form and the plugin.
 * @param  String $phone the phone number to be processed
 * @return String
 */
 add_filter(
    'mo_process_phone', 
    function($phone){
        // your code goes here
        // return $phone
    },10,1
 );

>> is_ajax_form

/**
 * This filter is called to check if the current form that the user
 * is initiating OTP Verification for makes an AJAX call for submission
 * or not. Hook into this filter to add your own form's data or modify
 * existing form's data during OTP Verification process. 
 * @param  bool $isAjax True or False value 
 * @return bool
 */
 add_filter(
    'is_ajax_form', 
    function($isAjax){
       // your code goes here
       // return $isAjax
    },10,1
 );

>> is_login_or_social_form

/**
 * This filter is called to check if the current form that the user
 * is initiating OTP Verification for is a login or social login form
 * or not. Hook into this filter to add your own form's data or modify
 * existing form's data during OTP Verification process. 
 * @param  bool $isLoginOrSocialForm True or False value 
 * @return bool
 */
 add_filter(
    'is_login_or_social_form', 
    function($isLoginOrSocialForm){
       // your code goes here
       // return $isAjax
    },10,1
 );

>> mo_curl_page_url

/**
 * This filter is called to modify the current page URL. This filter
 * is called during the OTP Verification process to keep track of the page
 * where user initiated OTP Verification for. User is redirected back to this
 * page when he clicks on the Go Back button on the OTP pop-up page.
 * Hook into this filter to modify the current page URL.
 * @param  String $pageURL the current page URL
 * @return String
 */ 
 add_filter(
    'mo_curl_page_url', 
    function($pageURL){
      // your code goes here
      // return $pageURL
    },10,1
 );