Documentation / Hooks and Filters

Hooks and Filters

Overview

Teydea Login Security provides PHP filters and actions that allow developers to extend or modify the plugin’s behavior. These hooks follow standard WordPress conventions.

PHP Filters

`password_requirements__is_user_excluded_from_policy`

Exclude specific users from all password policy enforcement. This is useful for users managed externally, such as those who log in through an SSO provider.

Parameters:

bool $is_excluded — Whether the user is excluded from the password policy. Default false.
?WP_User $user — The user object, or null if not available.

Return: bool — true to exclude the user, false to apply the policy.

add_filter(
    'password_requirements__is_user_excluded_from_policy',
    function ( bool $is_excluded, ?WP_User $user ): bool {
        // Exclude users with a specific meta value (e.g., SSO users).
        if ( $user instanceof WP_User && get_user_meta( $user->ID, 'is_sso_user', true ) ) {
            return true;
        }

        return $is_excluded;
    },
    10,
    2
);

`password_requirements__is_password_change_compelled`

Declare that the password change a user is facing is forced on them rather than chosen by them. A compelled change is exempt from the minimum password age rule, so the user is never sent to a reset form that then refuses the reset. See Age Rules.

The plugin already treats an expired password, a reset key it has issued for the account, and a change driven by somebody with the standing to edit the account as compelled. Use this filter when a reset is driven by machinery the plugin cannot observe — an external identity provider, or a companion plugin enforcing its own reset schedule.

Parameters:

bool $is_compelled — Whether the plugin has already concluded the change is compelled.
?WP_User $user — The user object, or null if not available.

Return: bool — true to exempt the change from the minimum password age rule, false to apply it.

add_filter(
    'password_requirements__is_password_change_compelled',
    function ( bool $is_compelled, ?WP_User $user ): bool {
        // Users flagged for a mandatory reset by another system may always change their password.
        if ( $user instanceof WP_User && get_user_meta( $user->ID, 'must_reset_password', true ) ) {
            return true;
        }

        return $is_compelled;
    },
    10,
    2
);

`password_requirements__password_reset_form_link`

Modify the URL where users are redirected when their password is non-compliant or expired. Third-party integrations (such as WooCommerce) use this filter to redirect to their own password reset pages.

Parameters:

string $url — The password reset form URL.
WP_User $user — The user object.
array $query_args — The query arguments used to construct the URL (includes key, login, action, wp_lang).

Return: string — The modified URL.

add_filter(
    'password_requirements__password_reset_form_link',
    function ( string $url, WP_User $user, array $query_args ): string {
        // Redirect to a custom password reset page.
        return add_query_arg( $query_args, home_url( '/custom-reset/' ) );
    },
    10,
    3
);

`password_requirements__settings_fields_config`

Extend or modify the settings fields configuration. This allows developers to add custom settings fields or modify validation rules.

Parameters:

array $config — The settings fields configuration array.

Return: array — The modified configuration array.

`password_requirements__custom_password_weaklist` (PRO)

Provide a custom list of weak passwords in addition to the built-in list of over 100,000 entries. Passwords on this list are rejected when the weaklist rule is enabled.

Parameters:

array $weaklist — An array of weak password strings. Default empty array.

Return: array — An array of password strings to reject.

add_filter(
    'password_requirements__custom_password_weaklist',
    function ( array $weaklist ): array {
        // Add organization-specific weak passwords.
        $weaklist[] = 'companyname123';
        $weaklist[] = 'welcome2024';

        return $weaklist;
    }
);

`password_requirements__custom_restricted_phrases`

Add entries to the site-wide restricted words and phrases list at runtime. Contributions are additive: they are merged with the admin-managed list and cannot remove entries an administrator has saved.

Parameters:

array $phrases — Additional restricted phrases. Default empty array.

Return: array — The list of phrases to also block.

The active list is built once per password-policy object and reused for every check that object performs, so your callback runs once per policy rather than once per password check. Return the same phrases every time it is called: a callback that returns a different list on a later call within the same request has no effect, because the list built on the first call is the one every subsequent check uses.

add_filter(
    'password_requirements__custom_restricted_phrases',
    function ( array $phrases ): array {
        $phrases[] = 'acme';
        $phrases[] = 'acmecorp';

        return $phrases;
    }
);

`password_requirements__vendor_default_usernames` (PRO)

Add usernames that should be flagged as vendor defaults by Vendor-Default Account Detection, in addition to the built-in list. Matching is case-insensitive.

Parameters:

array $usernames — Additional usernames to flag. Default empty array.

Return: array — The list of usernames to also flag.

PHP Actions

`password_requirements__settings_updated`

Fires after the plugin settings are saved. Receives the new settings data, the previous settings data, and the settings object.

Parameters:

array $data — The updated settings data.
array $old_data — The settings data before the update.
Settings $settings — The settings object.

add_action(
    'password_requirements__settings_updated',
    function ( array $data, array $old_data ): void {
        // Log settings changes or trigger other actions.
        error_log( 'Password policy settings were updated.' );
    },
    10,
    2
);