Merge pull request #817 from aslamdoctor/815-inline-docs-hooks

Fix inline documentation for hooks to follow WordPress Coding Standards

Author: masteradhoc

class-two-factor-core.php

@@ -240,6 +240,8 @@ private static function get_providers_classes( $providers ) {
 			/**
 			 * Filters the classname for a provider. The dynamic portion of the filter is the defined providers key.
 			 *
+			 * @since 0.9.0
+			 *
 			 * @param string $class The PHP Classname of the provider.
 			 * @param string $path  The provided provider path to be included.
 			 */
@@ -278,6 +280,8 @@ public static function get_providers() {
 		 * This lets third-parties either remove providers (such as Email), or
 		 * add their own providers (such as text message or Clef).
 		 *
+		 * @since 0.1-dev
+		 *
 		 * @param array $providers A key-value array where the key is the class name, and
 		 *                         the value is the path to the file containing the class.
 		 */
@@ -586,6 +590,8 @@ public static function get_enabled_providers_for_user( $user = null ) {
 		/**
 		 * Filter the enabled two-factor authentication providers for this user.
 		 *
+		 * @since 0.5.2
+		 *
 		 * @param array  $enabled_providers The enabled providers.
 		 * @param int    $user_id           The user ID.
 		 */
@@ -744,6 +750,8 @@ public static function get_primary_provider_for_user( $user = null ) {
 		/**
 		 * Filter the two-factor authentication provider used for this user.
 		 *
+		 * @since 0.2.0
+		 *
 		 * @param string $provider The provider currently being used.
 		 * @param int    $user_id  The user ID.
 		 */
@@ -863,6 +871,8 @@ public static function is_user_api_login_enabled( $user_id ) {
 		 * Allow or prevent logins without two-factor during
 		 * API requests such as XML-RPC and REST.
 		 *
+		 * @since 0.4.0
+		 *
 		 * @param boolean $enabled Whether the user can login via API requests.
 		 * @param integer $user_id User ID.
 		 */
@@ -1323,6 +1333,8 @@ public static function get_user_time_delay( $user ) {
 		/**
 		 * Filter the minimum time duration between two factor attempts.
 		 *
+		 * @since 0.8.0
+		 *
 		 * @param int $rate_limit The number of seconds between two factor attempts.
 		 */
 		$rate_limit = apply_filters( 'two_factor_rate_limit', 1 );
@@ -1334,6 +1346,8 @@ public static function get_user_time_delay( $user ) {
 			/**
 			 * Filter the maximum time duration a user may be locked out from retrying two factor authentications.
 			 *
+			 * @since 0.8.0
+			 *
 			 * @param int $max_rate_limit The maximum number of seconds a user might be locked out for. Default 15 minutes.
 			 */
 			$max_rate_limit = apply_filters( 'two_factor_max_rate_limit', 15 * MINUTE_IN_SECONDS );
@@ -1344,6 +1358,8 @@ public static function get_user_time_delay( $user ) {
 		/**
 		 * Filters the per-user time duration between two factor login attempts.
 		 *
+		 * @since 0.8.0
+		 *
 		 * @param int     $rate_limit The number of seconds between two factor attempts.
 		 * @param WP_User $user       The user attempting to login.
 		 */
@@ -1373,8 +1389,10 @@ public static function is_user_rate_limited( $user ) {
 		 * This allows for dedicated plugins to rate limit two factor login attempts
 		 * based on their own rules.
 		 *
-		 * @param bool     $rate_limited Whether the user login is rate limited.
-		 * @param WP_User $user          The user attempting to login.
+		 * @since 0.8.0
+		 *
+		 * @param bool    $rate_limited Whether the user login is rate limited.
+		 * @param WP_User $user         The user attempting to login.
 		 */
 		return apply_filters( 'two_factor_is_user_rate_limited', $rate_limited, $user );
 	}
@@ -1470,6 +1488,14 @@ public static function rest_api_can_edit_user_and_update_two_factor_options( $us
 			return new WP_Error( 'revalidation_required', __( 'Two Factor Revalidation required.', 'two-factor' ) );
 		}
 
+		/**
+		 * Filters whether the current user can edit another user's two-factor options via the REST API.
+		 *
+		 * @since 0.7.0
+		 *
+		 * @param bool $can_edit Whether the user can edit the two-factor options. Default true.
+		 * @param int  $user_id  The user ID being updated.
+		 */
 		return apply_filters( 'two_factor_rest_api_can_edit_user', true, $user_id );
 	}
 
@@ -1569,6 +1595,14 @@ public static function _login_form_validate_2fa( $user, $nonce = '', $provider =
 
 		wp_set_auth_cookie( $user->ID, $rememberme );
 
+		/**
+		 * Fires after a user has been authenticated via two-factor.
+		 *
+		 * @since 0.5.2
+		 *
+		 * @param WP_User               $user     The authenticated user.
+		 * @param Two_Factor_Provider $provider The two-factor provider used for authentication.
+		 */
 		do_action( 'two_factor_user_authenticated', $user, $provider );
 
 		remove_filter( 'attach_session_information', $session_information_callback );
@@ -1677,6 +1711,14 @@ public static function _login_form_revalidate_2fa( $nonce = '', $provider = '',
 			)
 		);
 
+		/**
+		 * Fires after a user has been revalidated via two-factor.
+		 *
+		 * @since 0.8.0
+		 *
+		 * @param WP_User               $user     The revalidated user.
+		 * @param Two_Factor_Provider $provider The two-factor provider used for revalidation.
+		 */
 		do_action( 'two_factor_user_revalidated', $user, $provider );
 
 		// Must be global because that's how login_header() uses it.
@@ -1787,11 +1829,13 @@ public static function should_reset_password( $user_id ) {
 		 * that the password has been compromised and an attacker is trying to brute force the 2nd
 		 * factor.
 		 *
-		 * ⚠️ `get_user_time_delay()` mitigates brute force attempts, but many 2nd factors --
+		 * `get_user_time_delay()` mitigates brute force attempts, but many 2nd factors --
 		 * like TOTP and backup codes -- are very weak on their own, so it's not safe to give
 		 * attackers unlimited attempts. Setting this to a very large number is strongly
 		 * discouraged.
 		 *
+		 * @since 0.8.0
+		 *
 		 * @param int $limit The number of attempts before the password is reset.
 		 */
 		$failed_attempt_limit = apply_filters( 'two_factor_failed_attempt_limit', 30 );
@@ -1837,6 +1881,8 @@ public static function send_password_reset_emails( $user ) {
 		 * Filters whether or not to email the site admin when a user's password has been
 		 * compromised and reset.
 		 *
+		 * @since 0.8.0
+		 *
 		 * @param bool $reset `true` to notify the admin, `false` to not notify them.
 		 */
 		$notify_admin = apply_filters( 'two_factor_notify_admin_user_password_reset', true );
@@ -2056,7 +2102,9 @@ private static function get_recommended_providers( $user ) {
 		);
 
 		/**
-		 * Set the keys of the recommended (secure) methods.
+		 * Filters the keys of the recommended (secure) methods.
+		 *
+		 * @since 0.14.0
 		 *
 		 * @param array   $recommended_providers The recommended providers.
 		 * @param WP_User $user The user.
@@ -2360,6 +2408,13 @@ public static function rememberme() {
 			$rememberme = true;
 		}
 
+		/**
+		 * Filters whether the login session should persist between browser sessions.
+		 *
+		 * @since 0.5.0
+		 *
+		 * @param bool $rememberme Whether to remember the user. Default false.
+		 */
 		return (bool) apply_filters( 'two_factor_rememberme', $rememberme );
 	}
 

providers/class-two-factor-backup-codes.php

@@ -253,10 +253,12 @@ public function user_options( $user ) {
 	 */
 	private function get_backup_code_length( $user ) {
 		/**
-		 * Customize the character count of the backup codes.
+		 * Filters the character count of the backup codes.
 		 *
-		 * @var int $code_length Length of the backup code.
-		 * @var WP_User $user User object.
+		 * @since 0.11.0
+		 *
+		 * @param int     $code_length Length of the backup code. Default 8.
+		 * @param WP_User $user        User object.
 		 */
 		$code_length = (int) apply_filters( 'two_factor_backup_code_length', 8, $user );
 
@@ -386,14 +388,41 @@ public function authentication_page( $user ) {
 		$code_placeholder = str_repeat( 'X', $code_length );
 
 		?>
-		<?php do_action( 'two_factor_before_authentication_prompt', $this ); ?>
+		<?php
+		/**
+		 * Fires before the two-factor authentication prompt text.
+		 *
+		 * @since 0.15.0
+		 *
+		 * @param Two_Factor_Provider $provider The two-factor provider instance.
+		 */
+		do_action( 'two_factor_before_authentication_prompt', $this );
+		?>
 		<p class="two-factor-prompt"><?php esc_html_e( 'Enter a recovery code.', 'two-factor' ); ?></p>
-		<?php do_action( 'two_factor_after_authentication_prompt', $this ); ?>
+		<?php
+		/**
+		 * Fires after the two-factor authentication prompt text.
+		 *
+		 * @since 0.15.0
+		 *
+		 * @param Two_Factor_Provider $provider The two-factor provider instance.
+		 */
+		do_action( 'two_factor_after_authentication_prompt', $this );
+		?>
 		<p>
 			<label for="authcode"><?php esc_html_e( 'Recovery Code:', 'two-factor' ); ?></label>
 			<input type="text" inputmode="numeric" name="two-factor-backup-code" id="authcode" class="input authcode" value="" size="20" pattern="[0-9 ]*" placeholder="<?php echo esc_attr( $code_placeholder ); ?>" data-digits="<?php echo esc_attr( $code_length ); ?>" />
 		</p>
-		<?php do_action( 'two_factor_after_authentication_input', $this ); ?>
+		<?php
+		/**
+		 * Fires after the two-factor authentication input field.
+		 *
+		 * @since 0.15.0
+		 *
+		 * @param Two_Factor_Provider $provider The two-factor provider instance.
+		 */
+		do_action( 'two_factor_after_authentication_input', $this );
+		?>
 		<?php
 		submit_button( __( 'Verify', 'two-factor' ) );
 	}

providers/class-two-factor-dummy.php

@@ -43,10 +43,19 @@ public function get_label() {
 	public function authentication_page( $user ) {
 		require_once ABSPATH . '/wp-admin/includes/template.php';
 		?>
-		<?php do_action( 'two_factor_before_authentication_prompt', $this ); ?>
+		<?php
+		/** This action is documented in providers/class-two-factor-backup-codes.php */
+		do_action( 'two_factor_before_authentication_prompt', $this );
+		?>
 		<p><?php esc_html_e( 'Are you really you?', 'two-factor' ); ?></p>
-		<?php do_action( 'two_factor_after_authentication_prompt', $this ); ?>
-		<?php do_action( 'two_factor_after_authentication_input', $this ); ?>
+		<?php
+		/** This action is documented in providers/class-two-factor-backup-codes.php */
+		do_action( 'two_factor_after_authentication_prompt', $this );
+		?>
+		<?php
+		/** This action is documented in providers/class-two-factor-backup-codes.php */
+		do_action( 'two_factor_after_authentication_input', $this );
+		?>
 		<?php
 		submit_button( __( 'Yup.', 'two-factor' ) );
 	}

providers/class-two-factor-email.php

@@ -72,9 +72,11 @@ public function get_alternative_provider_label() {
 	 */
 	private function get_token_length() {
 		/**
-		 * Number of characters in the email token.
+		 * Filters the number of characters in the email token.
 		 *
-		 * @param int $token_length Number of characters in the email token.
+		 * @since 0.11.0
+		 *
+		 * @param int $token_length Number of characters in the email token. Default 8.
 		 */
 		$token_length = (int) apply_filters( 'two_factor_email_token_length', 8 );
 
@@ -169,22 +171,23 @@ public function user_token_ttl( $user_id ) {
 		$token_ttl = 15 * MINUTE_IN_SECONDS;
 
 		/**
-		 * Number of seconds the token is considered valid
-		 * after the generation.
+		 * Filters the number of seconds the email token is considered valid after generation.
 		 *
+		 * @since 0.6.0
 		 * @deprecated 0.11.0 Use {@see 'two_factor_email_token_ttl'} instead.
 		 *
-		 * @param integer $token_ttl Token time-to-live in seconds.
-		 * @param integer $user_id User ID.
+		 * @param int $token_ttl Token time-to-live in seconds.
+		 * @param int $user_id User ID.
 		 */
 		$token_ttl = (int) apply_filters_deprecated( 'two_factor_token_ttl', array( $token_ttl, $user_id ), '0.11.0', 'two_factor_email_token_ttl' );
 
 		/**
-		 * Number of seconds the token is considered valid
-		 * after the generation.
+		 * Filters the number of seconds the email token is considered valid after generation.
+		 *
+		 * @since 0.11.0
 		 *
-		 * @param integer $token_ttl Token time-to-live in seconds.
-		 * @param integer $user_id User ID.
+		 * @param int $token_ttl Token time-to-live in seconds.
+		 * @param int $user_id User ID.
 		 */
 		return (int) apply_filters( 'two_factor_email_token_ttl', $token_ttl, $user_id );
 	}
@@ -304,15 +307,19 @@ public function generate_and_email_token( $user ) {
 		$message = wp_strip_all_tags( implode( "\n\n", $message_parts ) );
 
 		/**
-		 * Filter the token email subject.
+		 * Filters the token email subject.
+		 *
+		 * @since 0.5.2
 		 *
 		 * @param string $subject The email subject line.
 		 * @param int    $user_id The ID of the user.
 		 */
 		$subject = apply_filters( 'two_factor_token_email_subject', $subject, $user->ID );
 
 		/**
-		 * Filter the token email message.
+		 * Filters the token email message.
+		 *
+		 * @since 0.5.2
 		 *
 		 * @param string $message The email message.
 		 * @param string $token   The token.
@@ -344,14 +351,23 @@ public function authentication_page( $user ) {
 
 		require_once ABSPATH . '/wp-admin/includes/template.php';
 		?>
-		<?php do_action( 'two_factor_before_authentication_prompt', $this ); ?>
+		<?php
+		/** This action is documented in providers/class-two-factor-backup-codes.php */
+		do_action( 'two_factor_before_authentication_prompt', $this );
+		?>
 		<p class="two-factor-prompt"><?php esc_html_e( 'A verification code has been sent to the email address associated with your account.', 'two-factor' ); ?></p>
-		<?php do_action( 'two_factor_after_authentication_prompt', $this ); ?>
+		<?php
+		/** This action is documented in providers/class-two-factor-backup-codes.php */
+		do_action( 'two_factor_after_authentication_prompt', $this );
+		?>
 		<p>
 			<label for="authcode"><?php esc_html_e( 'Verification Code:', 'two-factor' ); ?></label>
 			<input type="text" inputmode="numeric" name="two-factor-email-code" id="authcode" class="input authcode" value="" size="20" pattern="[0-9 ]*" autocomplete="one-time-code" placeholder="<?php echo esc_attr( $token_placeholder ); ?>" data-digits="<?php echo esc_attr( $token_length ); ?>" />
 		</p>
-		<?php do_action( 'two_factor_after_authentication_input', $this ); ?>
+		<?php
+		/** This action is documented in providers/class-two-factor-backup-codes.php */
+		do_action( 'two_factor_after_authentication_input', $this );
+		?>
 		<?php submit_button( __( 'Verify', 'two-factor' ) ); ?>
 		<p class="two-factor-email-resend">
 			<input type="submit" class="button" name="<?php echo esc_attr( self::INPUT_NAME_RESEND_CODE ); ?>" value="<?php esc_attr_e( 'Resend Code', 'two-factor' ); ?>" />

providers/class-two-factor-fido-u2f.php

@@ -179,10 +179,19 @@ public function authentication_page( $user ) {
 		wp_enqueue_script( 'fido-u2f-login' );
 
 		?>
-		<?php do_action( 'two_factor_before_authentication_prompt', $this ); ?>
+		<?php
+		/** This action is documented in providers/class-two-factor-backup-codes.php */
+		do_action( 'two_factor_before_authentication_prompt', $this );
+		?>
 		<p><?php esc_html_e( 'Now insert (and tap) your Security Key.', 'two-factor' ); ?></p>
-		<?php do_action( 'two_factor_after_authentication_prompt', $this ); ?>
-		<?php do_action( 'two_factor_after_authentication_input', $this ); ?>
+		<?php
+		/** This action is documented in providers/class-two-factor-backup-codes.php */
+		do_action( 'two_factor_after_authentication_prompt', $this );
+		?>
+		<?php
+		/** This action is documented in providers/class-two-factor-backup-codes.php */
+		do_action( 'two_factor_after_authentication_input', $this );
+		?>
 		<input type="hidden" name="u2f_response" id="u2f_response" />
 		<?php
 	}