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.

advanced_username_manager_before_username_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
$new_user_name	string	The new username being saved
$current_user_name	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 );

---

advanced_username_manager_after_username_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
$new_user_name	string	The new username that was saved
$current_user_name	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 );

---

advanced_username_manager_add_general_setting_options

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.

advanced_username_manager_email_subject

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 );
} );

---

advanced_username_manager_email_content

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;
} );

---

bp_username_changer_user_has_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;
} );

---

aum_username_changer_user_can_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;
} );

---

aum_bp_username_changer_template_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';
} );

---

advanced_username_manager_profile_slug_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 );
} );

---

advanced_username_manager_core_get_user_slug

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

1. Before Change Hook - Verify your code runs before username update
2. After Change Hook - Verify your code runs after successful update
3. Filter Output - Check filtered values are correct
4. Error Handling - Test what happens when your code fails
5. 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
}

Related Documentation

• General Settings - Configure plugin options
• BuddyPress Integration - BuddyPress-specific features
• WooCommerce Integration - WooCommerce hooks
• Troubleshooting - Fix common issues