Docs: Improve documentation for `get_avatar()` and related functions.
Includes: * Expanding and synchronizing documentation for the `default` and `rating` arguments. * Adding `@since` entries for the `loading`, `fetchpriority`, and `decoding` arguments. * Wrapping long lines as per the documentation standards. * Fixing a typo in the `identicon` value. * Minor formatting edits for consistency. Follow-up to [31107], [45632], [47554], [53480], [56037]. See #58833. Built from https://develop.svn.wordpress.org/trunk@56767 git-svn-id: http://core.svn.wordpress.org/trunk@56279 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Sergey Biryukov
parent
2a2cbb3b49
commit
f2a85f2b2c
|
|
@ -4250,27 +4250,37 @@ function the_shortlink( $text = '', $title = '', $before = '', $after = '' ) {
|
|||
}
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Retrieves 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,
|
||||
* @param mixed $id_or_email The avatar to retrieve a URL for. Accepts a user ID, Gravatar MD5 hash,
|
||||
* user email, WP_User object, WP_Post object, or WP_Comment object.
|
||||
* @param array $args {
|
||||
* Optional. Arguments to use 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), 'RoboHash' (robohash),
|
||||
* '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'.
|
||||
* @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 $default URL for the default image or a default type. Accepts:
|
||||
* - '404' (return a 404 instead of a default image)
|
||||
* - 'retro' (a 8-bit arcade-style pixelated face)
|
||||
* - 'robohash' (a robot)
|
||||
* - 'monsterid' (a monster)
|
||||
* - 'wavatar' (a cartoon face)
|
||||
* - 'identicon' (the "quilt", a geometric pattern)
|
||||
* - 'mystery', 'mm', or 'mysteryman' (The Oyster Man)
|
||||
* - 'blank' (transparent GIF)
|
||||
* - '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' (suitable for all audiences)
|
||||
* - 'PG' (possibly offensive, usually for audiences 13 and above)
|
||||
* - 'R' (intended for adult audiences above 17)
|
||||
* - 'X' (even more mature than above)
|
||||
* Default is the value of the 'avatar_rating' option.
|
||||
* @type string $scheme URL scheme to use. 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
|
||||
|
|
@ -4283,7 +4293,6 @@ function get_avatar_url( $id_or_email, $args = null ) {
|
|||
return $args['url'];
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Check if this comment type allows avatars to be retrieved.
|
||||
*
|
||||
|
|
@ -4305,7 +4314,6 @@ function is_avatar_comment_type( $comment_type ) {
|
|||
return in_array( $comment_type, (array) $allowed_comment_types, true );
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Retrieves default data about the avatar.
|
||||
*
|
||||
|
|
@ -4316,23 +4324,35 @@ function is_avatar_comment_type( $comment_type ) {
|
|||
* @param array $args {
|
||||
* Optional. Arguments to use instead of the default arguments.
|
||||
*
|
||||
* @type int $size Height and width of the avatar image file in pixels. Default 96.
|
||||
* @type int $size Height and width of the avatar in pixels. Default 96.
|
||||
* @type int $height Display height of the avatar in pixels. Defaults to $size.
|
||||
* @type int $width Display width of the avatar in pixels. Defaults to $size.
|
||||
* @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 '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'.
|
||||
* @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 $default URL for the default image or a default type. Accepts:
|
||||
* - '404' (return a 404 instead of a default image)
|
||||
* - 'retro' (a 8-bit arcade-style pixelated face)
|
||||
* - 'robohash' (a robot)
|
||||
* - 'monsterid' (a monster)
|
||||
* - 'wavatar' (a cartoon face)
|
||||
* - 'identicon' (the "quilt", a geometric pattern)
|
||||
* - 'mystery', 'mm', or 'mysteryman' (The Oyster Man)
|
||||
* - 'blank' (transparent GIF)
|
||||
* - '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' (suitable for all audiences)
|
||||
* - 'PG' (possibly offensive, usually for audiences 13 and above)
|
||||
* - 'R' (intended for adult audiences above 17)
|
||||
* - 'X' (even more mature than above)
|
||||
* Default is the value of the 'avatar_rating' option.
|
||||
* @type string $scheme URL scheme to use. 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.
|
||||
* @type string $extra_attr HTML attributes to insert in the IMG element. Is not sanitized. Default empty.
|
||||
* @type string $extra_attr HTML attributes to insert in the IMG element. Is not sanitized.
|
||||
* Default empty.
|
||||
* }
|
||||
* @return array {
|
||||
* Along with the arguments passed in `$args`, this will contain a couple of extra arguments.
|
||||
|
|
|
|||
|
|
@ -2797,26 +2797,41 @@ if ( ! function_exists( 'get_avatar' ) ) :
|
|||
* Retrieves the avatar `<img>` tag for a user, email address, MD5 hash, comment, or post.
|
||||
*
|
||||
* @since 2.5.0
|
||||
* @since 4.2.0 Optional `$args` parameter added.
|
||||
* @since 4.2.0 Added the optional `$args` parameter.
|
||||
* @since 5.5.0 Added the `loading` argument.
|
||||
* @since 6.1.0 Added the `decoding` argument.
|
||||
* @since 6.3.0 Added the `fetchpriority` argument.
|
||||
*
|
||||
* @param mixed $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
|
||||
* @param mixed $id_or_email The avatar to retrieve. Accepts a user ID, Gravatar MD5 hash,
|
||||
* user email, WP_User object, WP_Post object, or WP_Comment object.
|
||||
* @param int $size Optional. Height and width of the avatar image file in pixels. Default 96.
|
||||
* @param string $default_value URL for the default image or a default type. Accepts '404' (return
|
||||
* a 404 instead of a default image), 'retro' (8bit), 'RoboHash' (robohash),
|
||||
* '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'.
|
||||
* @param string $alt Optional. Alternative text to use in img tag. Default empty.
|
||||
* @param int $size Optional. Height and width of the avatar in pixels. Default 96.
|
||||
* @param string $default_value URL for the default image or a default type. Accepts:
|
||||
* - '404' (return a 404 instead of a default image)
|
||||
* - 'retro' (a 8-bit arcade-style pixelated face)
|
||||
* - 'robohash' (a robot)
|
||||
* - 'monsterid' (a monster)
|
||||
* - 'wavatar' (a cartoon face)
|
||||
* - 'identicon' (the "quilt", a geometric pattern)
|
||||
* - 'mystery', 'mm', or 'mysteryman' (The Oyster Man)
|
||||
* - 'blank' (transparent GIF)
|
||||
* - '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 the avatar image tag.
|
||||
* Default empty.
|
||||
* @param array $args {
|
||||
* Optional. Extra arguments to retrieve the avatar.
|
||||
*
|
||||
* @type int $height Display height of the avatar in pixels. Defaults to $size.
|
||||
* @type int $width Display width of the avatar in pixels. Defaults to $size.
|
||||
* @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 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' (suitable for all audiences)
|
||||
* - 'PG' (possibly offensive, usually for audiences 13 and above)
|
||||
* - 'R' (intended for adult audiences above 17)
|
||||
* - 'X' (even more mature than above)
|
||||
* Default is the value of the 'avatar_rating' option.
|
||||
* @type string $scheme URL scheme to use. 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.
|
||||
|
|
@ -2825,7 +2840,12 @@ if ( ! function_exists( 'get_avatar' ) ) :
|
|||
* Default false.
|
||||
* @type string $loading Value for the `loading` attribute.
|
||||
* Default null.
|
||||
* @type string $extra_attr HTML attributes to insert in the IMG element. Is not sanitized. Default empty.
|
||||
* @type string $fetchpriority Value for the `fetchpriority` attribute.
|
||||
* Default null.
|
||||
* @type string $decoding Value for the `decoding` attribute.
|
||||
* Default null.
|
||||
* @type string $extra_attr HTML attributes to insert in the IMG element. Is not sanitized.
|
||||
* Default empty.
|
||||
* }
|
||||
* @return string|false `<img>` tag for the user's avatar. False on failure.
|
||||
*/
|
||||
|
|
@ -2844,8 +2864,8 @@ if ( ! function_exists( 'get_avatar' ) ) :
|
|||
'force_display' => false,
|
||||
'loading' => null,
|
||||
'fetchpriority' => null,
|
||||
'extra_attr' => '',
|
||||
'decoding' => null,
|
||||
'extra_attr' => '',
|
||||
);
|
||||
|
||||
if ( empty( $args ) ) {
|
||||
|
|
@ -2883,7 +2903,7 @@ if ( ! function_exists( 'get_avatar' ) ) :
|
|||
* @since 4.2.0
|
||||
*
|
||||
* @param string|null $avatar HTML for the user's avatar. Default null.
|
||||
* @param mixed $id_or_email The avatar to retrieve. Accepts a user_id, Gravatar MD5 hash,
|
||||
* @param mixed $id_or_email The avatar to retrieve. Accepts a user ID, Gravatar MD5 hash,
|
||||
* user email, WP_User object, WP_Post object, or WP_Comment object.
|
||||
* @param array $args Arguments passed to get_avatar_url(), after processing.
|
||||
*/
|
||||
|
|
@ -2922,7 +2942,7 @@ if ( ! function_exists( 'get_avatar' ) ) :
|
|||
}
|
||||
}
|
||||
|
||||
// Add `loading`, `fetchpriority` and `decoding` attributes.
|
||||
// Add `loading`, `fetchpriority`, and `decoding` attributes.
|
||||
$extra_attr = $args['extra_attr'];
|
||||
|
||||
if ( in_array( $args['loading'], array( 'lazy', 'eager' ), true )
|
||||
|
|
@ -2935,17 +2955,6 @@ if ( ! function_exists( 'get_avatar' ) ) :
|
|||
$extra_attr .= "loading='{$args['loading']}'";
|
||||
}
|
||||
|
||||
if ( in_array( $args['decoding'], array( 'async', 'sync', 'auto' ), true )
|
||||
&& ! preg_match( '/\bdecoding\s*=/', $extra_attr )
|
||||
) {
|
||||
if ( ! empty( $extra_attr ) ) {
|
||||
$extra_attr .= ' ';
|
||||
}
|
||||
|
||||
$extra_attr .= "decoding='{$args['decoding']}'";
|
||||
}
|
||||
|
||||
// Add support for `fetchpriority`.
|
||||
if ( in_array( $args['fetchpriority'], array( 'high', 'low', 'auto' ), true )
|
||||
&& ! preg_match( '/\bfetchpriority\s*=/', $extra_attr )
|
||||
) {
|
||||
|
|
@ -2956,6 +2965,16 @@ if ( ! function_exists( 'get_avatar' ) ) :
|
|||
$extra_attr .= "fetchpriority='{$args['fetchpriority']}'";
|
||||
}
|
||||
|
||||
if ( in_array( $args['decoding'], array( 'async', 'sync', 'auto' ), true )
|
||||
&& ! preg_match( '/\bdecoding\s*=/', $extra_attr )
|
||||
) {
|
||||
if ( ! empty( $extra_attr ) ) {
|
||||
$extra_attr .= ' ';
|
||||
}
|
||||
|
||||
$extra_attr .= "decoding='{$args['decoding']}'";
|
||||
}
|
||||
|
||||
$avatar = sprintf(
|
||||
"<img alt='%s' src='%s' srcset='%s' class='%s' height='%d' width='%d' %s/>",
|
||||
esc_attr( $args['alt'] ),
|
||||
|
|
@ -2971,14 +2990,22 @@ if ( ! function_exists( 'get_avatar' ) ) :
|
|||
* Filters the HTML for a user's avatar.
|
||||
*
|
||||
* @since 2.5.0
|
||||
* @since 4.2.0 The `$args` parameter was added.
|
||||
* @since 4.2.0 Added the `$args` parameter.
|
||||
*
|
||||
* @param string $avatar HTML for the user's avatar.
|
||||
* @param mixed $id_or_email The avatar to retrieve. Accepts a user_id, Gravatar MD5 hash,
|
||||
* @param mixed $id_or_email The avatar to retrieve. Accepts a user ID, Gravatar MD5 hash,
|
||||
* user email, WP_User object, WP_Post object, or WP_Comment object.
|
||||
* @param int $size Square avatar width and height in pixels to retrieve.
|
||||
* @param string $default_value URL for the default image or a default type. Accepts '404', 'retro', 'monsterid',
|
||||
* 'wavatar', 'indenticon', 'mystery', 'mm', 'mysteryman', 'blank', or 'gravatar_default'.
|
||||
* @param int $size Height and width of the avatar in pixels.
|
||||
* @param string $default_value URL for the default image or a default type. Accepts:
|
||||
* - '404' (return a 404 instead of a default image)
|
||||
* - 'retro' (a 8-bit arcade-style pixelated face)
|
||||
* - 'robohash' (a robot)
|
||||
* - 'monsterid' (a monster)
|
||||
* - 'wavatar' (a cartoon face)
|
||||
* - 'identicon' (the "quilt", a geometric pattern)
|
||||
* - 'mystery', 'mm', or 'mysteryman' (The Oyster Man)
|
||||
* - 'blank' (transparent GIF)
|
||||
* - 'gravatar_default' (the Gravatar logo)
|
||||
* @param string $alt Alternative text to use in the avatar image tag.
|
||||
* @param array $args Arguments passed to get_avatar_data(), after processing.
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -1215,13 +1215,13 @@ function rest_add_application_passwords_to_index( $response ) {
|
|||
}
|
||||
|
||||
/**
|
||||
* Retrieves the avatar urls in various sizes.
|
||||
* Retrieves the avatar URLs in various sizes.
|
||||
*
|
||||
* @since 4.7.0
|
||||
*
|
||||
* @see get_avatar_url()
|
||||
*
|
||||
* @param mixed $id_or_email The Gravatar to retrieve a URL for. Accepts a user_id, gravatar md5 hash,
|
||||
* @param mixed $id_or_email The avatar to retrieve a URL for. Accepts a user ID, Gravatar MD5 hash,
|
||||
* user email, WP_User object, WP_Post object, or WP_Comment object.
|
||||
* @return (string|false)[] Avatar URLs keyed by size. Each value can be a URL string or boolean false.
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@
|
|||
*
|
||||
* @global string $wp_version
|
||||
*/
|
||||
$wp_version = '6.4-beta1-56766';
|
||||
$wp_version = '6.4-beta1-56767';
|
||||
|
||||
/**
|
||||
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.
|
||||
|
|
|
|||
Loading…
Reference in New Issue