bp_core_fetch_avatar( array|string $args = '' )

Get an avatar for a BuddyPress object.


Description Description

Supports avatars for users, groups, and blogs by default, but can be extended to support custom components as well.

This function gives precedence to locally-uploaded avatars. When a local avatar is not found, Gravatar is queried. To disable Gravatar fallbacks locally: add_filter( ‘bp_core_fetch_avatar_no_grav’, ‘__return_true’ );


Top ↑

Parameters Parameters

$args

(array|string) (Optional) An array of arguments. All arguments are technically optional; some will, if not provided, be auto-detected by bp_core_fetch_avatar(). This auto-detection is described more below, when discussing specific arguments.

  • 'item_id'
    (int|bool) The numeric ID of the item for which you're requesting an avatar (eg, a user ID). If no 'item_id' is present, the function attempts to infer an ID from the 'object' + the current context: if 'object' is 'user' and the current page is a user page, 'item_id' will default to the displayed user ID; if 'group' and on a group page, to the current group ID; if 'blog', to the current blog's ID. If no 'item_id' can be determined in this way, the function returns false. Default: false.
  • 'object'
    (string) The kind of object for which you're getting an avatar. BuddyPress natively supports three options: 'user', 'group', 'blog'; a plugin may register more. Default: 'user'.
  • 'type'
    (string) When a new avatar is uploaded to BP, 'thumb' and 'full' versions are saved. This parameter specifies whether you'd like the 'full' or smaller 'thumb' avatar. Default: 'thumb'.
  • 'avatar_dir'
    (string|bool) The name of the subdirectory where the requested avatar should be found. If no value is passed, 'avatar_dir' is inferred from 'object': 'user' becomes 'avatars', 'group' becomes 'group-avatars', 'blog' becomes 'blog-avatars'. Remember that this string denotes a subdirectory of BP's main avatar directory (usually based on wp_upload_dir()); it's a string like 'group-avatars' rather than the full directory path. Generally, it'll only be necessary to override the default value if storing avatars in a non-default location. Defaults to false (auto-detected).
  • 'width'
    (int|bool) Requested avatar width. The unit is px. This value is used to build the 'width' attribute for the <img> element. If no value is passed, BP uses the global avatar width for this avatar type. Default: false (auto-detected).
  • 'height'
    (int|bool) Requested avatar height. The unit is px. This value is used to build the 'height' attribute for the <img> element. If no value is passed, BP uses the global avatar height for this avatar type. Default: false (auto-detected).
  • 'class'
    (string) The CSS class for the <img> element. Note that BP uses the 'avatar' class fairly extensively in its default styling, so if you plan to pass a custom value, consider appending it to 'avatar' (eg 'avatar foo') rather than replacing it altogether. Default: 'avatar'.
  • 'css_id'
    (string|bool) The CSS id for the <img> element. Default: false.
  • 'title'
    (string) The title attribute for the <img> element. Default: false.
  • 'alt'
    (string) The alt attribute for the <img> element. In BP, this value is generally passed by the wrapper functions, where the data necessary for concatenating the string is at hand; see bp_get_activity_avatar() for an example. Default: ''.
  • 'email'
    (string|bool) An email to use in Gravatar queries. Unless otherwise configured, BP uses Gravatar as a fallback for avatars that are not provided locally. Gravatar's API requires using a hash of the user's email address; this argument provides it. If not provided, the function will infer it: for users, by getting the user's email from the database, for groups/blogs, by concatenating "{$item_id}-{$object}@{bp_get_root_domain()}". The user query adds overhead, so it's recommended that wrapper functions provide a value for 'email' when querying user IDs. Default: false.
  • 'no_grav'
    (bool) Whether to disable the default Gravatar fallback. By default, BP will fall back on Gravatar when it cannot find a local avatar. In some cases, this may be undesirable, in which case 'no_grav' should be set to true. To disable Gravatar fallbacks globally, see the 'bp_core_fetch_avatar_no_grav' filter. Default: true for groups, otherwise false.
  • 'html'
    (bool) Whether to return an <img> HTML element, vs a raw URL to an avatar. If false, <img>-specific arguments (like 'css_id') will be ignored. Default: true.
  • 'extra_attr'
    (string) HTML attributes to insert in the IMG element. Not sanitized. Default: ''.
  • 'scheme'
    (string) URL scheme to use. See set_url_scheme() for accepted values. Default null.
  • 'rating'
    (string) What rating to display Gravatars for. Accepts 'G', 'PG', 'R', 'X'. Default is the value of the 'avatar_rating' option.
  • 'force_default'
    (bool) Used when creating the Gravatar URL. Whether to force the default image regardless if the Gravatar exists. Default: false.

