Using WordPress ‘pre_get_avatar’ PHP filter

by

pre_get_avatar is a WordPress PHP filter that allows the HTML for a user’s avatar to be returned early. By returning a non-null value, it short-circuits the get_avatar() function, passing the value through the get_avatar filter and returning early.

Usage

add_filter('pre_get_avatar', 'your_custom_function', 10, 3);

function your_custom_function($avatar, $id_or_email, $args) {
    // Your custom code here
    return $avatar;
}

Parameters

  • $avatar (string|null): HTML for the user’s avatar. Default is null.
  • $id_or_email (mixed): The avatar to retrieve. Accepts a user_id, Gravatar MD5 hash, user email, WP_User object, WP_Post object, or WP_Comment object.
  • $args (array): Arguments passed to get_avatar_url(), after processing.

Examples

Custom Default Avatar

add_filter('pre_get_avatar', 'custom_default_avatar', 10, 3);

function custom_default_avatar($avatar, $id_or_email, $args) {
    if (!$avatar) {
        $avatar = '<img src="/path/to/your/default/avatar.png" alt="Default Avatar">';
    }
    return $avatar;
}

This code snippet sets a custom default avatar when there’s no Gravatar available.

Replace Gravatar with a Local Avatar

add_filter('pre_get_avatar', 'local_user_avatar', 10, 3);

function local_user_avatar($avatar, $id_or_email, $args) {
    // Retrieve the user by ID, email or other input
    $user = get_user_by('id', $id_or_email);

    // If the user has a local avatar, use it
    if ($user && $local_avatar = get_user_meta($user->ID, 'local_avatar', true)) {
        $avatar = '<img src="' . $local_avatar . '" alt="Local Avatar">';
    }
    return $avatar;
}

This code replaces the Gravatar with a local avatar, if it’s set in the user’s metadata.

Use a Custom Image for a Specific User

add_filter('pre_get_avatar', 'custom_avatar_for_user', 10, 3);

function custom_avatar_for_user($avatar, $id_or_email, $args) {
    $user = get_user_by('id', $id_or_email);
    if ($user && $user->ID === 123) { // Replace 123 with the desired user ID
        $avatar = '<img src="/path/to/custom/avatar.png" alt="Custom Avatar">';
    }
    return $avatar;
}

This code sets a custom avatar for a specific user by ID.

Show Avatars Only for Registered Users

add_filter('pre_get_avatar', 'avatar_for_registered_users', 10, 3);

function avatar_for_registered_users($avatar, $id_or_email, $args) {
    $user = get_user_by('id', $id_or_email);
    if (!$user) {
        $avatar = null;
    }
    return $avatar;
}

This code displays avatars only for registered users and hides them for guests.

Display Avatars Based on User Role

add_filter('pre_get_avatar', 'avatar_based_on_user_role', 10, 3);
function avatar_based_on_user_role($avatar, $id_or_email, $args) {
$user = get_user_by('id', $id_or_email);
if ($user && in_array('administrator', $user->roles)) {
$avatar = '<img src="/path/to/admin/avatar.png" alt="Admin Avatar">';
} elseif ($user && in_array('subscriber', $user->roles)) {
$avatar = '<img src="/path/to/subscriber/avatar.png" alt="Subscriber Avatar">';
} else {
$avatar = null; // Hide avatar for other roles or guests
}
return $avatar;
}

This code displays different avatars based on the user’s role. It shows specific avatars for administrators and subscribers, and hides avatars for other roles or guests.