Developer Documentation – Advanced Username Manager

Get Started

Available Hooks

Action Hooks

1. advanced_username_changed

Triggered after a username has been successfully changed.

Parameters:

  • $new_username (string) – The new username
  • $user (WP_User) – The user object containing user data

Example:

add_action('advanced_username_changed', 'custom_username_change_handler', 10, 2);
function custom_username_change_handler($new_username, $user) {
    // Log the username change to a custom database or external service
    do_action('my_custom_logger', 'Username changed', [
        'user_id' => $user->ID,
        'new_username' => $new_username,
        'previous_username' => $user->user_login
    ]);
}

2. advanced_username_manager_add_general_setting_options

Allows adding custom options to the general settings page.

Example:

add_action('advanced_username_manager_add_general_setting_options', 'add_custom_username_settings');
function add_custom_username_settings() {
    $custom_option = get_option('advanced_username_manager_general_settings');
    $custom_value = isset($custom_option['custom_field']) ? $custom_option['custom_field'] : '';
    ?>
    <div class="wbcom-settings-section-wrap">
        <div class="wbcom-settings-section-options-heading">
            <label><?php esc_html_e('Custom Pattern Restrictions', 'my-plugin'); ?></label>
            <p class="description"><?php esc_html_e('Define a regex pattern to validate usernames.', 'my-plugin'); ?></p>
        </div>
        <div class="wbcom-settings-section-options">
            <input name="advanced_username_manager_general_settings[custom_field]" 
                   type="text" 
                   class="regular-text" 
                   value="<?php echo esc_attr($custom_value); ?>">
        </div>
    </div>
    <?php
}

Filter Hooks

1. advanced_username_manager_profile_slug_prefix

Allows customization of the profile slug prefix for BuddyPress unique identifiers.

Parameters:

  • $prefix (string) – Default prefix ‘aum’

Example:

add_filter('advanced_username_manager_profile_slug_prefix', 'custom_username_prefix');
function custom_username_prefix($prefix) {
    return 'mysite'; // Changes the prefix from 'aum' to 'mysite'
}

2. advanced_username_manager_core_get_user_slug

Filters the profile slug based on the originally provided user ID.

Parameters:

  • $profile_slug (string) – User profile slug
  • $user_id (int) – User ID

Example:

add_filter('advanced_username_manager_core_get_user_slug', 'modify_user_profile_slug', 10, 2);
function modify_user_profile_slug($profile_slug, $user_id) {
    // Add a custom prefix for premium members
    if (is_premium_member($user_id)) {
        return 'vip-' . $profile_slug;
    }

    return $profile_slug;
}

3. advanced_username_manager_email_subject

Customizes the email notification subject sent after username change.

Parameters:

  • $subject (string) – Default email subject

Example:

add_filter('advanced_username_manager_email_subject', 'custom_username_email_subject');
function custom_username_email_subject($subject) {
    $site_name = get_bloginfo('name');
    return sprintf('[%s] Your username has been successfully changed', $site_name);
}

4. bp_business_review_email_content

Customizes the email notification content for username change.

Parameters:

  • $content (string) – Default email content

Example:

add_filter('bp_business_review_email_content', 'custom_username_email_template');
function custom_username_email_template($content) {
    $site_name = get_bloginfo('name');
    $site_url = home_url();

    ob_start();
    ?>
    <div style="max-width: 600px; margin: 0 auto; padding: 20px; font-family: Arial, sans-serif;">
        <h2>Username Changed Successfully</h2>
        <p>Your username on <?php echo esc_html($site_name); ?> has been updated.</p>
        <p>If you did not make this change, please contact our support team immediately.</p>
        <div style="margin-top: 30px; padding-top: 20px; border-top: 1px solid #eee;">
            <p><a href="<?php echo esc_url($site_url); ?>"><?php echo esc_html($site_name); ?></a></p>
        </div>
    </div>
    <?php
    return ob_get_clean();
}

5. bp_username_changer_user_has_access

Controls user access to the username change feature in BuddyPress.

Parameters:

  • $access (bool) – Current access status

Example:

add_filter('bp_username_changer_user_has_access', 'restrict_username_change_access');
function restrict_username_change_access($access) {
    // Only allow users who registered more than 30 days ago
    $user_id = get_current_user_id();
    $user_data = get_userdata($user_id);

    if ($user_data) {
        $registered = strtotime($user_data->user_registered);
        $thirty_days_ago = strtotime('-30 days');

        if ($registered > $thirty_days_ago) {
            return false; // Block access for new users
        }
    }

    return $access;
}

6. aum_username_changer_user_can_update

Controls whether a user can update their username.

