diff --git a/wp-includes/link-template.php b/wp-includes/link-template.php index e68c0aacbd..bd5b0c48d2 100644 --- a/wp-includes/link-template.php +++ b/wp-includes/link-template.php @@ -3324,3 +3324,235 @@ function the_shortlink( $text = '', $title = '', $before = '', $after = '' ) { echo $before, $link, $after; } } + + +/** + * Retrieve the avatar URL. + * + * @since 4.2.0 + * + * @param mixed $id_or_email The Gravatar to retrieve a URL for. Accepts a user_id, gravatar md5 hash, + * user email, WP_User object, WP_Post object, or comment object. + * @param array $args { + * Optional. Arguments to return instead of the default arguments. + * + * @type int $size Height and width of the avatar in pixels. Default 96. + * @type string $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 'mysterman' (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'. + * @type bool $force_default Whether to always show the default image, never the Gravatar. Default false. + * @type string $rating What rating to display avatars up to. Accepts 'G', 'PG', 'R', 'X', and are + * judged in that order. Default is the value of the 'avatar_rating' option. + * @type string $scheme URL scheme to use. See {@see set_url_scheme()} for accepted values. + * Default null. + * @type array $processed_args When the function returns, the value will be the processed/sanitized $args + * plus a "found_avatar" guess. Pass as a reference. Default null. + * } + * + * @return false|string The URL of the avatar we found, or false if we couldn't find an avatar. + */ +function get_avatar_url( $id_or_email, $args = null ) { + $args = get_avatar_data( $id_or_email, $args ); + return $args['url']; +} + +/** + * Retrieve default data about the avatar. + * + * @since 4.2.0 + * + * @param mixed $id_or_email The Gravatar to check the data against. Accepts a user_id, gravatar md5 hash, + * user email, WP_User object, WP_Post object, or comment object. + * @param array $args { + * Optional. Arguments to return instead of the default arguments. + * + * @type int $size Height and width of the avatar in pixels. Default 96. + * @type string $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 'mysterman' (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'. + * @type bool $force_default Whether to always show the default image, never the Gravatar. Default false. + * @type string $rating What rating to display avatars up to. Accepts 'G', 'PG', 'R', 'X', and are + * judged in that order. Default is the value of the 'avatar_rating' option. + * @type string $scheme URL scheme to use. See {@see set_url_scheme()} for accepted values. + * Default null. + * @type array $processed_args When the function returns, the value will be the processed/sanitized $args + * plus a "found_avatar" guess. Pass as a reference. Default null. + * } + * + * @return 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 false|string $url The URL of the avatar we found, or false if we couldn't find an avatar. + * } + */ +function get_avatar_data( $id_or_email, $args = null ) { + $args = wp_parse_args( $args, array( + 'size' => 96, + 'default' => get_option( 'avatar_default', 'mystery' ), + 'force_default' => false, + 'rating' => get_option( 'avatar_rating' ), + 'scheme' => null, + 'processed_args' => null, // if used, should be a reference + ) ); + + if ( is_numeric( $args['size'] ) ) { + $args['size'] = absint( $args['size'] ); + if ( ! $args['size'] ) { + $args['size'] = 96; + } + } else { + $args['size'] = 96; + } + + if ( empty( $args['default'] ) ) { + $args['default'] = 'mystery'; + } + + switch ( $args['default'] ) { + case 'mm' : + case 'mystery' : + case 'mysteryman' : + $args['default'] = 'mm'; + break; + case 'gravatar_default' : + $args['default'] = false; + break; + } + + $args['force_default'] = (bool) $args['force_default']; + + $args['rating'] = strtolower( $args['rating'] ); + + $args['found_avatar'] = false; + + /** + * Filter whether to retrieve the avatar URL early. + * + * Passing a non-null value in the 'url' member of the return array will + * effectively short circuit {@see get_avatar_data()}, passing the value + * through the 'get_avatar_data' filter and returning early. + * + * @since 4.2.0 + * + * @param array $args Arguments passed to get_avatar_data(), after processing. + * @param int|object|string $id_or_email A user ID, email address, or comment object. + */ + $args = apply_filters( 'pre_get_avatar_data', $args, $id_or_email ); + + if ( isset( $args['url'] ) && ! is_null( $args['url'] ) ) { + /** This filter is documented in src/wp-includes/link-template.php */ + return apply_filters( 'get_avatar_data', $args, $id_or_email ); + } + + $email_hash = ''; + $user = $email = false; + + // Process the user identifier. + if ( is_numeric( $id_or_email ) ) { + $user = get_user_by( 'id', absint( $id_or_email ) ); + } elseif ( is_string( $id_or_email ) ) { + if ( strpos( $id_or_email, '@md5.gravatar.com' ) ) { + // md5 hash + list( $email_hash ) = explode( '@', $id_or_email ); + } else { + // email address + $email = $id_or_email; + } + } elseif ( $id_or_email instanceof WP_User ) { + // User Object + $user = $id_or_email; + } elseif ( $id_or_email instanceof WP_Post ) { + // Post Object + $user = get_user_by( 'id', (int) $id_or_email->post_author ); + } elseif ( is_object( $id_or_email ) && isset( $id_or_email->comment_ID ) ) { + // Comment Object + + /** + * Filter the list of allowed comment types for retrieving avatars. + * + * @since 3.0.0 + * + * @param array $types An array of content types. Default only contains 'comment'. + */ + $allowed_comment_types = apply_filters( 'get_avatar_comment_types', array( 'comment' ) ); + if ( ! empty( $id_or_email->comment_type ) && ! in_array( $id_or_email->comment_type, (array) $allowed_comment_types ) ) { + $args['url'] = false; + /** This filter is documented in src/wp-includes/link-template.php */ + return apply_filters( 'get_avatar_data', $args, $id_or_email ); + } + + if ( ! empty( $id_or_email->user_id ) ) { + $user = get_user_by( 'id', (int) $id_or_email->user_id ); + } + if ( ( ! $user || is_wp_error( $user ) ) && ! empty( $id_or_email->comment_author_email ) ) { + $email = $id_or_email->comment_author_email; + } + } + + if ( ! $email_hash ) { + if ( $user ) { + $email = $user->user_email; + } + + if ( $email ) { + $email_hash = md5( strtolower( trim( $email ) ) ); + } + } + + if ( $email_hash ) { + $args['found_avatar'] = true; + $gravatar_server = hexdec( $email_hash[0] ) % 3; + } else { + $gravatar_server = rand( 0, 2 ); + } + + $url_args = array( + 's' => $args['size'], + 'd' => $args['default'], + 'f' => $args['force_default'] ? 'y' : false, + 'r' => $args['rating'], + ); + + $url = sprintf( 'http://%d.gravatar.com/avatar/%s', $gravatar_server, $email_hash ); + + $url = add_query_arg( + rawurlencode_deep( array_filter( $url_args ) ), + set_url_scheme( $url, $args['scheme'] ) + ); + + /** + * Filter the avatar URL. + * + * @since 4.2.0 + * + * @param string $url The URL of the avatar. + * @param int|object|string $id_or_email A user ID, email address, or comment object. + * @param array $args Arguments passed to get_avatar_data(), after processing. + */ + $args['url'] = apply_filters( 'get_avatar_url', $url, $id_or_email, $args ); + + /** + * Filter the avatar data. + * + * @since 4.2.0 + * + * @param array $args Arguments passed to get_avatar_data(), after processing. + * @param int|object|string $id_or_email A user ID, email address, or comment object. + */ + $args = apply_filters( 'get_avatar_data', $args, $id_or_email ); + + // Don't return a broken URL if we couldn't find the email hash, and none of the filters returned a different URL. + if ( ! $email_hash && $url === $args['url'] ) { + $args['url'] = false; + } + + return $args; +} diff --git a/wp-includes/pluggable.php b/wp-includes/pluggable.php index cdefc06116..a2bac5af3f 100644 --- a/wp-includes/pluggable.php +++ b/wp-includes/pluggable.php @@ -2082,123 +2082,127 @@ endif; if ( !function_exists( 'get_avatar' ) ) : /** - * Retrieve the avatar for a user who provided a user ID or email address. + * Retrieve the avatar `` tag for a user, email address, MD5 hash, comment, or post. * * @since 2.5.0 + * @since 4.2.0 Optional $args parameter added. * - * @param int|string|object $id_or_email A user ID, email address, or comment object - * @param int $size Size of the avatar image - * @param string $default URL to a default image to use if no avatar is available - * @param string $alt Alternative text to use in image tag. Defaults to blank - * @return false|string `` tag for the user's avatar. -*/ -function get_avatar( $id_or_email, $size = '96', $default = '', $alt = false ) { - if ( ! get_option('show_avatars') ) + * @param mixed $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash, + * user email, WP_User object, WP_Post object, or comment object. + * @param int $size Optional. Height and width of the avatar in pixels. Default 96. + * @param string $default Optional. 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 'mysterman' (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'. + * @param string $alt Optional. Alternative text to use in <img> tag. Default empty. + * @param array $args { + * Optional. Extra arguments to retrieve the avatar. + * + * @type bool $force_default Whether to always show the default image, never the Gravatar. Default false. + * @type string $rating What rating to display avatars up to. Accepts 'G', 'PG', 'R', 'X', and are + * judged in that order. Default is the value of the 'avatar_rating' option. + * @type string $scheme URL scheme to use. See {@see set_url_scheme()} for accepted values. + * Default null. + * @type array|string $class Array or string of additional classes to add to the <img> element. + * Default null. + * @type bool $force_display Whether to always show the avatar - ignores the show_avatars option. + * Default false. + * } + * + * @return false|string `` tag for the user's avatar. False on failure. + */ +function get_avatar( $id_or_email, $size = 96, $default = '', $alt = '', $args = null ) { + $defaults = array( + // get_avatar_data() args. + 'size' => 96, + 'default' => get_option( 'avatar_default', 'mystery' ), + 'force_default' => false, + 'rating' => get_option( 'avatar_rating' ), + 'scheme' => null, + 'alt' => '', + 'class' => null, + 'force_display' => false, + ); + + if ( empty( $args ) ) { + $args = array(); + } + + $args['size'] = $size; + $args['default'] = $default; + $args['alt'] = $alt; + + $args = wp_parse_args( $args, $defaults ); + + /** + * Filter whether to retrieve the avatar URL early. + * + * Passing a non-null value will effectively short-circuit {@see get_avatar()}, + * passing the value through the 'pre_get_avatar' filter and returning early. + * + * @since 4.2.0 + * + * @param string $avatar HTML for the user's avatar. Default null. + * @param int|object|string $id_or_email A user ID, email address, or comment object. + * @param array $args Arguments passed to get_avatar_url(), after processing. + */ + $avatar = apply_filters( 'pre_get_avatar', null, $id_or_email, $args ); + if ( ! is_null( $avatar ) ) { + /** This filter is documented in src/wp-include/pluggable.php */ + return apply_filters( 'get_avatar', $avatar, $id_or_email, $args['size'], $args['default'], $args['alt'], $args ); + } + + if ( ! $args['force_display'] && ! get_option( 'show_avatars' ) ) { return false; + } - if ( false === $alt) - $safe_alt = ''; - else - $safe_alt = esc_attr( $alt ); + $args = get_avatar_data( $id_or_email, $args ); - if ( !is_numeric($size) ) - $size = '96'; + $url = $args['url']; - $email = ''; - if ( is_numeric($id_or_email) ) { - $id = (int) $id_or_email; - $user = get_userdata($id); - if ( $user ) - $email = $user->user_email; - } elseif ( is_object($id_or_email) ) { - // No avatar for pingbacks or trackbacks + if ( ! $url || is_wp_error( $url ) ) { + return false; + } - /** - * Filter the list of allowed comment types for retrieving avatars. - * - * @since 3.0.0 - * - * @param array $types An array of content types. Default only contains 'comment'. - */ - $allowed_comment_types = apply_filters( 'get_avatar_comment_types', array( 'comment' ) ); - if ( ! empty( $id_or_email->comment_type ) && ! in_array( $id_or_email->comment_type, (array) $allowed_comment_types ) ) - return false; + $class = array( 'avatar', 'avatar-' . (int) $args['size'], 'photo' ); - if ( ! empty( $id_or_email->user_id ) ) { - $id = (int) $id_or_email->user_id; - $user = get_userdata($id); - if ( $user ) - $email = $user->user_email; + if ( ! $args['found_avatar'] || $args['force_default'] ) { + $class[] = 'avatar-default'; + } + + if ( $args['class'] ) { + if ( is_array( $args['class'] ) ) { + $class = array_merge( $class, $args['class'] ); + } else { + $class[] = $args['class']; } - - if ( ! $email && ! empty( $id_or_email->comment_author_email ) ) - $email = $id_or_email->comment_author_email; - } else { - $email = $id_or_email; } - if ( empty($default) ) { - $avatar_default = get_option('avatar_default'); - if ( empty($avatar_default) ) - $default = 'mystery'; - else - $default = $avatar_default; - } - - if ( !empty($email) ) - $email_hash = md5( strtolower( trim( $email ) ) ); - - if ( is_ssl() ) { - $host = 'https://secure.gravatar.com'; - } else { - if ( !empty($email) ) - $host = sprintf( "http://%d.gravatar.com", ( hexdec( $email_hash[0] ) % 2 ) ); - else - $host = 'http://0.gravatar.com'; - } - - if ( 'mystery' == $default ) - $default = "$host/avatar/ad516503a11cd5ca435acc9bb6523536?s={$size}"; // ad516503a11cd5ca435acc9bb6523536 == md5('unknown@gravatar.com') - elseif ( 'blank' == $default ) - $default = $email ? 'blank' : includes_url( 'images/blank.gif' ); - elseif ( !empty($email) && 'gravatar_default' == $default ) - $default = ''; - elseif ( 'gravatar_default' == $default ) - $default = "$host/avatar/?s={$size}"; - elseif ( empty($email) ) - $default = "$host/avatar/?d=$default&s={$size}"; - elseif ( strpos($default, 'http://') === 0 ) - $default = add_query_arg( 's', $size, $default ); - - if ( !empty($email) ) { - $out = "$host/avatar/"; - $out .= $email_hash; - $out .= '?s='.$size; - $out .= '&d=' . urlencode( $default ); - - $rating = get_option('avatar_rating'); - if ( !empty( $rating ) ) - $out .= "&r={$rating}"; - - $out = str_replace( '&', '&', esc_url( $out ) ); - $avatar = "{$safe_alt}"; - } else { - $out = esc_url( $default ); - $avatar = "{$safe_alt}"; - } + $avatar = sprintf( + '%s', + esc_attr( $args['alt'] ), + esc_url( $url ), + esc_attr( join( ' ', $class ) ), + (int) $args['size'], + (int) $args['size'] + ); /** * Filter the avatar to retrieve. * * @since 2.5.0 + * @since 4.2.0 $args parameter added * - * @param string $avatar Image tag for the user's avatar. - * @param int|object|string $id_or_email A user ID, email address, or comment object. - * @param int $size Square avatar width and height in pixels to retrieve. - * @param string $alt Alternative text to use in the avatar image tag. - * Default empty. + * @param string $avatar <img> tag for the user's avatar. + * @param int|object|string $id_or_email A user ID, email address, or comment object. + * @param int $size Square avatar width and height in pixels to retrieve. + * @param string $alt Alternative text to use in the avatar image tag. + * Default empty. + * @param array $args Arguments passed to get_avatar_data(), after processing. */ - return apply_filters( 'get_avatar', $avatar, $id_or_email, $size, $default, $alt ); + return apply_filters( 'get_avatar', $avatar, $id_or_email, $args['size'], $args['default'], $args['alt'], $args ); } endif; diff --git a/wp-includes/version.php b/wp-includes/version.php index 4cf619faa4..a5c4127bc9 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -4,7 +4,7 @@ * * @global string $wp_version */ -$wp_version = '4.2-alpha-31106'; +$wp_version = '4.2-alpha-31107'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.