get_avatar

Retrieve the avatar `` tag for a user, email address, MD5 hash, comment, or post.

Description

(false|string) get_avatar( (mixed) $id_or_email, (int) $size = 96, (string) $default = '', (string) $alt = '', (null) $args = null ); 

Returns (false|string)

`` tag for the user's avatar. False on failure.

Parameters (5)

0. $id_or_email (mixed)
The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash, user email, WP_User object, WP_Post object, or WP_Comment object.
1. $size — Optional. (int) => 96
Height and width of the avatar image file in pixels. Default 96.
2. $default — Optional. (string) => ''
URL for the default image or a default type. Accepts 404 (return a 404 instead of a default image), retro (8bit), monsterid, (monster), wavatar. (cartoon face), indenticon (the quilt), mystery, mm, or mysteryman (The Oyster Man), blank (transparent GIF), or gravatar_default (the Gravatar logo). Default is the value of the avatar_default option, with a fallback of mystery.
3. $alt — Optional. (string) => ''
Alternative text to use in <img> tag. Default empty.
4. $args — Optional. (null) => null
Extra arguments to retrieve the avatar.

Options

  • height (int) => to $size

    Display height of the avatar in pixels.

  • width (int) => to $size

    Display width of the avatar in pixels.

  • force_default (bool) => false

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

  • rating (string) => 'avatar_rating'

    What rating to display avatars up to. Accepts G,, PG, R, X, and are judged in that order.

  • scheme (string) => null

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

  • class (array|string) => null

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

  • force_display (bool) => false

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

array(

    /**
     * Display height of the avatar in pixels.
     *
     * @type int
     * @default to $size
     */
    'height' => to $size,

    /**
     * Display width of the avatar in pixels.
     *
     * @type int
     * @default to $size
     */
    'width' => to $size,

    /**
     * Whether to always show the default image, never the Gravatar.
     *
     * @type bool
     * @default false
     */
    'force_default' => false,

    /**
     * What rating to display avatars up to. Accepts 'G', 'PG', 'R', 'X', and are judged in that order.
     *
     * @type string
     * @default 'avatar_rating'
     */
    'rating' => 'avatar_rating',

    /**
     * URL scheme to use. See set_url_scheme() for accepted values.
     *
     * @type string
     * @default null
     */
    'scheme' => null,

    /**
     * Array or string of additional classes to add to the <img> element.
     *
     * @type array|string
     * @default null
     */
    'class' => null,

    /**
     * Whether to always show the avatar - ignores the show_avatars option.
     *
     * @type bool
     * @default false
     */
    'force_display' => false
);        