Parameters:

  • $can_update (bool) – Current update permission

Example:

add_filter('aum_username_changer_user_can_update', 'conditional_username_update');
function conditional_username_update($can_update) {
    // Restrict username changes on weekends
    $day_of_week = date('N');
    if ($day_of_week >= 6) { // 6 is Saturday, 7 is Sunday
        return false;
    }

    return $can_update;
}

7. aum_bp_username_changer_template_settings

Customize the BuddyPress template used for the username change page.

Parameters:

  • $template (string) – Current template name

Example:

add_filter('aum_bp_username_changer_template_settings', 'custom_username_bp_template');
function custom_username_bp_template($template) {
    // Use a custom template for premium users
    if (is_premium_member()) {
        return 'members/single/premium/username-settings';
    }

    return $template;
}

Shortcode Integration

The plugin provides a shortcode to embed the username change form anywhere on your site.

Basic Usage

[username_manager]

Programmatic Integration

/**
 * Programmatically add the username manager form to a template
 */
function display_username_form() {
    if (function_exists('advanced_username_manager_change_username_func')) {
        echo advanced_username_manager_change_username_func([], '');
    }
}

Template Overrides

The plugin doesn’t provide specific template override functionality, but you can use the WordPress hooks system to modify the form output.

Customizing Form Output

You can use output buffers to modify the form structure:

add_action('advanced_username_manager_change_username_func', 'start_buffer_username_form', 1);
add_action('advanced_username_manager_change_username_func', 'end_buffer_username_form', 999);

function start_buffer_username_form() {
    ob_start();
}

function end_buffer_username_form() {
    $form = ob_get_clean();

    // Make modifications to the form HTML
    $form = str_replace('class="aum-standard-form"', 'class="aum-standard-form custom-form-style"', $form);

    echo $form;
}

Styling the Form

The plugin uses standardized CSS classes that can be targeted in your theme:

/* Style the username change form */
form.aum-standard-form {
    background: #f9f9f9;
    border-radius: 12px;
    padding: 25px;
    box-shadow: 0 4px 8px rgba(0,0,0,0.05);
}

/* Style the input fields */
form.aum-standard-form .aum-input-field input[type=text] {
    padding: 12px;
    border-color: #ddd;
    border-radius: 6px;
}

/* Style the submit button */
form.aum-standard-form #username_change_submit {
    background-color: #0073aa;
    color: white;
    padding: 10px 20px;
    border: none;
    border-radius: 4px;
}

JavaScript Integration

Extending Form Validation

jQuery(document).ready(function($) {
    // Add custom validation to the username field
    $(document).on('keyup', '#aum_new_user_name', function() {
        const username = $(this).val();
        const forbiddenTerms = ['admin', 'support', 'sales', 'info'];

        // Check if username contains forbidden terms
        const containsForbidden = forbiddenTerms.some(term => 
            username.toLowerCase().includes(term)
        );

        if (containsForbidden) {
            $('form.aum-standard-form p.aum-error').remove();
            $('form.aum-standard-form p.aum-success').remove();

            $("form.aum-standard-form #aum_new_user_input_field").after(
                '<p class="aum-error">Username cannot contain reserved terms.</p>'
            );

            $('#username_change_submit').attr('disabled', 'disabled');
        }
    });
});

Database Integration

Username Change Logs

The plugin creates a custom table to track username changes:

// Access username change history
global $wpdb;
$table_name = $wpdb->prefix . 'username_change_logs';

// Get username change history for a specific user
function get_username_history($user_id) {
    global $wpdb;
    $table_name = $wpdb->prefix . 'username_change_logs';

    return $wpdb->get_results(
        $wpdb->prepare(
            "SELECT * FROM {$table_name} WHERE user_id = %d ORDER BY created_date DESC",
            $user_id
        )
    );
}

// Display username history in a custom dashboard
function display_username_history() {
    $user_id = get_current_user_id();
    $history = get_username_history($user_id);

    if (!empty($history)) {
        echo '<h3>Your Username History</h3>';
        echo '<table class="username-history-table">';
        echo '<tr><th>Previous Username</th><th>New Username</th><th>Date Changed</th></tr>';

        foreach ($history as $entry) {
            echo '<tr>';
            echo '<td>' . esc_html($entry->old_username) . '</td>';
            echo '<td>' . esc_html($entry->new_username) . '</td>';
            echo '<td>' . esc_html(date_i18n(get_option('date_format'), strtotime($entry->created_date))) . '</td>';
            echo '</tr>';
        }

        echo '</table>';
    } else {
        echo '<p>You have not changed your username yet.</p>';
    }
}

BuddyPress Integration

