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提供服务，您可能希望也将Gravatar通过HTTPS提供服务，以避免“混合内容警告”。在生成任何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 包含了&字符，如果不使用过滤器，它将被双重转义。