Hooks and Filters

Advanced Username Manager provides a comprehensive set of hooks and filters that allow developers to customize and extend the plugin’s functionality. This guide documents all available hooks with code examples.

Actions

Actions allow you to run custom code at specific points during the username change process.

advancedusernamemanagerbeforeusername_change

Fires immediately before the username is changed in the database.

Parameters:

Parameter	Type	Description
`$user_id`	int	The ID of the user whose username is being changed
`$newusername`	string	The new username being saved
`$currentusername`	string	The current username before the change

Example: Log Username Changes

add_action( 'advanced_username_manager_before_username_change', function( $user_id, $new_user_name, $current_user_name ) {
    error_log( sprintf(
        'User %d is changing username from "%s" to "%s"',
        $user_id,
        $current_user_name,
        $new_user_name
    ) );
}, 10, 3 );

Example: Notify Administrators

add_action( 'advanced_username_manager_before_username_change', function( $user_id, $new_user_name, $current_user_name ) {
    $user = get_userdata( $user_id );
    $admin_email = get_option( 'admin_email' );

    $subject = 'Username Change Notification';
    $message = sprintf(
        'User %s (ID: %d) is changing their username from "%s" to "%s".',
        $user->user_email,
        $user_id,
        $current_user_name,
        $new_user_name
    );

    wp_mail( $admin_email, $subject, $message );
}, 10, 3 );

Example: Prevent Specific Username Changes

add_action( 'advanced_username_manager_before_username_change', function( $user_id, $new_user_name, $current_user_name ) {
    // Prevent changing to usernames containing "admin"
    if ( stripos( $new_user_name, 'admin' ) !== false ) {
        wp_send_json_error( array(
            'error_message' => 'Usernames containing "admin" are not allowed.'
        ) );
    }
}, 10, 3 );

advancedusernamemanagerafterusername_change

Fires after the username has been successfully changed in the database.

Parameters:

Parameter	Type	Description
`$user_id`	int	The ID of the user whose username was changed
`$newusername`	string	The new username that was saved
`$currentusername`	string	The old username before the change
`$user`	WP_User	The WordPress user object with updated data

Example: Update Third-Party Services

add_action( 'advanced_username_manager_after_username_change', function( $user_id, $new_user_name, $current_user_name, $user ) {
    // Sync username change with external CRM
    update_crm_username( $user_id, $new_user_name );

    // Update newsletter subscription
    update_newsletter_subscriber( $user->user_email, $new_user_name );
}, 10, 4 );

Example: Award Points for Username Change

add_action( 'advanced_username_manager_after_username_change', function( $user_id, $new_user_name, $current_user_name, $user ) {
    // Award 10 points for updating profile
    if ( function_exists( 'gamipress_award_points_to_user' ) ) {
        gamipress_award_points_to_user( $user_id, 10, 'points' );
    }
}, 10, 4 );

Example: Post to Activity Stream

add_action( 'advanced_username_manager_after_username_change', function( $user_id, $new_user_name, $current_user_name, $user ) {
    // Post BuddyPress activity
    if ( function_exists( 'bp_activity_add' ) ) {
        bp_activity_add( array(
            'user_id'   => $user_id,
            'component' => 'profile',
            'type'      => 'username_changed',
            'action'    => sprintf(
                '%s changed their username to %s',
                bp_core_get_userlink( $user_id ),
                $new_user_name
            ),
        ) );
    }
}, 10, 4 );

Example: Clear Custom Cache

add_action( 'advanced_username_manager_after_username_change', function( $user_id, $new_user_name, $current_user_name, $user ) {
    // Clear custom plugin caches
    wp_cache_delete( 'user_profile_' . $user_id, 'my_plugin' );
    wp_cache_delete( 'username_lookup_' . $current_user_name, 'my_plugin' );

    // Clear any transients
    delete_transient( 'user_display_' . $user_id );
}, 10, 4 );

advancedusernamemanageraddgeneralsettingoptions

Fires in the General Settings page, allowing you to add custom setting fields.

Example: Add Custom Setting Field

add_action( 'advanced_username_manager_add_general_setting_options', function() {
    $settings = get_option( 'advanced_username_manager_general_settings' );
    $custom_option = isset( $settings['custom_option'] ) ? $settings['custom_option'] : '';
    ?>
    <div class="wbcom-settings-section-wrap">
        <div class="wbcom-settings-section-options-heading">
            <label><?php esc_html_e( 'Custom Option' ); ?></label>
            <p class="description"><?php esc_html_e( 'Description of your custom option.' ); ?></p>
        </div>
        <div class="wbcom-settings-section-options">
            <input type="text"
                   name="advanced_username_manager_general_settings[custom_option]"
                   value="<?php echo esc_attr( $custom_option ); ?>"
                   class="regular-text">
        </div>
    </div>
    <?php
} );

Filters

Filters allow you to modify data before it’s used or displayed.

advancedusernamemanageremailsubject

Filters the email subject line sent to users after username change.

Parameters:

