get_avatar( mixed $id_or_email, int $size = 96, string $default_value = '', string $alt = '', array $args = null ): string|false

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$id_or_emailmixed

The avatar to retrieve. Accepts a user ID, Gravatar MD5 hash, user email, WP_User object, WP_Post object, or WP_Comment object.

$sizeintoptional

Height and width of the avatar in pixels. Default 96.Default: 96

$default_valuestringoptional

URL for the default image or a default type. Accepts:
- '404' (return a 404 instead of a default image)
- 'retro' (a 8-bit arcade-style pixelated face)
- 'robohash' (a robot)
- 'monsterid' (a monster)
- 'wavatar' (a cartoon face)
- 'identicon' (the "quilt", a geometric pattern)
- 'initials' (initials based avatar with background color)
- 'color' (generated background color)
- 'mystery', 'mm', or 'mysteryman' (The Oyster Man)
- 'blank' (transparent GIF)
- 'gravatar_default' (the Gravatar logo) Default is the value of the 'avatar_default' option, with a fallback of 'mystery'.Default: ''

$altstringoptional

Alternative text to use in the avatar image tag.
Default empty.Default: ''

$argsarrayoptional

Extra arguments to retrieve the avatar.Default: null

• $heightint

  Display height of the avatar in pixels. Defaults to $size.

• $widthint

  Display width of the avatar in pixels. Defaults to $size.

• $force_defaultbooldefault: false

  Whether to always show the default image, never the Gravatar.

• $ratingstringdefault: is the value of the 'avatar_rating' option

  What rating to display avatars up to. Accepts:

  • 'G' (suitable for all audiences)
  • 'PG' (possibly offensive, usually for audiences 13 and above)
  • 'R' (intended for adult audiences above 17)
  • 'X' (even more mature than above)

• $schemestringdefault: null

  URL scheme to use. See set_url_scheme() for accepted values.

• $classarray|stringdefault: null

  Array or string of additional classes to add to the img element.

• $force_displaybooldefault: false

  Whether to always show the avatar - ignores the show_avatars option.

• $loadingstringdefault: null

  Value for the loading attribute.

• $fetchprioritystringdefault: null

  Value for the fetchpriority attribute.

• $decodingstringdefault: null

  Value for the decoding attribute.

• $extra_attrstringdefault: empty

  HTML attributes to insert in the IMG element. Is not sanitized.

Return value

string|false

<img> tag for the user's avatar. False on failure.

Performance profile

How much work a call to get_avatar() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Heavy

Reaches the database via get_user_by().

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

74–214

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 248.

Plugin surface

2 hooks

Third-party callbacks on 'pre_get_avatar', 'get_avatar' run inside this call, and their cost is not bounded by anything here.

Called by

24

24 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• optionoption read or writeget_option()called directly
• hookthird-party callbacksapply_filters()called directly
• cacheobject cachewp_cache_get()one call below get_avatar()
• serializeserialisationmaybe_unserialize()one call below get_avatar()
• querycontent queryget_user_by()one call below get_avatar()

Further down the call graph this can also reach transient. That is the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 10 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost get_avatar() can have, taken from its control-flow graph on PHP 8.5.

This body has more branch combinations than are worth enumerating, so the table covers the outcomes found first rather than every one that exists.

Hooks and filters fired · 3

3 hooks fire while get_avatar() runs, in this order:

1. 1
   apply_filters( pre_get_avatar )filterline 3255 (+58 into the body)

   Allows the HTML for a user's avatar to be returned early.

2. 2
   apply_filters( get_avatar )filterline 3259 (+62 into the body)

   Filters the HTML for a user's avatar.

3. 3
   apply_filters( get_avatar )filterline 3357 (+160 into the body)

   Filters the HTML for a user's avatar.

Uses · 10

• get_option()Retrieves an option value based on an option name.
• wp_parse_args()Merges user defined arguments into defaults array.
• wp_get_loading_optimization_attributes()Gets loading optimization attributes.
• get_comment()Retrieves comment data given a comment ID or comment object.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• get_avatar_url()Retrieves the avatar URL.
• get_avatar_data()Retrieves default data about the avatar.
• is_wp_error()Checks whether the given variable is a WordPress Error.
• esc_attr()Escaping for HTML attributes.
• esc_url()Checks and cleans a URL.

