README

GravatarLib是一个小型库，旨在提供简单的Gravatar提供的头像集成。

版权

(c) 2011 emberlabs.org

许可证

此库采用MIT许可证；您可以在文件/LICENCE中找到许可证的完整副本。

需求

• PHP 5.3.0或更高版本
• hash()函数必须可用，同时需要md5算法

使用方法

我们假设您将此git仓库用作git子模块，并根据命名空间规则将其放置在includes/emberlabs/GravatarLib/，以便于自动加载。

通用示例

	<?php
	include __DIR__ . '/includes/emberlabs/GravatarLib/Gravatar.php';
    $gravatar = new \emberlabs\GravatarLib\Gravatar();
	// example: setting default image and maximum size
	$gravatar->setDefaultImage('mm')
		->setAvatarSize(150);
	// example: setting maximum allowed avatar rating
	$gravatar->setMaxRating('pg');
	$avatar = $gravatar->buildGravatarURL('someemail@domain.com');

设置默认图像

Gravatar提供了几个预制的默认图像，用于当提供的电子邮件地址没有Gravatar或指定的Gravatar超出您允许的最大内容评级时。提供的图像是'mm'、'identicon'、'monsterid'、'retro'和'wavatar'。要设置网站使用的默认图像，请使用方法\emberlabs\GravatarLib\Gravatar->setDefaultImage()。此外，您还可以通过提供您希望使用的图像的有效URL来自定义默认图像。

以下是一些示例...

	$gravatar->setDefaultImage('wavatar');

	$gravatar->setDefaultImage('http://yoursitehere.com/path/to/image.png');

警告

如果指定了无效的默认图像（既是一个无效的预制默认图像，又提供了一个无效的URL），此方法将抛出类\InvalidArgumentException的异常。

设置头像大小

Gravatar允许头像图像的大小从1px到512px，您作为开发者或网站管理员可以指定所需的头像大小。默认情况下，提供的头像大小是80px。要设置网站使用的头像大小，请使用方法\emberlabs\GravatarLib\Gravatar->setAvatarSize()，并使用表示像素大小的整数指定头像大小。

以下是如何设置头像大小的示例

	$gravatar->setAvatarSize(184);

警告

如果指定了无效的大小（小于1，大于512）或非整数值，此方法将抛出类\InvalidArgumentException的异常。

设置最大内容评级

Gravatar提供了四个评级等级，用于评级头像，其名称与美国娱乐媒体评级尺度相似。它们按照严重程度顺序排列（第一个是适合所有人查看，最后一个是非常明确的）：“g”、“pg”、“r”和“x”。默认情况下，最大内容评级设置为“g”。您可以通过使用方法\emberlabs\GravatarLib\Gravatar->setMaxRating()来设置嵌入您网站中的头像允许的最大评级。请注意，任何不符合您最大内容评级的头像都将替换为您指定的默认图像。

以下是如何设置最大内容评级的示例

	$gravatar->setMaxRating('r');

警告

如果指定了无效的最大评级，此方法将抛出类\InvalidArgumentException的异常。

启用安全图像

如果您的网站通过HTTPS提供，您可能希望也通过HTTPS提供Gravatar，以避免“混合内容警告”。在生成任何Gravatar URL之前，请调用方法\emberlabs\GravatarLib\Gravatar->enableSecureImages()以启用“安全图像”模式。要检查您是否正在使用“安全图像”模式，请调用方法\emberlabs\GravatarLib\Gravatar->usingSecureImages()，该方法将返回一个布尔值，表示是否启用了安全图像模式。

集成到twig

将此库作为模板资源集成到Twig模板引擎非常简单。

当你准备好一个Twig_Environment实例时，可以将你实例化的Gravatar对象添加为twig的“全局”变量，如下所示

	<?php
	// include the lib file here, or use an autoloader if you wish
	include __DIR__ . '/includes/emberlabs/GravatarLib/Gravatar.php';
	// instantiate the gravatar library object
    $gravatar = new \emberlabs\GravatarLib\Gravatar();

	// ... do whatever you want with your settings here

	// here, we will assume $twig is an already-created instance of Twig_Environment
	$twig->addGlobal('gravatar', $gravatar);

现在在你的twig模板中，你可以使用类似以下代码片段来获取一个用户的Gravatar

(注意：这个模板片段假设“email”模板变量包含要获取Gravatar的用户邮箱)

	<img src="User avatar" src="{{ gravatar.get(email)|raw }}" />

我们还在这里使用原始过滤器来保持XHTML 1.0 Strict的兼容性；生成的Gravatar URL包含&字符，如果不使用过滤器，它将被双重转义。