Hooks & Filters: Users

The following is an non-exhaustive list of hooks and filters developers may use to adjust certain features of the plugin that pertain to users.

Where a return type is specified for a filter, you should always ensure that the type of value returned from your callable on that filter matches what is required. Shield uses PHP Strict wherever possible, and if you return a type that isn't the same as the required type, you'll likely generate Fatal Errors.

Examples provided are untested and may not make logical sense to use - they're provided solely to illustrate how you might start to use a given filter.

[Filter] Is User Password Expired?

If you're using Shield's built-in password expiration feature, you can adjust the result of Shield's determination of whether a user's password is expired.

Filter: shield/user/is_user_password_expired

Return Type: bool (strict)

Additional Parameters:

  1. [\WP_User ]$user
  2. [int ] $passAge - the age (seconds) of the current password as determined by Shield
  3. [int ] $expireTTL - the current configuration for TTL (seconds) of a password before expiration

Available Since: v19.1.16

Code Example:

add_filter(
    'shield/user/is_user_password_expired',
    function ( $isExpired, $user, $passAge, $expireTTL ) {
       return $isExpired && \in_array( 'administrator', $user->roles );
    },
    10, 4
);

This filter example will result in the expired password setting only ever being applied to adminstrator users.

[Filter] Is User Account Idle?

If you're using Shield's idle account detection feature, you can override its determination of when an account is considered idle. (note: this is not idle session, but idle account usage)

Filter: shield/user/is_user_account_idle

Return Type: bool (strict)

Additional Parameters:

  1. [\WP_User ]$user
  2. [int ] $idleFor - how long the user has been idle without site login
  3. [string[] ] $rolesToSuspend - the configured user roles for which the idle option is applied

Available Since: v19.1.16

Code Example:

add_filter(
    'shield/user/is_user_account_idle',
    function ( $isIdle, $user, $idleFor, $rolesToSuspend ) {
       return $isIdle ||
          ( \in_array( 'administrator', $user->roles ) && $idleFor > MONTH_IN_SECONDS );
    },
    10, 4
);

This filter example will override the idle user setting so that administrators will automatically be suspended if they've been idle for at least 1 month.

[Filter] Is User Account Hard Suspended?

If you're using Shield's ability to manually ("hard") suspend user accounts, you can override this determination.

Filter: shield/user/is_user_hard_suspended

Return Type: bool (strict)

Additional Parameters:

  1. [\WP_User ]$user

Available Since: v19.1.16

Code Example:

add_filter(
    'shield/user/is_user_hard_suspended',
    function ( $isHardSuspended, $user ) {
       return $isHardSuspended && \in_array( 'administrator', $user->roles );
    },
    10, 2
);

This filter example results in the hard suspension only ever being applied to users with the administrator role.