get_avatar_data

Retrieves default data about the avatar.

Description

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

Returns (array)

$processed_args { Along with the arguments passed in `$args`, this will contain a couple of extra arguments. @type bool $found_avatar True if we were able to find an avatar for this user, false or not set if we couldn't. @type string $url The URL of the avatar we found. }

Parameters (2)

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. $args — Optional. (null) => null
Arguments to return instead of the default arguments.

Options

  • size (int) => 96

    Height and width of the avatar image file in pixels.

  • height (int) => to $size

    Display height of the avatar in pixels.

  • width (int) => to $size

    Display width of the avatar in pixels.

  • default (string) => 'avatar_default'

    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).

  • 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.

  • processed_args (array) => null

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

array(

    /**
     * Height and width of the avatar image file in pixels.
     *
     * @type int
     * @default 96
     */
    'size' => 96,

    /**
     * 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,

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

    /**
     * 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,

    /**
     * When the function returns, the value will be the processed/sanitized $args plus a
     * "found_avatar" guess. Pass as a reference.
     *
     * @type array
     * @default null
     */
    'processed_args' => null
);        


Usage

  1. if ( !function_exists( 'get_avatar_data' ) ) { 
  2. require_once ABSPATH . WPINC . '/link-template.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. Arguments to return instead of the default arguments. 
  9. $args = array( 
  10. 'size' => 96, 
  11. 'height' => to $size, 
  12. 'width' => to $size, 
  13. 'default' => 'avatar_default', 
  14. 'force_default' => false, 
  15. 'rating' => 'avatar_rating', 
  16. 'scheme' => null, 
  17. 'processed_args' => null 
  18. ); 
  19.  
  20. // NOTICE! Understand what this does before running. 
  21. $result = get_avatar_data($id_or_email, $args); 
  22.  

Defined (1)

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

/wp-includes/link-template.php  
  1. function get_avatar_data( $id_or_email, $args = null ) { 
  2. $args = wp_parse_args( $args, array( 
  3. 'size' => 96,  
  4. 'height' => null,  
  5. 'width' => null,  
  6. 'default' => get_option( 'avatar_default', 'mystery' ),  
  7. 'force_default' => false,  
  8. 'rating' => get_option( 'avatar_rating' ),  
  9. 'scheme' => null,  
  10. 'processed_args' => null, // if used, should be a reference 
  11. 'extra_attr' => '',  
  12. ) ); 
  13.  
  14. if ( is_numeric( $args['size'] ) ) { 
  15. $args['size'] = absint( $args['size'] ); 
  16. if ( ! $args['size'] ) { 
  17. $args['size'] = 96; 
  18. } else { 
  19. $args['size'] = 96; 
  20.  
  21. if ( is_numeric( $args['height'] ) ) { 
  22. $args['height'] = absint( $args['height'] ); 
  23. if ( ! $args['height'] ) { 
  24. $args['height'] = $args['size']; 
  25. } else { 
  26. $args['height'] = $args['size']; 
  27.  
  28. if ( is_numeric( $args['width'] ) ) { 
  29. $args['width'] = absint( $args['width'] ); 
  30. if ( ! $args['width'] ) { 
  31. $args['width'] = $args['size']; 
  32. } else { 
  33. $args['width'] = $args['size']; 
  34.  
  35. if ( empty( $args['default'] ) ) { 
  36. $args['default'] = get_option( 'avatar_default', 'mystery' ); 
  37.  
  38. switch ( $args['default'] ) { 
  39. case 'mm' : 
  40. case 'mystery' : 
  41. case 'mysteryman' : 
  42. $args['default'] = 'mm'; 
  43. break; 
  44. case 'gravatar_default' : 
  45. $args['default'] = false; 
  46. break; 
  47.  
  48. $args['force_default'] = (bool) $args['force_default']; 
  49.  
  50. $args['rating'] = strtolower( $args['rating'] ); 
  51.  
  52. $args['found_avatar'] = false; 
  53.  
  54. /** 
  55. * Filters whether to retrieve the avatar URL early. 
  56. * Passing a non-null value in the 'url' member of the return array will 
  57. * effectively short circuit get_avatar_data(), passing the value through 
  58. * the {@see 'get_avatar_data'} filter and returning early. 
  59. * @since 4.2.0 
  60. * @param array $args Arguments passed to get_avatar_data(), after processing. 
  61. * @param mixed $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,  
  62. * user email, WP_User object, WP_Post object, or WP_Comment object. 
  63. */ 
  64. $args = apply_filters( 'pre_get_avatar_data', $args, $id_or_email ); 
  65.  
  66. if ( isset( $args['url'] ) && ! is_null( $args['url'] ) ) { 
  67. /** This filter is documented in wp-includes/link-template.php */ 
  68. return apply_filters( 'get_avatar_data', $args, $id_or_email ); 
  69.  
  70. $email_hash = ''; 
  71. $user = $email = false; 
  72.  
  73. if ( is_object( $id_or_email ) && isset( $id_or_email->comment_ID ) ) { 
  74. $id_or_email = get_comment( $id_or_email ); 
  75.  
  76. // Process the user identifier. 
  77. if ( is_numeric( $id_or_email ) ) { 
  78. $user = get_user_by( 'id', absint( $id_or_email ) ); 
  79. } elseif ( is_string( $id_or_email ) ) { 
  80. if ( strpos( $id_or_email, '@md5.gravatar.com' ) ) { 
  81. // md5 hash 
  82. list( $email_hash ) = explode( '@', $id_or_email ); 
  83. } else { 
  84. // email address 
  85. $email = $id_or_email; 
  86. } elseif ( $id_or_email instanceof WP_User ) { 
  87. // User Object 
  88. $user = $id_or_email; 
  89. } elseif ( $id_or_email instanceof WP_Post ) { 
  90. // Post Object 
  91. $user = get_user_by( 'id', (int) $id_or_email->post_author ); 
  92. } elseif ( $id_or_email instanceof WP_Comment ) { 
  93. /** 
  94. * Filters the list of allowed comment types for retrieving avatars. 
  95. * @since 3.0.0 
  96. * @param array $types An array of content types. Default only contains 'comment'. 
  97. */ 
  98. $allowed_comment_types = apply_filters( 'get_avatar_comment_types', array( 'comment' ) ); 
  99. if ( ! empty( $id_or_email->comment_type ) && ! in_array( $id_or_email->comment_type, (array) $allowed_comment_types ) ) { 
  100. $args['url'] = false; 
  101. /** This filter is documented in wp-includes/link-template.php */ 
  102. return apply_filters( 'get_avatar_data', $args, $id_or_email ); 
  103.  
  104. if ( ! empty( $id_or_email->user_id ) ) { 
  105. $user = get_user_by( 'id', (int) $id_or_email->user_id ); 
  106. if ( ( ! $user || is_wp_error( $user ) ) && ! empty( $id_or_email->comment_author_email ) ) { 
  107. $email = $id_or_email->comment_author_email; 
  108.  
  109. if ( ! $email_hash ) { 
  110. if ( $user ) { 
  111. $email = $user->user_email; 
  112.  
  113. if ( $email ) { 
  114. $email_hash = md5( strtolower( trim( $email ) ) ); 
  115.  
  116. if ( $email_hash ) { 
  117. $args['found_avatar'] = true; 
  118. $gravatar_server = hexdec( $email_hash[0] ) % 3; 
  119. } else { 
  120. $gravatar_server = rand( 0, 2 ); 
  121.  
  122. $url_args = array( 
  123. 's' => $args['size'],  
  124. 'd' => $args['default'],  
  125. 'f' => $args['force_default'] ? 'y' : false,  
  126. 'r' => $args['rating'],  
  127. ); 
  128.  
  129. if ( is_ssl() ) { 
  130. $url = 'https://secure.gravatar.com/avatar/' . $email_hash; 
  131. } else { 
  132. $url = sprintf( 'http://%d.gravatar.com/avatar/%s', $gravatar_server, $email_hash ); 
  133.  
  134. $url = add_query_arg
  135. rawurlencode_deep( array_filter( $url_args ) ),  
  136. set_url_scheme( $url, $args['scheme'] ) 
  137. ); 
  138.  
  139. /** 
  140. * Filters the avatar URL. 
  141. * @since 4.2.0 
  142. * @param string $url The URL of the avatar. 
  143. * @param mixed $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,  
  144. * user email, WP_User object, WP_Post object, or WP_Comment object. 
  145. * @param array $args Arguments passed to get_avatar_data(), after processing. 
  146. */ 
  147. $args['url'] = apply_filters( 'get_avatar_url', $url, $id_or_email, $args ); 
  148.  
  149. /** 
  150. * Filters the avatar data. 
  151. * @since 4.2.0 
  152. * @param array $args Arguments passed to get_avatar_data(), after processing. 
  153. * @param mixed $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,  
  154. * user email, WP_User object, WP_Post object, or WP_Comment object. 
  155. */ 
  156. return apply_filters( 'get_avatar_data', $args, $id_or_email );