Used by · 24

• TwentyNineteen_Walker_Comment::html5_comment()Outputs a comment in the HTML5 format.
• TwentyTwenty_Walker_Comment::html5_comment()Outputs a comment in the HTML5 format.
• WP_Comments_List_Table::floated_admin_avatar()Adds avatars to comment author names.
• WP_MS_Users_List_Table::column_username()Handles the username column output.
• WP_Posts_List_Table::column_title()Handles the title column output.
• WP_Users_List_Table::single_row()Generates HTML for a single row on the users.php admin panel.
• Walker_Comment::comment()Outputs a single comment.
• Walker_Comment::html5_comment()Outputs a comment in the HTML5 format.
• _admin_notice_post_locked()Outputs the HTML for the notice to say that someone else is editing or has taken over editing of this post.
• _wp_dashboard_recent_comments_row()Outputs a row for the Recent Comments widget.
• floated_admin_avatar()Adds avatars to relevant places in admin.
• render_block_core_avatar()Renders the `core/avatar` block on the server.

Source code

View on Trac ↗View on GitHub ↗

3197	function get_avatar( $id_or_email, $size = 96, $default_value = '', $alt = '', $args = null ) {3198		$defaults = array(3199			// get_avatar_data() args.3200			'size'          => 96,3201			'height'        => null,3202			'width'         => null,3203			'default'       => get_option( 'avatar_default', 'mystery' ),3204			'force_default' => false,3205			'rating'        => get_option( 'avatar_rating' ),3206			'scheme'        => null,3207			'alt'           => '',3208			'class'         => null,3209			'force_display' => false,3210			'loading'       => null,3211			'fetchpriority' => null,3212			'decoding'      => null,3213			'extra_attr'    => '',3214		);3215 3216		if ( empty( $args ) ) {3217			$args = array();3218		}3219 3220		$args['size']    = (int) $size;3221		$args['default'] = $default_value;3222		$args['alt']     = $alt;3223 3224		$args = wp_parse_args( $args, $defaults );3225 3226		if ( empty( $args['height'] ) ) {3227			$args['height'] = $args['size'];3228		}3229		if ( empty( $args['width'] ) ) {3230			$args['width'] = $args['size'];3231		}3232 3233		// Update args with loading optimized attributes.3234		$loading_optimization_attr = wp_get_loading_optimization_attributes( 'img', $args, 'get_avatar' );3235 3236		$args = array_merge( $args, $loading_optimization_attr );3237 3238		if ( is_object( $id_or_email ) && isset( $id_or_email->comment_ID ) ) {3239			$id_or_email = get_comment( $id_or_email );3240		}3241 3242		/**3243		 * Allows the HTML for a user's avatar to be returned early.3244		 *3245		 * Returning a non-null value will effectively short-circuit get_avatar(), passing3246		 * the value through the {@see 'get_avatar'} filter and returning early.3247		 *3248		 * @since 4.2.03249		 *3250		 * @param string|null $avatar      HTML for the user's avatar. Default null.3251		 * @param mixed       $id_or_email The avatar to retrieve. Accepts a user ID, Gravatar MD5 hash,3252		 *                                 user email, WP_User object, WP_Post object, or WP_Comment object.3253		 * @param array       $args        Arguments passed to get_avatar_url(), after processing.3254		 */3255		$avatar = apply_filters( 'pre_get_avatar', null, $id_or_email, $args );3256 3257		if ( ! is_null( $avatar ) ) {3258			/** This filter is documented in wp-includes/pluggable.php */3259			return apply_filters( 'get_avatar', $avatar, $id_or_email, $args['size'], $args['default'], $args['alt'], $args );3260		}3261 3262		if ( ! $args['force_display'] && ! get_option( 'show_avatars' ) ) {3263			return false;3264		}3265 3266		$url2x = get_avatar_url( $id_or_email, array_merge( $args, array( 'size' => $args['size'] * 2 ) ) );3267 3268		$args = get_avatar_data( $id_or_email, $args );3269 3270		$url = $args['url'];3271 3272		if ( ! $url || is_wp_error( $url ) ) {3273			return false;3274		}3275 3276		$class = array( 'avatar', 'avatar-' . (int) $args['size'], 'photo' );

Changelog

Introduced in 2.5.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.1.0 tag, from src/wp-includes/pluggable.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.