The plugin automatically adds a “Username Change” tab to the BuddyPress settings area. You can customize its appearance or behavior.

Changing Tab Position

add_action('bp_setup_nav', 'modify_username_tab_position', 20);
function modify_username_tab_position() {
    // Get BP global
    $bp = buddypress();

    // Check if the subnav exists
    if (!empty($bp->members->nav->get('settings-nav'))) {
        // Find and rename the tab
        $subnav_items = $bp->members->nav->get_secondary(['parent_slug' => $bp->settings->slug]);

        foreach ($subnav_items as $subnav_item) {
            if ($subnav_item->slug === 'username-change') {
                // Modify properties
                $subnav_item->position = 15; // Change position
                $subnav_item->name = 'Manage Username'; // Change label
                break;
            }
        }
    }
}

WooCommerce Integration

The plugin adds a “Change username” tab to the WooCommerce My Account section.

Customizing the Tab

add_filter('woocommerce_account_menu_items', 'customize_username_tab', 20);
function customize_username_tab($menu_items) {
    if (isset($menu_items['change-username'])) {
        // Change the label
        $menu_items['change-username'] = 'Update Username';

        // Reorder the items - move username tab after dashboard
        $new_items = [];
        foreach ($menu_items as $endpoint => $label) {
            $new_items[$endpoint] = $label;

            if ($endpoint === 'dashboard') {
                // Move 'change-username' after dashboard
                unset($new_items['change-username']);
                $new_items['change-username'] = 'Update Username';
            }
        }

        return $new_items;
    }

    return $menu_items;
}

Performance Considerations

Caching Username Data

/**
 * Cache username availability check results
 */
add_action('wp_ajax_check_username_availability', 'cache_username_checks', 1);
function cache_username_checks() {
    if (!isset($_POST['username']) || !isset($_POST['nonce'])) {
        return;
    }

    $username = sanitize_text_field($_POST['username']);
    $cache_key = 'aum_username_check_' . md5($username);

    // Check if we have cached result
    $cached_result = wp_cache_get($cache_key, 'advanced_username_manager');
    if (false !== $cached_result) {
        wp_send_json_success($cached_result);
        exit;
    }

    // Let the plugin handle the check, but cache the result
    add_filter('wp_send_json_success', function($response) use ($cache_key) {
        wp_cache_set($cache_key, $response['data'], 'advanced_username_manager', 3600); // Cache for 1 hour
        return $response;
    });
}

Security Best Practices

Additional Validation

/**
 * Add extra security checks for username changes
 */
add_action('wp_ajax_aum_update_username', 'extra_username_security', 5);
function extra_username_security() {
    // Verify this is a legitimate admin
    if (!current_user_can('manage_options') && !wp_verify_nonce($_POST['nonce'], 'advanced-username-change')) {
        wp_send_json_error([
            'error_message' => 'Security check failed. Please refresh the page and try again.'
        ]);
        exit;
    }

    // Check for suspicious usernames
    if (isset($_POST['new_user_name'])) {
        $username = sanitize_text_field($_POST['new_user_name']);

        // Check for common impersonation attempts
        $protected_terms = ['admin', 'administrator', 'moderator', 'support'];
        foreach ($protected_terms as $term) {
            if (stripos($username, $term) !== false && !current_user_can('manage_options')) {
                wp_send_json_error([
                    'error_message' => 'This username is reserved for administrative purposes.'
                ]);
                exit;
            }
        }
    }
}

Troubleshooting

Debugging Username Changes

/**
 * Log username change attempts for debugging
 */
add_action('advanced_username_changed', 'log_username_changes', 10, 2);
function log_username_changes($new_username, $user) {
    if (defined('WP_DEBUG') && WP_DEBUG) {
        error_log(sprintf(
            'Username changed: User ID %d changed username to %s',
            $user->ID,
            $new_username
        ));
    }
}

Compatibility with Other Plugins

WP Members Plugin Compatibility

/**
 * Ensure compatibility with WP Members plugin
 */
add_action('wpmem_post_register_user', 'sync_username_with_wpmem', 10, 1);
function sync_username_with_wpmem($user_id) {
    // Make sure new user gets a unique identifier for BuddyPress
    if (function_exists('advanced_username_manager_set_bulk_user_profile_slug')) {
        advanced_username_manager_set_bulk_user_profile_slug([$user_id]);
    }
}

This documentation provides a comprehensive overview of the development hooks, filters, and integration points available in the Advanced Username Manager plugin. Use these tools to customize the plugin’s functionality to meet your specific requirements or to integrate with other plugins in your WordPress ecosystem.

Support

For additional support or to report issues:

Last updated: April 10, 2025