Usage

  1. if ( !function_exists( 'get_avatar' ) ) { 
  2. require_once ABSPATH . WPINC . '/pluggable.php'; 
  3.  
  4. // The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash, 
  5. // user email, WP_User object, WP_Post object, or WP_Comment object. 
  6. $id_or_email = null; 
  7.  
  8. // Optional. Height and width of the avatar image file in pixels. Default 96. 
  9. $size = 96; 
  10. $default = ''; 
  11.  
  12. // Optional. Alternative text to use in <img> tag. Default empty. 
  13. $alt = ''; 
  14.  
  15. // Optional. Extra arguments to retrieve the avatar. 
  16. $args = array( 
  17. 'height' => to $size, 
  18. 'width' => to $size, 
  19. 'force_default' => false, 
  20. 'rating' => 'avatar_rating', 
  21. 'scheme' => null, 
  22. 'class' => null, 
  23. 'force_display' => false 
  24. ); 
  25.  
  26. // NOTICE! Understand what this does before running. 
  27. $result = get_avatar($id_or_email, $size, $default, $alt, $args); 
  28.  

Defined (1)

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

/wp-includes/pluggable.php  
  1. function get_avatar( $id_or_email, $size = 96, $default = '', $alt = '', $args = null ) { 
  2. $defaults = array( 
  3. // get_avatar_data() args. 
  4. 'size' => 96,  
  5. 'height' => null,  
  6. 'width' => null,  
  7. 'default' => get_option( 'avatar_default', 'mystery' ),  
  8. 'force_default' => false,  
  9. 'rating' => get_option( 'avatar_rating' ),  
  10. 'scheme' => null,  
  11. 'alt' => '',  
  12. 'class' => null,  
  13. 'force_display' => false,  
  14. 'extra_attr' => '',  
  15. ); 
  16.  
  17. if ( empty( $args ) ) { 
  18. $args = array(); 
  19.  
  20. $args['size'] = (int) $size; 
  21. $args['default'] = $default; 
  22. $args['alt'] = $alt; 
  23.  
  24. $args = wp_parse_args( $args, $defaults ); 
  25.  
  26. if ( empty( $args['height'] ) ) { 
  27. $args['height'] = $args['size']; 
  28. if ( empty( $args['width'] ) ) { 
  29. $args['width'] = $args['size']; 
  30.  
  31. if ( is_object( $id_or_email ) && isset( $id_or_email->comment_ID ) ) { 
  32. $id_or_email = get_comment( $id_or_email ); 
  33.  
  34. /** 
  35. * Filters whether to retrieve the avatar URL early. 
  36. * Passing a non-null value will effectively short-circuit get_avatar(), passing 
  37. * the value through the {@see 'get_avatar'} filter and returning early. 
  38. * @since 4.2.0 
  39. * @param string $avatar HTML for the user's avatar. Default null. 
  40. * @param mixed $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,  
  41. * user email, WP_User object, WP_Post object, or WP_Comment object. 
  42. * @param array $args Arguments passed to get_avatar_url(), after processing. 
  43. */ 
  44. $avatar = apply_filters( 'pre_get_avatar', null, $id_or_email, $args ); 
  45.  
  46. if ( ! is_null( $avatar ) ) { 
  47. /** This filter is documented in wp-includes/pluggable.php */ 
  48. return apply_filters( 'get_avatar', $avatar, $id_or_email, $args['size'], $args['default'], $args['alt'], $args ); 
  49.  
  50. if ( ! $args['force_display'] && ! get_option( 'show_avatars' ) ) { 
  51. return false; 
  52.  
  53. $url2x = get_avatar_url( $id_or_email, array_merge( $args, array( 'size' => $args['size'] * 2 ) ) ); 
  54.  
  55. $args = get_avatar_data( $id_or_email, $args ); 
  56.  
  57. $url = $args['url']; 
  58.  
  59. if ( ! $url || is_wp_error( $url ) ) { 
  60. return false; 
  61.  
  62. $class = array( 'avatar', 'avatar-' . (int) $args['size'], 'photo' ); 
  63.  
  64. if ( ! $args['found_avatar'] || $args['force_default'] ) { 
  65. $class[] = 'avatar-default'; 
  66.  
  67. if ( $args['class'] ) { 
  68. if ( is_array( $args['class'] ) ) { 
  69. $class = array_merge( $class, $args['class'] ); 
  70. } else { 
  71. $class[] = $args['class']; 
  72.  
  73. $avatar = sprintf( 
  74. "<img alt='%s' src='%s' srcset='%s' class='%s' height='%d' width='%d' %s/>",  
  75. esc_attr( $args['alt'] ),  
  76. esc_url( $url ),  
  77. esc_attr( "$url2x 2x" ),  
  78. esc_attr( join( ' ', $class ) ),  
  79. (int) $args['height'],  
  80. (int) $args['width'],  
  81. $args['extra_attr'] 
  82. ); 
  83.  
  84. /** 
  85. * Filters the avatar to retrieve. 
  86. * @since 2.5.0 
  87. * @since 4.2.0 The `$args` parameter was added. 
  88. * @param string $avatar <img> tag for the user's avatar. 
  89. * @param mixed $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,  
  90. * user email, WP_User object, WP_Post object, or WP_Comment object. 
  91. * @param int $size Square avatar width and height in pixels to retrieve. 
  92. * @param string $alt Alternative text to use in the avatar image tag. 
  93. * Default empty. 
  94. * @param array $args Arguments passed to get_avatar_data(), after processing. 
  95. */ 
  96. return apply_filters( 'get_avatar', $avatar, $id_or_email, $args['size'], $args['default'], $args['alt'], $args );