README

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

版权

(c) 2011 emberlabs.org

许可证

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

要求

• 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提供服务，您可能还希望将 gravatars 也通过 HTTPS 提供服务，以避免“混合内容警告”。要在生成任何 gravatars URL 之前启用“安全图片”模式，请调用方法 \emberlabs\GravatarLib\Gravatar->enableSecureImages()。要检查是否正在使用“安全图片”模式，请调用方法 \emberlabs\GravatarLib\Gravatar->usingSecureImages()，它将返回一个布尔值，表示是否启用了安全图片模式。

twig 集成

将此库作为模板资产连接到 Twig 模板引擎 非常简单。

当您准备好 Twig_Environment 实例时，将您的实例化 gravatars 对象添加为 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”模板变量包含要获取 gravatars 的用户的电子邮件地址）

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

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