WordPress.org
Get WordPress

Make WordPress Core

Ticket #21195: 21195.9.diff

File 21195.9.diff, 16.6 KB (added by DrewAPicture, 10 years ago)

docs pass 2

  • src/wp-includes/link-template.php

     
    31393139                echo $before, $link, $after;
    31403140        }
    31413141}
     3142
     3143/**
     3144 * Retrieve the avatar URL for a user, email address, MD5 hash, comment, or post.
     3145 *
     3146 * @since 4.1.0
     3147 *
     3148 * @param mixed $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
     3149 *                           user email, WP_User object, WP_Post object, or comment object.
     3150 * @param array $args        {
     3151 *     Optional. Extra arguments to retrieve the avatar.
     3152 *
     3153 *     @type int    $size           Height and width of the avatar in pixels. Default 96.
     3154 *     @type string $default        URL for the default image or a default type. Accepts '404' (return
     3155 *                                  a 404 instead of a default image), 'retro' (8bit), 'monsterid' (monster),
     3156 *                                  'wavatar' (cartoon face), 'indenticon' (the "quilt"), 'mystery', 'mm',
     3157 *                                  or 'mysterman' (The Oyster Man), 'blank' (transparent GIF), or
     3158 *                                  'gravatar_default' (the Gravatar logo). Default is the value of the
     3159 *                                  'avatar_default' option, with a fallback of 'mystery'.
     3160 *     @type bool   $force_default  Whether to always show the default image, never the Gravatar. Default false.
     3161 *     @type string $rating         What rating to display avatars up to. Accepts 'G', 'PG', 'R', 'X', and are
     3162 *                                  judged in that order. Default is the value of the 'avatar_rating' option.
     3163 *     @type string $scheme         URL scheme to use. See {@see set_url_scheme()} for accepted values.
     3164 *                                  Default null.
     3165 *     @type array  $processed_args When the function returns, the value will be the processed/sanitized $args
     3166 *                                  plus a "found_avatar" guess. Pass as a reference. Default null.
     3167 * }
     3168 *
     3169 * @return bool|string Avatar URL, or false on failure.
     3170 */
     3171function get_avatar_url( $id_or_email, $args = null ) {
     3172        $original_args = $args;
     3173
     3174        $args = wp_parse_args( $args, array(
     3175                'size'           => 96,
     3176                'default'        => get_option( 'avatar_default', 'mystery' ),
     3177                'force_default'  => false,
     3178                'rating'         => get_option( 'avatar_rating' ),
     3179                'scheme'         => null,
     3180                'processed_args' => null, // if used, should be a reference
     3181        ) );
     3182
     3183        if ( is_numeric( $args['size'] ) ) {
     3184                $args['size'] = absint( $args['size'] );
     3185                if ( ! $args['size'] ) {
     3186                        $args['size'] = 96;
     3187                }
     3188        } else {
     3189                $args['size'] = 96;
     3190        }
     3191
     3192        if ( empty( $args['default'] ) ) {
     3193                $args['default'] = 'mystery';
     3194        }
     3195
     3196        switch ( $args['default'] ) {
     3197                case 'mm' :
     3198                case 'mystery' :
     3199                case 'mysteryman' :
     3200                        $args['default'] = 'mm';
     3201                        break;
     3202                case 'gravatar_default' :
     3203                        $args['default'] = false;
     3204                        break;
     3205        }
     3206
     3207        $args['force_default'] = (bool) $args['force_default'];
     3208
     3209        $args['rating'] = strtolower( $args['rating'] );
     3210
     3211        $args['found_avatar'] = false;
     3212
     3213        /**
     3214         * Filter whether to retrieve the avatar URL early.
     3215         *
     3216         * Passing a non-null value will effectively short-circuit {@see get_avatar_url()},
     3217         * passing the value through the 'get_avatar_url' filter and returning early.
     3218         *
     3219         * @since 4.1.0
     3220         *
     3221         * @param string            $url           URL for the user's avatar. Default null.
     3222         * @param int|object|string $id_or_email   A user ID, email address, or comment object.
     3223         * @param array             $args          Arguments passed to get_avatar_url(), after processing.
     3224         * @param array             $original_args Original arguments passed to get_avatar_url().
     3225         */
     3226        $url = apply_filters_ref_array( 'pre_get_avatar_url', array( null, $id_or_email, &$args, $original_args ) );
     3227
     3228        if ( ! is_null( $url ) ) {
     3229                /** This filter is documented in src/wp-includes/link-template.php */
     3230                $return = apply_filters_ref_array( 'get_avatar_url', array( $url, $id_or_email, &$args, $original_args ) );
     3231                $args['processed_args'] = $args;
     3232                unset( $args['processed_args']['processed_args'] );
     3233                return $return;
     3234        }
     3235
     3236        $email_hash = '';
     3237        $user = $email = false;
     3238
     3239        // Process the user identifier.
     3240        if ( is_numeric( $id_or_email ) ) {
     3241                $user = get_user_by( 'id', absint( $id_or_email ) );
     3242        } elseif ( is_string( $id_or_email ) ) {
     3243                if ( strpos( $id_or_email, '@md5.gravatar.com' ) ) {
     3244                        // md5 hash
     3245                        list( $email_hash ) = explode( '@', $id_or_email );
     3246                } else {
     3247                        // email address
     3248                        $email = $id_or_email;
     3249                }
     3250        } elseif ( is_object( $id_or_email ) ) {
     3251                if ( isset( $id_or_email->comment_ID ) ) {
     3252                        // Comment Object
     3253
     3254                        /**
     3255                         * Filter the list of allowed comment types for retrieving avatars.
     3256                         *
     3257                         * @since 3.0.0
     3258                         *
     3259                         * @param array $types An array of content types. Default only contains 'comment'.
     3260                         */
     3261                        $allowed_comment_types = apply_filters( 'get_avatar_comment_types', array( 'comment' ) );
     3262                        if ( ! empty( $id_or_email->comment_type ) && ! in_array( $id_or_email->comment_type, (array) $allowed_comment_types ) ) {
     3263                                $args['processed_args'] = $args;
     3264                                unset( $args['processed_args']['processed_args'] );
     3265                                return false;
     3266                        }
     3267
     3268                        if ( ! empty( $id_or_email->user_id ) ) {
     3269                                $user = get_user_by( 'id', (int) $id_or_email->user_id );
     3270                        }
     3271                        if ( ( ! $user || is_wp_error( $user ) ) && ! empty( $id_or_email->comment_author_email ) ) {
     3272                                $email = $id_or_email->comment_author_email;
     3273                        }
     3274                } elseif ( ! empty( $id_or_email->user_login ) ) {
     3275                        // User Object
     3276                        $user = $id_or_email;
     3277                } elseif ( ! empty( $id_or_email->post_author ) ) {
     3278                        // Post Object
     3279                        $user = get_user_by( 'id', (int) $id_or_email->post_author );
     3280                }
     3281        }
     3282
     3283        if ( ! $email_hash ) {
     3284                if ( $user ) {
     3285                        $email = $user->user_email;
     3286                }
     3287
     3288                if ( $email ) {
     3289                        $email_hash = md5( strtolower( trim( $email ) ) );
     3290                }
     3291        }
     3292
     3293        if ( $email_hash ) {
     3294                $args['found_avatar'] = true;
     3295                $gravatar_server = hexdec( $email_hash[0] ) % 3;
     3296        } else {
     3297                $gravatar_server = rand( 0, 2 );
     3298        }
     3299
     3300        $url_args = array(
     3301                's' => $args['size'],
     3302                'd' => $args['default'],
     3303                'f' => $args['force_default'] ? 'y' : false,
     3304                'r' => $args['rating'],
     3305        );
     3306
     3307        $url = sprintf( 'http://%d.gravatar.com/avatar/%s', $gravatar_server, $email_hash );
     3308
     3309        $url = add_query_arg(
     3310                rawurlencode_deep( array_filter( $url_args ) ),
     3311                set_url_scheme( $url, $args['scheme'] )
     3312        );
     3313
     3314        /**
     3315         * Filter the avatar to retrieve.
     3316         *
     3317         * @since 4.1.0
     3318         *
     3319         * @param string            $url           URL for the user's avatar.
     3320         * @param int|object|string $id_or_email   A user ID, email address, or comment object.
     3321         * @param array             $args          Arguments passed to get_avatar_url(), after processing.
     3322         * @param array             $original_args Original arguments passed to get_avatar_url().
     3323         */
     3324        $return = apply_filters_ref_array( 'get_avatar_url', array( $url, $id_or_email, &$args, $original_args ) );
     3325
     3326        $args['processed_args'] = $args;
     3327        unset( $args['processed_args']['processed_args'] );
     3328        return $return;
     3329}

  • src/wp-includes/pluggable.php

     
    20862086
    20872087if ( !function_exists( 'get_avatar' ) ) :
    20882088/**
    2089  * Retrieve the avatar for a user who provided a user ID or email address.
     2089 * Retrieve the avatar <img> tag for a user, email address, MD5 hash, comment, or post.
    20902090 *
    20912091 * @since 2.5.0
     2092 * @since 4.1.0 Optional $args parameter added.
    20922093 *
    2093  * @param int|string|object $id_or_email A user ID,  email address, or comment object
    2094  * @param int $size Size of the avatar image
    2095  * @param string $default URL to a default image to use if no avatar is available
    2096  * @param string $alt Alternative text to use in image tag. Defaults to blank
    2097  * @return string <img> tag for the user's avatar
    2098 */
    2099 function get_avatar( $id_or_email, $size = '96', $default = '', $alt = false ) {
    2100         if ( ! get_option('show_avatars') )
    2101                 return false;
     2094 * @param mixed $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
     2095 *                           user email, WP_User object, WP_Post object, or comment object.
     2096 * @param int    $size       Optional. Height and width of the avatar in pixels. Default 96.
     2097 * @param string $default    Optional. URL for the default image or a default type. Accepts '404'
     2098 *                           (return a 404 instead of a default image), 'retro' (8bit), 'monsterid'
     2099 *                           (monster), 'wavatar' (cartoon face), 'indenticon' (the "quilt"),
     2100 *                           'mystery', 'mm', or 'mysterman' (The Oyster Man), 'blank' (transparent GIF),
     2101 *                           or 'gravatar_default' (the Gravatar logo). Default is the value of the
     2102 *                           'avatar_default' option, with a fallback of 'mystery'.
     2103 * @param string $alt        Optional. Alternative text to use in &lt;img&gt; tag. Default empty.
     2104 * @param array  $args       {
     2105 *     Optional. Extra arguments to retrieve the avatar.
     2106 *
     2107 *     @type bool         $force_default Whether to always show the default image, never the Gravatar. Default false.
     2108 *     @type string       $rating        What rating to display avatars up to. Accepts 'G', 'PG', 'R', 'X', and are
     2109 *                                       judged in that order. Default is the value of the 'avatar_rating' option.
     2110 *     @type string       $scheme        URL scheme to use. See {@see set_url_scheme()} for accepted values.
     2111 *                                       Default null.
     2112 *     @type array|string $class         Array or string of additional classes to add to the &lt;img&gt; element.
     2113 *                                       Default null.
     2114 *     @type bool         $force_display Whether to always show the avatar - ignores the show_avatars option.
     2115 *                                       Default false.
     2116 * }
     2117 *
     2118 * @return bool|string &lt;img&gt; tag for the user's avatar. False on failure.
     2119 */
     2120function get_avatar( $id_or_email, $size = 96, $default = '', $alt = '', $args = null ) {
     2121        $defaults = array(
     2122                // get_avatar_url() args.
     2123                'size'          => 96,
     2124                'default'       => get_option( 'avatar_default', 'mystery' ),
     2125                'force_default' => false,
     2126                'rating'        => get_option( 'avatar_rating' ),
     2127                'scheme'        => null,
     2128                'alt'           => '',
     2129                'class'         => null,
     2130                'force_display' => false,
     2131        );
    21022132
    2103         if ( false === $alt)
    2104                 $safe_alt = '';
    2105         else
    2106                 $safe_alt = esc_attr( $alt );
     2133        if ( empty( $args ) ) {
     2134                $args = array();
     2135        }
    21072136
    2108         if ( !is_numeric($size) )
    2109                 $size = '96';
     2137        $args['size']    = $size;
     2138        $args['default'] = $default;
     2139        $args['alt']     = $alt;
    21102140
    2111         $email = '';
    2112         if ( is_numeric($id_or_email) ) {
    2113                 $id = (int) $id_or_email;
    2114                 $user = get_userdata($id);
    2115                 if ( $user )
    2116                         $email = $user->user_email;
    2117         } elseif ( is_object($id_or_email) ) {
    2118                 // No avatar for pingbacks or trackbacks
     2141        $original_args = $args;
    21192142
    2120                 /**
    2121                  * Filter the list of allowed comment types for retrieving avatars.
    2122                  *
    2123                  * @since 3.0.0
    2124                  *
    2125                  * @param array $types An array of content types. Default only contains 'comment'.
    2126                  */
    2127                 $allowed_comment_types = apply_filters( 'get_avatar_comment_types', array( 'comment' ) );
    2128                 if ( ! empty( $id_or_email->comment_type ) && ! in_array( $id_or_email->comment_type, (array) $allowed_comment_types ) )
    2129                         return false;
     2143        $args = wp_parse_args( $args, $defaults );
    21302144
    2131                 if ( ! empty( $id_or_email->user_id ) ) {
    2132                         $id = (int) $id_or_email->user_id;
    2133                         $user = get_userdata($id);
    2134                         if ( $user )
    2135                                 $email = $user->user_email;
    2136                 }
    2137 
    2138                 if ( ! $email && ! empty( $id_or_email->comment_author_email ) )
    2139                         $email = $id_or_email->comment_author_email;
    2140         } else {
    2141                 $email = $id_or_email;
     2145        /**
     2146         * Filter whether to retrieve the avatar URL early.
     2147         *
     2148         * Passing a non-null value will effectively short-circuit {@see get_avatar()},
     2149         * passing the value through the 'pre_get_avatar' filter and returning early.
     2150         *
     2151         * @since 4.1.0
     2152         *
     2153         * @param string            $avatar        HTML for the user's avatar. Default null.
     2154         * @param int|object|string $id_or_email   A user ID, email address, or comment object.
     2155         * @param array             $args          Arguments passed to get_avatar_url(), after processing.
     2156         * @param array             $original_args Original arguments passed to get_avatar_url().
     2157         */
     2158        $avatar = apply_filters_ref_array( 'pre_get_avatar', array( null, $id_or_email, &$args, $original_args ) );
     2159        if ( ! is_null( $avatar ) ) {
     2160                /** This filter is documented in src/wp-include/pluggable.php */
     2161                return apply_filters( 'get_avatar', $avatar, $id_or_email, $args['size'], $args['default'], $args['alt'], $args, $original_args );
    21422162        }
    21432163
    2144         if ( empty($default) ) {
    2145                 $avatar_default = get_option('avatar_default');
    2146                 if ( empty($avatar_default) )
    2147                         $default = 'mystery';
    2148                 else
    2149                         $default = $avatar_default;
     2164        if ( ! $args['force_display'] && ! get_option( 'show_avatars' ) ) {
     2165                return false;
    21502166        }
    21512167
    2152         if ( !empty($email) )
    2153                 $email_hash = md5( strtolower( trim( $email ) ) );
     2168        $processed_args = null;
     2169        $args['processed_args'] =& $processed_args;
    21542170
    2155         if ( is_ssl() ) {
    2156                 $host = 'https://secure.gravatar.com';
    2157         } else {
    2158                 if ( !empty($email) )
    2159                         $host = sprintf( "http://%d.gravatar.com", ( hexdec( $email_hash[0] ) % 2 ) );
    2160                 else
    2161                         $host = 'http://0.gravatar.com';
     2171        $url = get_avatar_url( $id_or_email, $args );
     2172
     2173        if ( ! $url || is_wp_error( $url ) ) {
     2174        return false;
    21622175        }
    21632176
    2164         if ( 'mystery' == $default )
    2165                 $default = "$host/avatar/ad516503a11cd5ca435acc9bb6523536?s={$size}"; // ad516503a11cd5ca435acc9bb6523536 == md5('unknown@gravatar.com')
    2166         elseif ( 'blank' == $default )
    2167                 $default = $email ? 'blank' : includes_url( 'images/blank.gif' );
    2168         elseif ( !empty($email) && 'gravatar_default' == $default )
    2169                 $default = '';
    2170         elseif ( 'gravatar_default' == $default )
    2171                 $default = "$host/avatar/?s={$size}";
    2172         elseif ( empty($email) )
    2173                 $default = "$host/avatar/?d=$default&amp;s={$size}";
    2174         elseif ( strpos($default, 'http://') === 0 )
    2175                 $default = add_query_arg( 's', $size, $default );
     2177        $class = array( 'avatar', 'avatar-' . (int) $processed_args['size'], 'photo' );
    21762178
    2177         if ( !empty($email) ) {
    2178                 $out = "$host/avatar/";
    2179                 $out .= $email_hash;
    2180                 $out .= '?s='.$size;
    2181                 $out .= '&amp;d=' . urlencode( $default );
     2179        if ( ! $processed_args['found_avatar'] || $processed_args['force_default'] ) {
     2180        $class[] = ' avatar-default';
     2181        }
    21822182
    2183                 $rating = get_option('avatar_rating');
    2184                 if ( !empty( $rating ) )
    2185                         $out .= "&amp;r={$rating}";
    2186 
    2187                 $out = str_replace( '&#038;', '&amp;', esc_url( $out ) );
    2188                 $avatar = "<img alt='{$safe_alt}' src='{$out}' class='avatar avatar-{$size} photo' height='{$size}' width='{$size}' />";
    2189         } else {
    2190                 $out = esc_url( $default );
    2191                 $avatar = "<img alt='{$safe_alt}' src='{$out}' class='avatar avatar-{$size} photo avatar-default' height='{$size}' width='{$size}' />";
     2183        if ( $args['class'] ) {
     2184                if ( is_array( $args['class'] ) ) {
     2185                        $class = array_merge( $class, $args['class'] );
     2186                } else {
     2187                        $class[] = $args['class'];
     2188                }
    21922189        }
    21932190
     2191        $avatar = sprintf(
     2192                '<img alt="%s" src="%s" class="%s" height="%d" width="%d" />',
     2193                esc_attr( $processed_args['alt'] ),
     2194                esc_url( $url ),
     2195                esc_attr( join( ' ', $class ) ),
     2196                (int) $processed_args['size'],
     2197                (int) $processed_args['size']
     2198        );
     2199
    21942200        /**
    21952201         * Filter the avatar to retrieve.
    21962202         *
    21972203         * @since 2.5.0
    21982204         *
    2199          * @param string            $avatar      Image tag for the user's avatar.
    2200          * @param int|object|string $id_or_email A user ID, email address, or comment object.
    2201          * @param int               $size        Square avatar width and height in pixels to retrieve.
    2202          * @param string            $alt         Alternative text to use in the avatar image tag.
    2203          *                                       Default empty.
     2205         * @param string            $avatar         &lt;img&gt; tag for the user's avatar.
     2206         * @param int|object|string $id_or_email    A user ID, email address, or comment object.
     2207         * @param int               $size           Square avatar width and height in pixels to retrieve.
     2208         * @param string            $alt            Alternative text to use in the avatar image tag.
     2209         *                                          Default empty.
     2210         * @param array             $processed_args Arguments passed to get_avatar_url(), after processing. (since 4.1.0)
     2211         * @param array             $original_args  Original arguments passed to get_avatar_url(). (since 4.1.0)
    22042212         */
    2205         return apply_filters( 'get_avatar', $avatar, $id_or_email, $size, $default, $alt );
     2213        return apply_filters( 'get_avatar', $avatar, $id_or_email, $args['size'], $args['default'], $args['alt'], $processed_args, $original_args );
    22062214}
    22072215endif;
    22082216