Default value: ''


Top ↑

Return Return

(string) Formatted HTML <img> element, or raw avatar URL based on $html arg.


Source Source

File: bp-core/bp-core-avatars.php

function bp_core_fetch_avatar( $args = '' ) {
	$bp = buddypress();

	// If avatars are disabled for the root site, obey that request and bail.
	if ( ! $bp->avatar || ! $bp->avatar->show_avatars ) {
		return;
	}

	// Set the default variables array and parse it against incoming $args array.
	$params = wp_parse_args( $args, array(
		'item_id'       => false,
		'object'        => 'user',
		'type'          => 'thumb',
		'avatar_dir'    => false,
		'width'         => false,
		'height'        => false,
		'class'         => 'avatar',
		'css_id'        => false,
		'alt'           => '',
		'email'         => false,
		'no_grav'       => null,
		'html'          => true,
		'title'         => '',
		'extra_attr'    => '',
		'scheme'        => null,
		'rating'        => get_option( 'avatar_rating' ),
		'force_default' => false,
	) );

	/* Set item_id ***********************************************************/

	if ( empty( $params['item_id'] ) ) {

		switch ( $params['object'] ) {

			case 'blog'  :
				$params['item_id'] = get_current_blog_id();
				break;

			case 'group' :
				if ( bp_is_active( 'groups' ) ) {
					$params['item_id'] = $bp->groups->current_group->id;
				} else {
					$params['item_id'] = false;
				}

				break;

			case 'user'  :
			default      :
				$params['item_id'] = bp_displayed_user_id();
				break;
		}

		/**
		 * Filters the ID of the item being requested.
		 *
		 * @since 1.1.0
		 *
		 * @param string $value  ID of avatar item being requested.
		 * @param string $value  Avatar type being requested.
		 * @param array  $params Array of parameters for the request.
		 */
		$params['item_id'] = apply_filters( 'bp_core_avatar_item_id', $params['item_id'], $params['object'], $params );

		if ( empty( $params['item_id'] ) ) {
			return false;
		}
	}

	/* Set avatar_dir ********************************************************/

	if ( empty( $params['avatar_dir'] ) ) {

		switch ( $params['object'] ) {

			case 'blog'  :
				$params['avatar_dir'] = 'blog-avatars';
				break;

			case 'group' :
				if ( bp_is_active( 'groups' ) ) {
					$params['avatar_dir'] = 'group-avatars';
				} else {
					$params['avatar_dir'] = false;
				}

				break;

			case 'user'  :
			default      :
				$params['avatar_dir'] = 'avatars';
				break;
		}

		/**
		 * Filters the avatar directory to use.
		 *
		 * @since 1.1.0
		 *
		 * @param string $value  Name of the subdirectory where the requested avatar should be found.
		 * @param string $value  Avatar type being requested.
		 * @param array  $params Array of parameters for the request.
		 */
		$params['avatar_dir'] = apply_filters( 'bp_core_avatar_dir', $params['avatar_dir'], $params['object'], $params );

		if ( empty( $params['avatar_dir'] ) ) {
			return false;
		}
	}

	/* <img> alt *************************************************************/

	if ( false !== strpos( $params['alt'], '%s' ) || false !== strpos( $params['alt'], '%1$s' ) ) {

		switch ( $params['object'] ) {

			case 'blog'  :
				$item_name = get_blog_option( $params['item_id'], 'blogname' );
				break;

			case 'group' :
				$item_name = bp_get_group_name( groups_get_group( $params['item_id'] ) );
				break;

			case 'user'  :
			default :
				$item_name = bp_core_get_user_displayname( $params['item_id'] );
				break;
		}

		/**
		 * Filters the alt attribute value to be applied to avatar.
		 *
		 * @since 1.5.0
		 *
		 * @param string $value  alt to be applied to avatar.
		 * @param string $value  ID of avatar item being requested.
		 * @param string $value  Avatar type being requested.
		 * @param array  $params Array of parameters for the request.
		 */
		$item_name = apply_filters( 'bp_core_avatar_alt', $item_name, $params['item_id'], $params['object'], $params );
		$params['alt'] = sprintf( $params['alt'], $item_name );
	}

	/* Sanity Checks *********************************************************/

	// Get a fallback for the 'alt' parameter, create html output.
	if ( empty( $params['alt'] ) ) {
		$params['alt'] = __( 'Profile Photo', 'buddypress' );
	}
	$html_alt = ' alt="' . esc_attr( $params['alt'] ) . '"';

	// Filter image title and create html string.
	$html_title = '';

	/**
	 * Filters the title attribute value to be applied to avatar.
	 *
	 * @since 1.5.0
	 *
	 * @param string $value  Title to be applied to avatar.
	 * @param string $value  ID of avatar item being requested.
	 * @param string $value  Avatar type being requested.
	 * @param array  $params Array of parameters for the request.
	 */
	$params['title'] = apply_filters( 'bp_core_avatar_title', $params['title'], $params['item_id'], $params['object'], $params );

	if ( ! empty( $params['title'] ) ) {
		$html_title = ' title="' . esc_attr( $params['title'] ) . '"';
	}

	// Extra attributes.
	$extra_attr = '';
	if ( ! empty( $params['extra_attr'] ) ) {
		$extra_attr = ' ' . $params['extra_attr'];
	}

	// Set CSS ID and create html string.
	$html_css_id = '';

	/**
	 * Filters the ID attribute to be applied to avatar.
	 *
	 * @since 2.2.0
	 *
	 * @param string $value  ID to be applied to avatar.
	 * @param string $value  ID of avatar item being requested.
	 * @param string $value  Avatar type being requested.
	 * @param array  $params Array of parameters for the request.
	 */
	$params['css_id'] = apply_filters( 'bp_core_css_id', $params['css_id'], $params['item_id'], $params['object'], $params );

	if ( ! empty( $params['css_id'] ) ) {
		$html_css_id = ' id="' . esc_attr( $params['css_id'] ) . '"';
	}

	// Set image width.
	if ( false !== $params['width'] ) {
		// Width has been specified. No modification necessary.
	} elseif ( 'thumb' == $params['type'] ) {
		$params['width'] = bp_core_avatar_thumb_width();
	} else {
		$params['width'] = bp_core_avatar_full_width();
	}
	$html_width = ' width="' . $params['width'] . '"';

	// Set image height.
	if ( false !== $params['height'] ) {
		// Height has been specified. No modification necessary.
	} elseif ( 'thumb' == $params['type'] ) {
		$params['height'] = bp_core_avatar_thumb_height();
	} else {
		$params['height'] = bp_core_avatar_full_height();
	}
	$html_height = ' height="' . $params['height'] . '"';

	/**
	 * Filters the classes to be applied to the avatar.
	 *
	 * @since 1.6.0
	 *
	 * @param array|string $value  Class(es) to be applied to the avatar.
	 * @param string       $value  ID of the avatar item being requested.
	 * @param string       $value  Avatar type being requested.
	 * @param array        $params Array of parameters for the request.
	 */
	$params['class'] = apply_filters( 'bp_core_avatar_class', $params['class'], $params['item_id'], $params['object'], $params );

	// Use an alias to leave the param unchanged.
	$avatar_classes = $params['class'];
	if ( ! is_array( $avatar_classes ) ) {
		$avatar_classes = explode( ' ', $avatar_classes );
	}

	// Merge classes.
	$avatar_classes = array_merge( $avatar_classes, array(
		$params['object'] . '-' . $params['item_id'] . '-avatar',
		'avatar-' . $params['width'],
	) );

	// Sanitize each class.
	$avatar_classes = array_map( 'sanitize_html_class', $avatar_classes );

	// Populate the class attribute.
	$html_class = ' class="' . join( ' ', $avatar_classes ) . ' photo"';

	// Set img URL and DIR based on prepopulated constants.
	$avatar_loc        = new stdClass();
	$avatar_loc->path  = trailingslashit( bp_core_avatar_upload_path() );
	$avatar_loc->url   = trailingslashit( bp_core_avatar_url() );

	$avatar_loc->dir   = trailingslashit( $params['avatar_dir'] );

	/**
	 * Filters the avatar folder directory URL.
	 *
	 * @since 1.1.0
	 *
	 * @param string $value Path to the avatar folder URL.
	 * @param int    $value ID of the avatar item being requested.
	 * @param string $value Avatar type being requested.
	 * @param string $value Subdirectory where the requested avatar should be found.
	 */
	$avatar_folder_url = apply_filters( 'bp_core_avatar_folder_url', ( $avatar_loc->url  . $avatar_loc->dir . $params['item_id'] ), $params['item_id'], $params['object'], $params['avatar_dir'] );

	/**
	 * Filters the avatar folder directory path.
	 *
	 * @since 1.1.0
	 *
	 * @param string $value Path to the avatar folder directory.
	 * @param int    $value ID of the avatar item being requested.
	 * @param string $value Avatar type being requested.
	 * @param string $value Subdirectory where the requested avatar should be found.
	 */
	$avatar_folder_dir = apply_filters( 'bp_core_avatar_folder_dir', ( $avatar_loc->path . $avatar_loc->dir . $params['item_id'] ), $params['item_id'], $params['object'], $params['avatar_dir'] );

	/**
	 * Look for uploaded avatar first. Use it if it exists.
	 * Set the file names to search for, to select the full size
	 * or thumbnail image.
	 */
	$avatar_size              = ( 'full' == $params['type'] ) ? '-bpfull' : '-bpthumb';
	$legacy_user_avatar_name  = ( 'full' == $params['type'] ) ? '-avatar2' : '-avatar1';
	$legacy_group_avatar_name = ( 'full' == $params['type'] ) ? '-groupavatar-full' : '-groupavatar-thumb';

	// Check for directory.
	if ( ! $params['force_default'] && file_exists( $avatar_folder_dir ) ) {

		// Open directory.
		if ( $av_dir = opendir( $avatar_folder_dir ) ) {

			// Stash files in an array once to check for one that matches.
			$avatar_files = array();
			while ( false !== ( $avatar_file = readdir( $av_dir ) ) ) {
				// Only add files to the array (skip directories).
				if ( 2 < strlen( $avatar_file ) ) {
					$avatar_files[] = $avatar_file;
				}
			}

			// Check for array.
			if ( 0 < count( $avatar_files ) ) {

				// Check for current avatar.
				foreach( $avatar_files as $key => $value ) {
					if ( strpos ( $value, $avatar_size )!== false ) {
						$avatar_url = $avatar_folder_url . '/' . $avatar_files[$key];
					}
				}

				// Legacy avatar check.
				if ( !isset( $avatar_url ) ) {
					foreach( $avatar_files as $key => $value ) {
						if ( strpos ( $value, $legacy_user_avatar_name )!== false ) {
							$avatar_url = $avatar_folder_url . '/' . $avatar_files[$key];
						}
					}

					// Legacy group avatar check.
					if ( !isset( $avatar_url ) ) {
						foreach( $avatar_files as $key => $value ) {
							if ( strpos ( $value, $legacy_group_avatar_name )!== false ) {
								$avatar_url = $avatar_folder_url . '/' . $avatar_files[$key];
							}
						}
					}
				}
			}
		}

		// Close the avatar directory.
		closedir( $av_dir );

		// If we found a locally uploaded avatar.
		if ( isset( $avatar_url ) ) {
			// Support custom scheme.
			$avatar_url = set_url_scheme( $avatar_url, $params['scheme'] );

			// Return it wrapped in an <img> element.
			if ( true === $params['html'] ) {

				/**
				 * Filters an avatar URL wrapped in an <img> element.
				 *
				 * @since 1.1.0
				 *
				 * @param string $value             Full <img> element for an avatar.
				 * @param array  $params            Array of parameters for the request.
				 * @param string $value             ID of the item requested.
				 * @param string $value             Subdirectory where the requested avatar should be found.
				 * @param string $html_css_id       ID attribute for avatar.
				 * @param string $html_width        Width attribute for avatar.
				 * @param string $html_height       Height attribute for avatar.
				 * @param string $avatar_folder_url Avatar URL path.
				 * @param string $avatar_folder_dir Avatar DIR path.
				 */
				return apply_filters( 'bp_core_fetch_avatar', '<img src="' . $avatar_url . '"' . $html_class . $html_css_id  . $html_width . $html_height . $html_alt . $html_title . $extra_attr . ' />', $params, $params['item_id'], $params['avatar_dir'], $html_css_id, $html_width, $html_height, $avatar_folder_url, $avatar_folder_dir );

			// ...or only the URL
			} else {

				/**
				 * Filters a locally uploaded avatar URL.
				 *
				 * @since 1.2.5
				 *
				 * @param string $avatar_url URL for a locally uploaded avatar.
				 * @param array  $params     Array of parameters for the request.
				 */
				return apply_filters( 'bp_core_fetch_avatar_url', $avatar_url, $params );
			}
		}
	}

	// By default, Gravatar is not pinged for groups.
	if ( null === $params['no_grav'] ) {
		$params['no_grav'] = 'group' === $params['object'];
	}

	/**
	 * Filters whether or not to skip Gravatar check.
	 *
	 * @since 1.5.0
	 *
	 * @param bool  $value  Whether or not to skip Gravatar.
	 * @param array $params Array of parameters for the avatar request.
	 */
	if ( ! apply_filters( 'bp_core_fetch_avatar_no_grav', $params['no_grav'], $params ) ) {

		// Set gravatar type.
		if ( empty( $bp->grav_default->{$params['object']} ) ) {
			$default_grav = 'wavatar';
		} elseif ( 'mystery' == $bp->grav_default->{$params['object']} ) {

			/**
			 * Filters the Mystery person avatar src value.
			 *
			 * @since 1.2.0
			 *
			 * @param string $value Avatar value.
			 * @param string $value Width to display avatar at.
			 */
			$default_grav = apply_filters( 'bp_core_mysteryman_src', 'mm', $params['width'] );
		} else {
			$default_grav = $bp->grav_default->{$params['object']};
		}

		// Set gravatar object.
		if ( empty( $params['email'] ) ) {
			if ( 'user' == $params['object'] ) {
				$params['email'] = bp_core_get_user_email( $params['item_id'] );
			} elseif ( 'group' == $params['object'] || 'blog' == $params['object'] ) {
				$params['email'] = $params['item_id'] . '-' . $params['object'] . '@' . bp_get_root_domain();
			}
		}

		/**
		 * Filters the Gravatar email to use.
		 *
		 * @since 1.1.0
		 *
		 * @param string $value Email to use in Gravatar request.
		 * @param string $value ID of the item being requested.
		 * @param string $value Object type being requested.
		 */
		$params['email'] = apply_filters( 'bp_core_gravatar_email', $params['email'], $params['item_id'], $params['object'] );

		/**
		 * Filters the Gravatar URL host.
		 *
		 * @since 1.0.2
		 *
		 * @param string $value Gravatar URL host.
		 */
		$gravatar = apply_filters( 'bp_gravatar_url', '//www.gravatar.com/avatar/' );

		// Append email hash to Gravatar.
		$gravatar .=  md5( strtolower( $params['email'] ) );

		// Main Gravatar URL args.
		$url_args = array(
			's' => $params['width']
		);

		// Custom Gravatar URL args.
		if ( ! empty( $params['force_default'] ) ) {
			$url_args['f'] = 'y';
			$url_args['d'] = $params['default'];
		}
		if ( ! empty( $params['rating'] ) ) {
			$url_args['r'] = strtolower( $params['rating'] );
		}

		/** This filter is documented in wp-includes/deprecated.php */
		$d = apply_filters_deprecated(
			'bp_core_avatar_default',
			array( $default_grav, $params ),
			'8.0.0',
			'bp_core_avatar_gravatar_default||bp_core_default_avatar',
			__( 'This filter was used for 2 different purposes. If your goal was to filter the default *Gravatar*, please use `bp_core_avatar_gravatar_default` instead. Otherwise, please use `bp_core_default_avatar` instead.', 'buddypress' )
		);

		if ( bp_core_is_default_gravatar( $d ) ) {
			$default_grav = $d;
		}

		/**
		 * Filters the Gravatar "d" parameter.
		 *
		 * @since 2.6.0
		 * @since 8.0.0 The name of the filter was changed to `bp_core_avatar_gravatar_default`.
		 *
		 * @param string $default_grav The avatar default.
		 * @param array  $params       The avatar's data.
		 */
		$default_grav = apply_filters( 'bp_core_avatar_gravatar_default', $default_grav, $params );

		// Only set default image if 'Gravatar Logo' is not requested.
		if ( ! $params['force_default'] && 'gravatar_default' !== $default_grav ) {
			$url_args['d'] = $default_grav;
		}

		// Set up the Gravatar URL.
		$gravatar = esc_url( add_query_arg(
			rawurlencode_deep( array_filter( $url_args ) ),
			$gravatar
		) );

	// No avatar was found, and we've been told not to use a gravatar.
	} else {

		/**
		 * Filters the avatar default when Gravatar is not used.
		 *
		 * This is a variable filter dependent on the avatar type being requested.
		 *
		 * @since 1.5.0
		 *
		 * @param string $value  Default avatar for non-gravatar requests.
		 * @param array  $params Array of parameters for the avatar request.
		 */
		$gravatar = apply_filters( 'bp_core_default_avatar_' . $params['object'], bp_core_avatar_default( 'local', $params ), $params );
	}

	if ( true === $params['html'] ) {

		/** This filter is documented in bp-core/bp-core-avatars.php */
		return apply_filters( 'bp_core_fetch_avatar', '<img src="' . $gravatar . '"' . $html_css_id . $html_class . $html_width . $html_height . $html_alt . $html_title . $extra_attr . ' />', $params, $params['item_id'], $params['avatar_dir'], $html_css_id, $html_width, $html_height, $avatar_folder_url, $avatar_folder_dir );
	} else {

		/** This filter is documented in bp-core/bp-core-avatars.php */
		return apply_filters( 'bp_core_fetch_avatar_url', $gravatar, $params );
	}
}