get_avatar_data( mixed $id_or_email, array $args = null ): array

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 SHA-256 or MD5 hash, user email, WP_User object, WP_Post object, or WP_Comment object.

$argsarrayoptional

Arguments to use instead of the default arguments.Default: null

• $sizeintdefault: 96

  Height and width of the avatar in pixels.

• $heightint

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

• $widthint

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

• $defaultstringdefault: is the value of the 'avatar_default' option, with a fallback of 'mystery'

  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)

• $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. For Gravatars this setting is ignored and HTTPS is used to avoid unnecessary redirects. The setting is retained for systems using the 'pre_get_avatar_data' filter to customize avatars.

• $processed_argsarraydefault: null

  When the function returns, the value will be the processed/sanitized $args plus a "found_avatar" guess. Pass as a reference.

• $extra_attrstringdefault: empty

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

Return value

array

Along with the arguments passed in $args, this will contain a couple of extra arguments.

• $found_avatarbool

  True if an avatar was found for this user, false or not set if none was found.

• $urlstring|false

  The URL of the avatar that was found, or false.

Performance profile

How much work a call to get_avatar_data() 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

126–207

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

Plugin surface

3 hooks

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

Called by

3

3 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
• querycontent queryget_user_by()called directly
• cacheobject cachewp_cache_get()one call below get_avatar_data()
• serializeserialisationmaybe_unserialize()one call below get_avatar_data()

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 · 36 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost get_avatar_data() 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 · 5

5 hooks fire while get_avatar_data() runs, in this order:

1. 1
   apply_filters( pre_get_avatar_data )filterline 4492 (+77 into the body)

   Filters whether to retrieve the avatar URL early.

2. 2
   apply_filters( get_avatar_data )filterline 4496 (+81 into the body)

   Filters the avatar data.

3. 3
   apply_filters( get_avatar_data )filterline 4531 (+116 into the body)

   Filters the avatar data.

4. 4
   apply_filters( get_avatar_url )filterline 4622 (+207 into the body)

   Filters the avatar URL.

5. 5
   apply_filters( get_avatar_data )filterline 4633 (+218 into the body)

   Filters the avatar data.

Uses · 15

• wp_parse_args()Merges user defined arguments into defaults array.
• get_option()Retrieves an option value based on an option name.
• absint()Converts a value to non-negative integer.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• get_comment()Retrieves comment data given a comment ID or comment object.
• get_user_by()Retrieves user info by a given field.
• str_contains()Polyfill for `str_contains()` function added in PHP 8.0.
• is_avatar_comment_type()Check if this comment type allows avatars to be retrieved.
• get_comment_type()Retrieves the comment type of the current comment.
• is_wp_error()Checks whether the given variable is a WordPress Error.
• _x()Retrieves translated string with gettext context.
• mb_substr()Compat function to mimic mb_substr().

Used by · 3

• get_avatar()Retrieves the avatar `` tag for a user, email address, MD5 hash, comment, or post.
• get_avatar_url()Retrieves the avatar URL.
• wp_credits_section_list()Displays a list of contributors for a given group.

Source code

View on Trac ↗View on GitHub ↗

4415function get_avatar_data( $id_or_email, $args = null ) {4416	$args = wp_parse_args(4417		$args,4418		array(4419			'size'           => 96,4420			'height'         => null,4421			'width'          => null,4422			'default'        => get_option( 'avatar_default', 'mystery' ),4423			'force_default'  => false,4424			'rating'         => get_option( 'avatar_rating' ),4425			'scheme'         => null,4426			'processed_args' => null, // If used, should be a reference.4427			'extra_attr'     => '',4428		)4429	);4430 4431	if ( is_numeric( $args['size'] ) ) {4432		$args['size'] = absint( $args['size'] );4433		if ( ! $args['size'] ) {4434			$args['size'] = 96;4435		}4436	} else {4437		$args['size'] = 96;4438	}4439 4440	if ( is_numeric( $args['height'] ) ) {4441		$args['height'] = absint( $args['height'] );4442		if ( ! $args['height'] ) {4443			$args['height'] = $args['size'];4444		}4445	} else {4446		$args['height'] = $args['size'];4447	}4448 4449	if ( is_numeric( $args['width'] ) ) {4450		$args['width'] = absint( $args['width'] );4451		if ( ! $args['width'] ) {4452			$args['width'] = $args['size'];4453		}4454	} else {4455		$args['width'] = $args['size'];4456	}4457 4458	if ( empty( $args['default'] ) ) {4459		$args['default'] = get_option( 'avatar_default', 'mystery' );4460	}4461 4462	switch ( $args['default'] ) {4463		case 'mm':4464		case 'mystery':4465		case 'mysteryman':4466			$args['default'] = 'mm';4467			break;4468		case 'gravatar_default':4469			$args['default'] = false;4470			break;4471	}4472 4473	$args['force_default'] = (bool) $args['force_default'];4474 4475	$args['rating'] = strtolower( $args['rating'] );4476 4477	$args['found_avatar'] = false;4478 4479	/**4480	 * Filters whether to retrieve the avatar URL early.4481	 *4482	 * Passing a non-null value in the 'url' member of the return array will4483	 * effectively short circuit get_avatar_data(), passing the value through4484	 * the {@see 'get_avatar_data'} filter and returning early.4485	 *4486	 * @since 4.2.04487	 *4488	 * @param array $args        Arguments passed to get_avatar_data(), after processing.4489	 * @param mixed $id_or_email The avatar to retrieve. Accepts a user ID, Gravatar SHA-256 or MD5 hash,4490	 *                           user email, WP_User object, WP_Post object, or WP_Comment object.4491	 */4492	$args = apply_filters( 'pre_get_avatar_data', $args, $id_or_email );4493 4494	if ( isset( $args['url'] ) ) {

Changelog

Introduced in 4.2.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.0.4 tag, from src/wp-includes/link-template.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.