Parameter	Type	Description
`$email_subject`	string	The default email subject

Default Value:

"{Site Name} Your Username Has Been Successfully Updated !"

Example: Customize Email Subject

add_filter( 'advanced_username_manager_email_subject', function( $email_subject ) {
    return 'Your account username has been updated';
} );

Example: Add User Name to Subject

add_filter( 'advanced_username_manager_email_subject', function( $email_subject ) {
    $user = wp_get_current_user();
    return sprintf( 'Hi %s, your username has been updated!', $user->display_name );
} );

advancedusernamemanageremailcontent

Filters the email content sent to users after username change.

Parameters:

Parameter	Type	Description
`$email_content`	string	The default email HTML content

Example: Customize Email Content

add_filter( 'advanced_username_manager_email_content', function( $email_content ) {
    $custom_content = '<h2>Username Updated</h2>';
    $custom_content .= '<p>Your username has been successfully changed.</p>';
    $custom_content .= '<p>Visit your account: <a href="' . home_url( '/my-account/' ) . '">My Account</a></p>';

    return $custom_content;
} );

Example: Add Custom Footer

add_filter( 'advanced_username_manager_email_content', function( $email_content ) {
    $footer = '<hr>';
    $footer .= '<p style="font-size: 12px; color: #666;">';
    $footer .= 'This is an automated message. Please do not reply to this email.';
    $footer .= '</p>';

    return $email_content . $footer;
} );

Example: Translate Email Content

add_filter( 'advanced_username_manager_email_content', function( $email_content ) {
    // Use custom translation based on user language
    $user = wp_get_current_user();
    $user_language = get_user_meta( $user->ID, 'user_language', true );

    if ( $user_language === 'es' ) {
        // Return Spanish version
        return get_spanish_email_content();
    }

    return $email_content;
} );

bpusernamechangeruserhas_access

Filters whether a user has access to the BuddyPress Username Change settings tab.

Parameters:

Parameter	Type	Description
`$has_access`	bool	Whether the user has access (default: true for own profile or super admin)

Example: Allow Moderators to Change Any Username

add_filter( 'bp_username_changer_user_has_access', function( $has_access ) {
    // Allow moderators to change any member's username
    if ( current_user_can( 'moderate' ) ) {
        return true;
    }

    return $has_access;
} );

Example: Restrict Access Based on Membership Level

add_filter( 'bp_username_changer_user_has_access', function( $has_access ) {
    $user_id = get_current_user_id();

    // Only premium members can change usernames
    $membership_level = get_user_meta( $user_id, 'membership_level', true );

    if ( $membership_level !== 'premium' && ! is_super_admin() ) {
        return false;
    }

    return $has_access;
} );

aumusernamechangerusercan_update

Filters whether the current user can update the displayed user’s username.

Parameters:

Parameter	Type	Description
`$can_update`	bool	Whether user can update (default: true for own profile or super admin)

Example: Allow Friend Connections to Update

add_filter( 'aum_username_changer_user_can_update', function( $can_update ) {
    if ( ! function_exists( 'friends_check_friendship' ) ) {
        return $can_update;
    }

    $loggedin_user = get_current_user_id();
    $displayed_user = bp_displayed_user_id();

    // Allow if users are friends
    if ( friends_check_friendship( $loggedin_user, $displayed_user ) ) {
        return true;
    }

    return $can_update;
} );

aumbpusernamechangertemplate_settings

Filters the BuddyPress template used for the username change page.

Parameters:

Parameter	Type	Description
`$template`	string	Template file path (default: ‘members/single/plugins’)

Example: Use Custom Template

add_filter( 'aum_bp_username_changer_template_settings', function( $template ) {
    // Use custom template from your theme
    return 'members/single/settings/username-change';
} );

advancedusernamemanagerprofileslug_prefix

Filters the prefix used for unique identifier profile slugs.

Parameters:

Parameter	Type	Description
`$prefix`	string	The prefix for unique identifiers (default: ‘aum’)

Example: Custom Prefix

add_filter( 'advanced_username_manager_profile_slug_prefix', function( $prefix ) {
    return 'member'; // Changes aum5f8a3c9b1 to member5f8a3c9b1
} );

Example: Site-Specific Prefix

add_filter( 'advanced_username_manager_profile_slug_prefix', function( $prefix ) {
    $site_name = get_bloginfo( 'name' );
    $site_slug = sanitize_title( $site_name );

    // Use first 3 letters of site name
    return substr( $site_slug, 0, 3 );
} );

advancedusernamemanagercoregetuserslug

Filters the profile slug retrieved for a specific user.

Parameters:

Parameter	Type	Description
`$profile_slug`	string	The user’s profile slug
`$user_id`	int	The user ID

Example: Override Slug for Specific Users

add_filter( 'advanced_username_manager_core_get_user_slug', function( $profile_slug, $user_id ) {
    // Use custom slugs for VIP members
    $is_vip = get_user_meta( $user_id, 'vip_member', true );

    if ( $is_vip ) {
        return 'vip-' . $user_id;
    }

    return $profile_slug;
}, 10, 2 );

