bp_core_fetch_avatar

Get an avatar for a BuddyPress object.

Description

(string) bp_core_fetch_avatar( (string) $args = '' ); 

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:

Returns (string)

Formatted HTML element, or raw avatar URL based on $html arg.

Parameters (1)

0. $args — Optional. (string) => ''
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.

Options

  • item_id (int|bool) => 0

    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 .

array(

    /**
     * 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.
     *
     * @type int|bool
     */
    'item_id' => 0,

    /**
     * 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
     * @default ''
     */
    'object' => '',

    /**
     * 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'.
     *
     * @type string
     * @default ''
     */
    'type' => ''
);        


Usage

  1. if ( !function_exists( 'bp_core_fetch_avatar' ) ) { 
  2. require_once ABSPATH . PLUGINDIR . 'buddypress/bp-core/bp-core-avatars.php'; 
  3.  
  4. // 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. 
  5. $args = array( 
  6. 'item_id' => 0, 
  7. 'object' => '', 
  8. 'type' => '' 
  9. ); 
  10.  
  11. // NOTICE! Understand what this does before running. 
  12. $result = bp_core_fetch_avatar($args); 
  13.  

Defined (1)

The function is defined in the following location(s).

/bp-core/bp-core-avatars.php  
  1. function bp_core_fetch_avatar( $args = '' ) { 
  2. $bp =buddypress); 
  3.  
  4. // If avatars are disabled for the root site, obey that request and bail. 
  5. if ( ! $bp->avatar->show_avatars ) { 
  6. return; 
  7.  
  8. global $current_blog; 
  9.  
  10. // Set the default variables array and parse it against incoming $args array. 
  11. $params = wp_parse_args( $args, array( 
  12. 'item_id' => false,  
  13. 'object' => 'user',  
  14. 'type' => 'thumb',  
  15. 'avatar_dir' => false,  
  16. 'width' => false,  
  17. 'height' => false,  
  18. 'class' => 'avatar',  
  19. 'css_id' => false,  
  20. 'alt' => '',  
  21. 'email' => false,  
  22. 'no_grav' => null,  
  23. 'html' => true,  
  24. 'title' => '',  
  25. 'extra_attr' => '',  
  26. 'scheme' => null,  
  27. 'rating' => get_option( 'avatar_rating' ),  
  28. 'force_default' => false,  
  29. ) ); 
  30.  
  31. /** Set item_id ***********************************************************/ 
  32.  
  33. if ( empty( $params['item_id'] ) ) { 
  34.  
  35. switch ( $params['object'] ) { 
  36.  
  37. case 'blog' : 
  38. $params['item_id'] = $current_blog->id; 
  39. break; 
  40.  
  41. case 'group' : 
  42. if ( bp_is_active( 'groups' ) ) { 
  43. $params['item_id'] = $bp->groups->current_group->id; 
  44. } else { 
  45. $params['item_id'] = false; 
  46.  
  47. break; 
  48.  
  49. case 'user' : 
  50. default : 
  51. $params['item_id'] = bp_displayed_user_id(); 
  52. break; 
  53.  
  54. /** 
  55. * Filters the ID of the item being requested. 
  56. * @since 1.1.0 
  57. * @param string $value ID of avatar item being requested. 
  58. * @param string $value Avatar type being requested. 
  59. * @param array $params Array of parameters for the request. 
  60. */ 
  61. $params['item_id'] = apply_filters( 'bp_core_avatar_item_id', $params['item_id'], $params['object'], $params ); 
  62.  
  63. if ( empty( $params['item_id'] ) ) { 
  64. return false; 
  65.  
  66. /** Set avatar_dir ********************************************************/ 
  67.  
  68. if ( empty( $params['avatar_dir'] ) ) { 
  69.  
  70. switch ( $params['object'] ) { 
  71.  
  72. case 'blog' : 
  73. $params['avatar_dir'] = 'blog-avatars'; 
  74. break; 
  75.  
  76. case 'group' : 
  77. if ( bp_is_active( 'groups' ) ) { 
  78. $params['avatar_dir'] = 'group-avatars'; 
  79. } else { 
  80. $params['avatar_dir'] = false; 
  81.  
  82. break; 
  83.  
  84. case 'user' : 
  85. default : 
  86. $params['avatar_dir'] = 'avatars'; 
  87. break; 
  88.  
  89. /** 
  90. * Filters the avatar directory to use. 
  91. * @since 1.1.0 
  92. * @param string $value Name of the subdirectory where the requested avatar should be found. 
  93. * @param string $value Avatar type being requested. 
  94. * @param array $params Array of parameters for the request. 
  95. */ 
  96. $params['avatar_dir'] = apply_filters( 'bp_core_avatar_dir', $params['avatar_dir'], $params['object'], $params ); 
  97.  
  98. if ( empty( $params['avatar_dir'] ) ) { 
  99. return false; 
  100.  
  101. /** <img> alt *************************************************************/ 
  102.  
  103. if ( false !== strpos( $params['alt'], '%s' ) || false !== strpos( $params['alt'], '%1$s' ) ) { 
  104.  
  105. switch ( $params['object'] ) { 
  106.  
  107. case 'blog' : 
  108. $item_name = get_blog_option( $params['item_id'], 'blogname' ); 
  109. break; 
  110.  
  111. case 'group' : 
  112. $item_name = bp_get_group_name( groups_get_group( $params['item_id'] ) ); 
  113. break; 
  114.  
  115. case 'user' : 
  116. default : 
  117. $item_name = bp_core_get_user_displayname( $params['item_id'] ); 
  118. break; 
  119.  
  120. /** 
  121. * Filters the alt attribute value to be applied to avatar. 
  122. * @since 1.5.0 
  123. * @param string $value alt to be applied to avatar. 
  124. * @param string $value ID of avatar item being requested. 
  125. * @param string $value Avatar type being requested. 
  126. * @param array $params Array of parameters for the request. 
  127. */ 
  128. $item_name = apply_filters( 'bp_core_avatar_alt', $item_name, $params['item_id'], $params['object'], $params ); 
  129. $params['alt'] = sprintf( $params['alt'], $item_name ); 
  130.  
  131. /** Sanity Checks *********************************************************/ 
  132.  
  133. // Get a fallback for the 'alt' parameter, create html output. 
  134. if ( empty( $params['alt'] ) ) { 
  135. $params['alt'] = __( 'Profile Photo', buddypress ); 
  136. $html_alt = ' alt="' . esc_attr( $params['alt'] ) . '"'; 
  137.  
  138. // Filter image title and create html string. 
  139. $html_title = ''; 
  140.  
  141. /** 
  142. * Filters the title attribute value to be applied to avatar. 
  143. * @since 1.5.0 
  144. * @param string $value Title to be applied to avatar. 
  145. * @param string $value ID of avatar item being requested. 
  146. * @param string $value Avatar type being requested. 
  147. * @param array $params Array of parameters for the request. 
  148. */ 
  149. $params['title'] = apply_filters( 'bp_core_avatar_title', $params['title'], $params['item_id'], $params['object'], $params ); 
  150.  
  151. if ( ! empty( $params['title'] ) ) { 
  152. $html_title = ' title="' . esc_attr( $params['title'] ) . '"'; 
  153.  
  154. // Extra attributes. 
  155. $extra_attr = ! empty( $args['extra_attr'] ) ? ' ' . $args['extra_attr'] : ''; 
  156.  
  157. // Set CSS ID and create html string. 
  158. $html_css_id = ''; 
  159.  
  160. /** 
  161. * Filters the ID attribute to be applied to avatar. 
  162. * @since 2.2.0 
  163. * @param string $value ID to be applied to avatar. 
  164. * @param string $value ID of avatar item being requested. 
  165. * @param string $value Avatar type being requested. 
  166. * @param array $params Array of parameters for the request. 
  167. */ 
  168. $params['css_id'] = apply_filters( 'bp_core_css_id', $params['css_id'], $params['item_id'], $params['object'], $params ); 
  169.  
  170. if ( ! empty( $params['css_id'] ) ) { 
  171. $html_css_id = ' id="' . esc_attr( $params['css_id'] ) . '"'; 
  172.  
  173. // Set image width. 
  174. if ( false !== $params['width'] ) { 
  175. // Width has been specified. No modification necessary. 
  176. } elseif ( 'thumb' == $params['type'] ) { 
  177. $params['width'] = bp_core_avatar_thumb_width(); 
  178. } else { 
  179. $params['width'] = bp_core_avatar_full_width(); 
  180. $html_width = ' width="' . $params['width'] . '"'; 
  181.  
  182. // Set image height. 
  183. if ( false !== $params['height'] ) { 
  184. // Height has been specified. No modification necessary. 
  185. } elseif ( 'thumb' == $params['type'] ) { 
  186. $params['height'] = bp_core_avatar_thumb_height(); 
  187. } else { 
  188. $params['height'] = bp_core_avatar_full_height(); 
  189. $html_height = ' height="' . $params['height'] . '"'; 
  190.  
  191. /** 
  192. * Filters the classes to be applied to the avatar. 
  193. * @since 1.6.0 
  194. * @param array|string $value Class(es) to be applied to the avatar. 
  195. * @param string $value ID of the avatar item being requested. 
  196. * @param string $value Avatar type being requested. 
  197. * @param array $params Array of parameters for the request. 
  198. */ 
  199. $params['class'] = apply_filters( 'bp_core_avatar_class', $params['class'], $params['item_id'], $params['object'], $params ); 
  200.  
  201. // Use an alias to leave the param unchanged. 
  202. $avatar_classes = $params['class']; 
  203. if ( ! is_array( $avatar_classes ) ) { 
  204. $avatar_classes = explode( ' ', $avatar_classes ); 
  205.  
  206. // Merge classes. 
  207. $avatar_classes = array_merge( $avatar_classes, array( 
  208. $params['object'] . '-' . $params['item_id'] . '-avatar',  
  209. 'avatar-' . $params['width'],  
  210. ) ); 
  211.  
  212. // Sanitize each class. 
  213. $avatar_classes = array_map( 'sanitize_html_class', $avatar_classes ); 
  214.  
  215. // Populate the class attribute. 
  216. $html_class = ' class="' . join( ' ', $avatar_classes ) . ' photo"'; 
  217.  
  218. // Set img URL and DIR based on prepopulated constants. 
  219. $avatar_loc = new stdClass(); 
  220. $avatar_loc->path = trailingslashit( bp_core_avatar_upload_path() ); 
  221. $avatar_loc->url = trailingslashit( bp_core_avatar_url() ); 
  222.  
  223. $avatar_loc->dir = trailingslashit( $params['avatar_dir'] ); 
  224.  
  225. /** 
  226. * Filters the avatar folder directory URL. 
  227. * @since 1.1.0 
  228. * @param string $value Path to the avatar folder URL. 
  229. * @param int $value ID of the avatar item being requested. 
  230. * @param string $value Avatar type being requested. 
  231. * @param string $value Subdirectory where the requested avatar should be found. 
  232. */ 
  233. $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'] ); 
  234.  
  235. /** 
  236. * Filters the avatar folder directory path. 
  237. * @since 1.1.0 
  238. * @param string $value Path to the avatar folder directory. 
  239. * @param int $value ID of the avatar item being requested. 
  240. * @param string $value Avatar type being requested. 
  241. * @param string $value Subdirectory where the requested avatar should be found. 
  242. */ 
  243. $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'] ); 
  244.  
  245. /** 
  246. * Look for uploaded avatar first. Use it if it exists. 
  247. * Set the file names to search for, to select the full size 
  248. * or thumbnail image. 
  249. */ 
  250. $avatar_size = ( 'full' == $params['type'] ) ? '-bpfull' : '-bpthumb'; 
  251. $legacy_user_avatar_name = ( 'full' == $params['type'] ) ? '-avatar2' : '-avatar1'; 
  252. $legacy_group_avatar_name = ( 'full' == $params['type'] ) ? '-groupavatar-full' : '-groupavatar-thumb'; 
  253.  
  254. // Check for directory. 
  255. if ( file_exists( $avatar_folder_dir ) ) { 
  256.  
  257. // Open directory. 
  258. if ( $av_dir = opendir( $avatar_folder_dir ) ) { 
  259.  
  260. // Stash files in an array once to check for one that matches. 
  261. $avatar_files = array(); 
  262. while ( false !== ( $avatar_file = readdir( $av_dir ) ) ) { 
  263. // Only add files to the array (skip directories). 
  264. if ( 2 < strlen( $avatar_file ) ) { 
  265. $avatar_files[] = $avatar_file; 
  266.  
  267. // Check for array. 
  268. if ( 0 < count( $avatar_files ) ) { 
  269.  
  270. // Check for current avatar. 
  271. foreach( $avatar_files as $key => $value ) { 
  272. if ( strpos ( $value, $avatar_size )!== false ) { 
  273. $avatar_url = $avatar_folder_url . '/' . $avatar_files[$key]; 
  274.  
  275. // Legacy avatar check. 
  276. if ( !isset( $avatar_url ) ) { 
  277. foreach( $avatar_files as $key => $value ) { 
  278. if ( strpos ( $value, $legacy_user_avatar_name )!== false ) { 
  279. $avatar_url = $avatar_folder_url . '/' . $avatar_files[$key]; 
  280.  
  281. // Legacy group avatar check. 
  282. if ( !isset( $avatar_url ) ) { 
  283. foreach( $avatar_files as $key => $value ) { 
  284. if ( strpos ( $value, $legacy_group_avatar_name )!== false ) { 
  285. $avatar_url = $avatar_folder_url . '/' . $avatar_files[$key]; 
  286.  
  287. // Close the avatar directory. 
  288. closedir( $av_dir ); 
  289.  
  290. // If we found a locally uploaded avatar. 
  291. if ( isset( $avatar_url ) ) { 
  292. // Support custom scheme. 
  293. $avatar_url = set_url_scheme( $avatar_url, $params['scheme'] ); 
  294.  
  295. // Return it wrapped in an <img> element. 
  296. if ( true === $params['html'] ) { 
  297.  
  298. /** 
  299. * Filters an avatar URL wrapped in an <img> element. 
  300. * @since 1.1.0 
  301. * @param string $value Full <img> element for an avatar. 
  302. * @param array $params Array of parameters for the request. 
  303. * @param string $value ID of the item requested. 
  304. * @param string $value Subdirectory where the requested avatar should be found. 
  305. * @param string $html_css_id ID attribute for avatar. 
  306. * @param string $html_width Width attribute for avatar. 
  307. * @param string $html_height Height attribute for avatar. 
  308. * @param string $avatar_folder_url Avatar URL path. 
  309. * @param string $avatar_folder_dir Avatar DIR path. 
  310. */ 
  311. 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 ); 
  312.  
  313. // ...or only the URL 
  314. } else { 
  315.  
  316. /** 
  317. * Filters a locally uploaded avatar URL. 
  318. * @since 1.2.5 
  319. * @param string $avatar_url URL for a locally uploaded avatar. 
  320. * @param array $params Array of parameters for the request. 
  321. */ 
  322. return apply_filters( 'bp_core_fetch_avatar_url', $avatar_url, $params ); 
  323.  
  324. // By default, Gravatar is not pinged for groups. 
  325. if ( null === $params['no_grav'] ) { 
  326. $params['no_grav'] = 'group' === $params['object']; 
  327.  
  328. /** 
  329. * Filters whether or not to skip Gravatar check. 
  330. * @since 1.5.0 
  331. * @param bool $value Whether or not to skip Gravatar. 
  332. * @param array $params Array of parameters for the avatar request. 
  333. */ 
  334. if ( ! apply_filters( 'bp_core_fetch_avatar_no_grav', $params['no_grav'], $params ) ) { 
  335.  
  336. // Set gravatar type. 
  337. if ( empty( $bp->grav_default->{$params['object']} ) ) { 
  338. $default_grav = 'wavatar'; 
  339. } elseif ( 'mystery' == $bp->grav_default->{$params['object']} ) { 
  340.  
  341. /** 
  342. * Filters the Mystery person avatar src value. 
  343. * @since 1.2.0 
  344. * @param string $value Avatar value. 
  345. * @param string $value Width to display avatar at. 
  346. */ 
  347. $default_grav = apply_filters( 'bp_core_mysteryman_src', 'mm', $params['width'] ); 
  348. } else { 
  349. $default_grav = $bp->grav_default->{$params['object']}; 
  350.  
  351. // Set gravatar object. 
  352. if ( empty( $params['email'] ) ) { 
  353. if ( 'user' == $params['object'] ) { 
  354. $params['email'] = bp_core_get_user_email( $params['item_id'] ); 
  355. } elseif ( 'group' == $params['object'] || 'blog' == $params['object'] ) { 
  356. $params['email'] = $params['item_id'] . '-' . $params['object'] . '@' . bp_get_root_domain(); 
  357.  
  358. /** 
  359. * Filters the Gravatar email to use. 
  360. * @since 1.1.0 
  361. * @param string $value Email to use in Gravatar request. 
  362. * @param string $value ID of the item being requested. 
  363. * @param string $value Object type being requested. 
  364. */ 
  365. $params['email'] = apply_filters( 'bp_core_gravatar_email', $params['email'], $params['item_id'], $params['object'] ); 
  366.  
  367. /** 
  368. * Filters the Gravatar URL host. 
  369. * @since 1.0.2 
  370. * @param string $value Gravatar URL host. 
  371. */ 
  372. $gravatar = apply_filters( 'bp_gravatar_url', '//www.gravatar.com/avatar/' ); 
  373.  
  374. // Append email hash to Gravatar. 
  375. $gravatar .= md5( strtolower( $params['email'] ) ); 
  376.  
  377. // Main Gravatar URL args. 
  378. $url_args = array( 
  379. 's' => $params['width'] 
  380. ); 
  381.  
  382. // Custom Gravatar URL args. 
  383. if ( ! empty( $params['force_default'] ) ) { 
  384. $url_args['f'] = 'y'; 
  385. if ( ! empty( $params['rating'] ) ) { 
  386. $url_args['r'] = strtolower( $params['rating'] ); 
  387.  
  388. /** 
  389. * Filters the Gravatar "d" parameter. 
  390. * @since 2.6.0 
  391. * @param string $default_grav The avatar default. 
  392. * @param array $params The avatar's data. 
  393. */ 
  394. $default_grav = apply_filters( 'bp_core_avatar_default', $default_grav, $params ); 
  395.  
  396. // Only set default image if 'Gravatar Logo' is not requested. 
  397. if ( 'gravatar_default' !== $default_grav ) { 
  398. $url_args['d'] = $default_grav; 
  399.  
  400. // Set up the Gravatar URL. 
  401. $gravatar = esc_url( add_query_arg
  402. rawurlencode_deep( array_filter( $url_args ) ),  
  403. $gravatar 
  404. ) ); 
  405.  
  406. // No avatar was found, and we've been told not to use a gravatar. 
  407. } else { 
  408.  
  409. /** 
  410. * Filters the avatar default when Gravatar is not used. 
  411. * This is a variable filter dependent on the avatar type being requested. 
  412. * @since 1.5.0 
  413. * @param string $value Default avatar for non-gravatar requests. 
  414. * @param array $params Array of parameters for the avatar request. 
  415. */ 
  416.  
  417. if ( true === $params['html'] ) { 
  418.  
  419. /** This filter is documented in bp-core/bp-core-avatars.php */ 
  420. 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 ); 
  421. } else { 
  422.  
  423. /** This filter is documented in bp-core/bp-core-avatars.php */ 
  424. return apply_filters( 'bp_core_fetch_avatar_url', $gravatar, $params );