EasyGravatar

EasyGravatar is a simple PHP wrapper class for Gravatar that allows you to get user Avatar or Profile eaisly.

Requirements

• PHP 5.3+
• SPL
• allow_url_fopen enabled (Required for EasyGravatar\Profile)

Installation

Depends what you want to do you have to download other file (there are two).

• src/Image.php if you want to get user's avatar
• src/Profile.php if you want to get user's profile data.

If you know which file you want, put it into your include_path or include path.

Avatar

Basic Usage

Simplest way to get user's avatar requires only to call EasyGravatar\Image::getImage().
Here's some example code:

# Include Image.php file
 include 'path/to/EasyGravatar/Image.php';

# Creating EasyGravatar\Image object with specifing user's email
 $img = new EasyGravatar\Image('youremailhere@example.com');

# Get plain image URL
 echo $img->getImage();

Code above will print URL to your avatar.

TIP: If you have only hashed user e-mail or want to hash it by your own, while creating object you can pass hashed mail instead of non-hashed, it will work.

Changing result type

EasyGravatar allows you to get user's image and return in in few formats:

• EasyGravatar\Image::Plain - Returns plain URL to avatar. [default]
• EasyGravatar\Image::HTML - Returns HTML <img> tag with specified src attribute as Avatar URL and alt as $alt which is 'Avatar' by default.
• EasyGravatar\Image::BB - Returns BB [img] tag with specified URL.
• EasyGravatar\Image::Markdown - Returns image in Markdown syntax. [Since 0.1.2]

Example:

$img->getImage( EasyGravatar\Image::HTML );

Will return:

<img src="path" alt="$alt value" />

Request parameters

You can also get user's avatar with specified size, rating and others.

Size

Default size specified by EasyGravatar is 60, so if you want to get image in this size you can avoid specifing size, but if you want to use other size you can specify avatar size using EasyGravatar\Image::setSize($size); method. Some simple example:

 $img->setSize(50);

But there are also defined simple size constants:

• EasyGravatar\Image::SizeSmall - 30x30px
• EasyGravatar\Image::SizeMedium - 70x70px
• EasyGravatar\Image::SizeLarge - 120x120px

Rating

'Gravatar allows users to self-rate their images so that they can indicate if an image is appropriate for a certain audience.'. To change rating use EasyGravatar\Image::setRating($rating); method. By default rating is set to g.

$img->setRating('pg');

Constants:

• EasyGravatar\Image::RATING_G - Suitable for display on all websites with any audience type.
• EasyGravatar\Image::RATING_PG - May contain rude gestures, provocatively dressed individuals, the lesser swear words, or mild violence.
• EasyGravatar\Image::RATING_R - May contain such things as harsh profanity, intense violence, nudity, or hard drug use.
• EasyGravatar\Image::RATING_X - May contain hardcore sexual imagery or extremely disturbing violence.

Default

When avatar you want fet doesn't exists, default Gravatar image is showed. You can change default image to yours, or one of Gravatar's builded in. To change it use EasyGravatar\Image::setDefault($default);.

$img->default('http://example.com/avatars/default.png');

Constants:

• EasyGravatar\Image::MysteryMan - A simple, cartoon-style silhouetted outline of a person (does not vary by email hash)
• EasyGravatar\Image::Identicon - A geometric pattern based on an email hash
• EasyGravatar\Image::Monster - A generated 'monster' with different colors, faces, etc
• EasyGravatar\Image::Wavatar - Generated faces with differing features and backgrounds
• EasyGravatar\Image::Retro - Awesome generated, 8-bit arcade-style pixelated faces

Force default

If you you want to make default image always loaded, forceDefault can be useful here. To use forceDefault use EasyGravatar\Image::setForcedDefault($bool);.

$img->setForcedDefault(true);

Secure

If you want to display avatar from page that is served over SSL, this function can be useful. To use it, set secure to true by EasyGravatar\Image::useSecure(true);

$img->useSecure(true);

---

To make code cleaner and shorter EasyGravatar allows you to set parameters in chain. Here's some simple example:

$img->setSize(50)
	->setForcedDefault(true)
	->setRating( EasyGravatar\Image::RATING_PG )
	->useSecure(true);

Profile

Easy gravatar provides simple support for profile requests too. (Yay! :D)

Basics

EasyGravatar user profile data gathering is based on getting element from response array with specifing path. Simplest way to get user's profile data you just need to:

1. Include path/to/EasyGravatar/Profile.php
2. Create EasyGravatar\Profile object
3. Load user data using EasyGravatar\Profile::loadProfile();
4. Get data that you are interested using EasyGravatar\Profile::get($path);

In PHP it's looking like that:

# Step 1
 include 'path/to/EasyGravatar/Profile.php';
 	 
# Step 2
 $profile = new Profile('usermail@example.com');
 	 
# Step 3
 $profile->loadProfile();
 	 
# Step 4
 echo $profile->getDisplayName();

Profile fields

To get user's data you can use EasyGravatar\Profile getters. Here's list of them:

Basic:

• ID - EasyGravatar\Profile::getID();
• Hash - EasyGravatar\Profile::getHash();
• Requested Hash - EasyGravatar\Profile::getRequestedHash();
• Profile URL - EasyGravatar\Profile::getURL();
• Preferred Username - EasyGravatar\Profile::getPreferredUsername();
• Thumbnail/Avatar URL - EasyGravatar\Profile::getAvatar();
• Display Name - EasyGravatar\Profile::getDisplayName();

User info:

• About - EasyGravatar\Profile::getAboutInfo();
• Given name - EasyGravatar\Profile::getGivenName();
• Family name - EasyGravatar\Profile::getFamilyName();
• Formatted name - EasyGravatar\Profile::getFormattedName();
• Location - EasyGravatar\Profile::getLocation();

Background:

• Color - EasyGravatar\Profile::getBackgroundColor();
• Position - EasyGravatar\Profile::getBackgroundPosition();
• Repeat - EasyGravatar\Profile::getBackgroundRepeat();
• URL - EasyGravatar\Profile::getBackgroundURL();

Array-Returns:

• Photos - EasyGravatar\Profile::getPhotos();
• URLs - EasyGravatar\Profile::getURLs();
• Accounts - EasyGravatar\Profile::getAccounts();
• IMs - EasyGravatar\Profile::getIMs();
• Mails - EasyGravatar\Profile::getMails();

TIP: If you don't want to use EasyGravatar\Classname all time, type use EasyGravatar\classname; on beggining of your script.

 

TIP: If you want to print user name, use EasyGravatar\Profile::getDisplayName().

Array-return getters are returning array of items, for example EasyGravatar\Profile::getPhotos() will return array of photos.

Arrays build

Photos

Each photo array have some fields:

{
    value: [mixed],
    [type: [mixed]]
}

value - URL to photo

type - Contains "thumbnail" if photo is user's avatar [oprional]

Emails

{
	value: [mixed],
	primary: [bool as string]
}

value - E-Mail adress

primary - Is that email-primary?. Bool represented as string. Instead of true/false there is "true"/"false". So using if statement will always return true.

URLs

{
	value: [mixed],
	title: [mixed]
}

value - URL

title - URL name

IMs

{
	type: [mixed]
	value: [mixed]
}

type - IM type

value - User's IM id

Accounts

{
	domain: [mixed],
	display: [mixed],
	url: [mixed]
	username\userid: [mixed/int],
	verified: [bool as string],
	shortname: [mixed]		
}

domain - Contains domain only

display - Accound display, for example: for twitter it could be @name

url - URL to you accound on the website

username/userid - User name or id

verified - Is user verified

shortname - provider short name