Common Customization Scenarios

Scenario 1: Integrate with Points System

Award points when users update their username:

// Award points after username change
add_action( 'advanced_username_manager_after_username_change', function( $user_id, $new_user_name, $current_user_name, $user ) {
    // Check if this is the first time changing username
    $change_count = get_user_meta( $user_id, 'username_change_count', true );

    if ( empty( $change_count ) ) {
        // Award 50 points for first username update
        mycred_add( 'username_update', $user_id, 50, 'Updated username for the first time' );
        update_user_meta( $user_id, 'username_change_count', 1 );
    } else {
        // Award 10 points for subsequent updates
        mycred_add( 'username_update', $user_id, 10, 'Updated username' );
        update_user_meta( $user_id, 'username_change_count', $change_count + 1 );
    }
}, 10, 4 );

Scenario 2: Block Offensive Usernames

Prevent users from choosing inappropriate usernames:

add_action( 'advanced_username_manager_before_username_change', function( $user_id, $new_user_name, $current_user_name ) {
    $blocked_words = array( 'spam', 'offensive', 'badword' );

    foreach ( $blocked_words as $word ) {
        if ( stripos( $new_user_name, $word ) !== false ) {
            wp_send_json_error( array(
                'error_message' => 'This username contains inappropriate content. Please choose a different username.'
            ) );
        }
    }
}, 10, 3 );

Scenario 3: Require Username Format

Enforce specific username patterns:

add_action( 'advanced_username_manager_before_username_change', function( $user_id, $new_user_name, $current_user_name ) {
    // Require usernames to start with a letter
    if ( ! preg_match( '/^[a-zA-Z]/', $new_user_name ) ) {
        wp_send_json_error( array(
            'error_message' => 'Username must start with a letter.'
        ) );
    }

    // Require at least one number
    if ( ! preg_match( '/[0-9]/', $new_user_name ) ) {
        wp_send_json_error( array(
            'error_message' => 'Username must contain at least one number.'
        ) );
    }
}, 10, 3 );

Scenario 4: Custom Email Templates

Use custom email templates with variables:

add_filter( 'advanced_username_manager_email_content', function( $email_content ) {
    $user = wp_get_current_user();

    // Load custom template
    ob_start();
    include locate_template( 'emails/username-change.php' );
    $template = ob_get_clean();

    // Replace variables
    $template = str_replace( '{user_name}', $user->display_name, $template );
    $template = str_replace( '{new_username}', $user->user_login, $template );
    $template = str_replace( '{site_name}', get_bloginfo( 'name' ), $template );

    return $template;
} );

Scenario 5: Log All Username Changes

Maintain a detailed log of username changes:

add_action( 'advanced_username_manager_after_username_change', function( $user_id, $new_user_name, $current_user_name, $user ) {
    global $wpdb;

    // Log to custom table
    $wpdb->insert(
        $wpdb->prefix . 'username_history',
        array(
            'user_id'      => $user_id,
            'old_username' => $current_user_name,
            'new_username' => $new_user_name,
            'changed_date' => current_time( 'mysql' ),
            'ip_address'   => $_SERVER['REMOTE_ADDR'],
            'user_agent'   => $_SERVER['HTTP_USER_AGENT'],
        ),
        array( '%d', '%s', '%s', '%s', '%s', '%s' )
    );
}, 10, 4 );

Testing Your Customizations

When developing custom functionality, always test thoroughly:

Enable WordPress Debug Mode

// In wp-config.php
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Test Scenarios

Before Change Hook – Verify your code runs before username update
After Change Hook – Verify your code runs after successful update
Filter Output – Check filtered values are correct
Error Handling – Test what happens when your code fails
Multiple Users – Test with different user roles and scenarios

Debugging Tips

// Log to debug.log
error_log( 'Username changed from ' . $current_user_name . ' to ' . $new_user_name );

// Inspect variables
error_log( print_r( $user, true ) );

// Check if function exists before using
if ( function_exists( 'bp_activity_add' ) ) {
    // Your BuddyPress code
}

Available Hooks & Filters for Developers

Hooks and Filters

Actions

advancedusernamemanagerbeforeusername_change

advancedusernamemanagerafterusername_change

advancedusernamemanageraddgeneralsettingoptions

Filters

advancedusernamemanageremailsubject

advancedusernamemanageremailcontent

bpusernamechangeruserhas_access

aumusernamechangerusercan_update

aumbpusernamechangertemplate_settings

advancedusernamemanagerprofileslug_prefix

advancedusernamemanagercoregetuserslug

Common Customization Scenarios

Scenario 1: Integrate with Points System

Scenario 2: Block Offensive Usernames

Scenario 3: Require Username Format

Scenario 4: Custom Email Templates

Scenario 5: Log All Username Changes

Testing Your Customizations

Enable WordPress Debug Mode

Test Scenarios

Debugging Tips

Related Documentation