WordPress.org

Using Gravatars

Languages: English • 日本語 • (Add your language)

What is a Gravatar?

Gravatars are Globally Recognized Avatars. An avatar or gravatar is an icon, or representation, of a user in a shared virtual reality, such as a forum, chat, website, or any other form of online community in which the user(s) wish to have something to distinguish themselves from other users. Created by Tom Werner, gravatars make it possible for a person to have one avatar across the entire web. Avatars are usually an 80px by 80px image that the user will create themselves.

Gravatars in blog post comments

A Gravatar is essentially the same thing, but they are all hosted on a single server and are called up by encrypting the users' email address via the MD5 algorithm. So instead of having one avatar on one forum you visit, and another at a blog you visit, you could have the same avatar at both.

Gravatars can easily be used within WordPress with the Gravatar WordPress Plugin or added manually in the index.php, comments.php and comments-popup.php template files.

How a Gravatar is Constructed

A Gravatar is a dynamic image resource that is requested from a server. The request URL is presented here, broken into its segments. The URL always begins with:

http://www.gravatar.com/avatar.php?

A mandatory parameter named gravatar_id follows this. Its value is the hexadecimal MD5 hash of the requested users' email address with all whitespace trimmed. The value is case insensitive.

gravatar_id=279aa12c3326f87c460aa4f31d18a065

An optional rating parameter may follow with a value of [ G | PG | R | X ] which determines the highest rating (inclusive) that will be returned.

&rating=R

Gravatar offers a rate checking service so you can determine your rate.

An optional size parameter may follow that specifies the desired width and height of the Gravatar. Valid values are from 1 to 80 inclusive. Any size other than 80 will cause the original Gravatar image to be downsampled using bicubic resampling before output.

&size=40

An optional default parameter may follow that specifies the full URL, encoded URL, protocol included, of a GIF, JPEG, or PNG image that should be returned if either the requested email address has no associated gravatar, or that Gravatar has a rating higher than is allowed by the rating parameter.

&default=http%3A%2F%2Fwww.somesite.com%2Fsomeimage.jpg

An optional border parameter may follow that specifies the hexadecimal value of a 1px border to be overlaid on the Gravatar. The supplied value may be either the full six character hex string (e.g. FF0000 for red) or the abbreviated three character hex string (e.g. F00 for red).

&border=FF0000

Using Gravatars in WordPress

An example of a Gravatar

For most people, encrypting an email address with MD5 is no easy task, most of the time requiring PHP or other form of scripting. Several WordPress Plugins have been created to help with this task, such as the Gravatar.com Plugin and Gravatars2 Enhanced Caching Plugin. For information on using and installing those WordPress Plugins, see the Plugin's documentation.

As of WordPress 2.5, Gravatars are built-in and require no additional Plugins for basic usage and management.

WordPress 2.5 marries theme authors and casual WordPress users together with support for Gravatars in the WordPress Administration Panels. Theme authors have an option to include Gravatars in their designs, and are recommended to do so. WordPress users can easily control their Gravatar usage in the Settings > Discussion Administration Panel.

WordPress users can change:

Whether Avatars (aka, Gravatars) are displayed or not.
Which rating of Avatars are shown.

Theme Support for WordPress 2.5

The function to add Gravatars to your theme is called: get_avatar. The function returns a complete image HTML tag of the Avatar.

The function is called as follows:

  <?php 
   echo get_avatar( $id_or_email, $size = '96', $default = '<path_to_url>' ); 
   ?>

The parameters are:

id_or_email (required): Author’s User ID (an integer or string), an E-mail Address (a string) or the comment object from the comment loop. Note: with most comment templates you can use $comment here, in order to display the gravatar of the commenter. In other templates within The Loop (for WordPress 2.7 and lower), you can use get_the_author_id() (deprecated in WordPress 2.8). For WordPress 2.8, please use get_the_author_meta('user_email').
size (optional): Avatar display size (max is 512).
default (optional): Absolute location of the default avatar to use (used when the person has no email address associated with them). If this is left blank then the gravatar you see here will be used as the default avatar.

Some things to note here:

The default Avatar size is 96x96 if you do not set the size using the size paramater.
The default Avatar is Gravatar
The Avatars will show only if the user allows them in the WP Admin Panel (enabled by default).
The Avatars will only show based on the rating the user has selected in the WordPress Administration Panels.

Code output:

The default output is when using the above function is listed below. Various classes are applied to img element to help you with element styling.

<img alt='' src='http://gravatarurl_or_default'
class='avatar avatar-$size' height='$size' width='$size' />

If the gravatar reverts to the default image due to a lack of an e-mail address (i.e. a pingback or trackback), whether you have specified a default or not, the img element will also be given a CSS class of avatar-default.

Backwards Compatibility

If you wish to develop a WordPress Theme with Avatars for 2.5 and below, add a check for the Gravatar function to the code:

   if (function_exists('get_avatar')) {
      echo get_avatar($email);
   } else {
      //alternate gravatar code for < 2.5
      $grav_url = "http://www.gravatar.com/avatar.php?gravatar_id=" . 
         md5($email) . "&default=" . urlencode($default) . "&size=" . $size;
      echo "<img src='$grav_url'/>";
   }

Checking for the Existence of a Gravatar

If you request a Gravatar image and the email you request doesn't have an account in the Gravatar system it returns a default image to you.

In some cases this might not be what you want, instead, you might want to know whether you will get back a real gravatar or if it will just be the default.

Example situations:

you want to show local avatars if the user has no gravatar
you want to warn users that they have no gravatar that they should sign up for one, but you don't want to bother users who are already signed up.

WARNING: You need to understand PHP to make use of the information below.

The trick to do this is to specify "404" as the default. In this case, the gravatar service will return a 404 error if no gravatar exists, instead of returning some default image. A real image will get a 200 code. It is best to check for 200, as some other errors might be returned as well, for other cases.

Here is an example validation function using HTTP headers. You will need to modify it for your needs:

function validate_gravatar($email) {
	// Craft a potential url and test its headers
	$hash = md5($email);
	$uri = 'http://www.gravatar.com/avatar/' . $hash . '?d=404';
	$headers = @get_headers($uri);
	if (!preg_match("|200|", $headers[0])) {
		$has_valid_avatar = FALSE;
	} else {
		$has_valid_avatar = TRUE;
	}
	return $has_valid_avatar;
}

Resources

WordPress.org

Codex