├── .gitignore ├── Gravatar.php ├── LICENSE ├── README.markdown └── composer.json /.gitignore: -------------------------------------------------------------------------------- 1 | vendor 2 | composer.lock 3 | *.komodoproject 4 | -------------------------------------------------------------------------------- /Gravatar.php: -------------------------------------------------------------------------------- 1 | size; 77 | } 78 | 79 | /** 80 | * Set the avatar size to use. 81 | * @param integer $size - The avatar size to use, must be less than 512 and greater than 0. 82 | * @return \emberlabs\GravatarLib\Gravatar - Provides a fluent interface. 83 | * 84 | * @throws \InvalidArgumentException 85 | */ 86 | public function setAvatarSize($size) 87 | { 88 | // Wipe out the param cache. 89 | $this->param_cache = NULL; 90 | 91 | if(!is_int($size) && !ctype_digit($size)) 92 | { 93 | throw new InvalidArgumentException('Avatar size specified must be an integer'); 94 | } 95 | 96 | $this->size = (int) $size; 97 | 98 | if($this->size > 512 || $this->size < 0) 99 | { 100 | throw new InvalidArgumentException('Avatar size must be within 0 pixels and 512 pixels'); 101 | } 102 | 103 | return $this; 104 | } 105 | 106 | /** 107 | * Get the current default image setting. 108 | * @return mixed - False if no default image set, string if one is set. 109 | */ 110 | public function getDefaultImage() 111 | { 112 | return $this->default_image; 113 | } 114 | 115 | /** 116 | * Set the default image to use for avatars. 117 | * @param mixed $image - The default image to use. Use boolean false for the gravatar default, a string containing a valid image URL, or a string specifying a recognized gravatar "default". 118 | * @return \emberlabs\GravatarLib\Gravatar - Provides a fluent interface. 119 | * 120 | * @throws \InvalidArgumentException 121 | */ 122 | public function setDefaultImage($image) 123 | { 124 | // Quick check against boolean false. 125 | if($image === false) 126 | { 127 | $this->default_image = false; 128 | 129 | return $this; 130 | } 131 | 132 | // Wipe out the param cache. 133 | $this->param_cache = NULL; 134 | 135 | // Check $image against recognized gravatar "defaults", and if it doesn't match any of those we need to see if it is a valid URL. 136 | $_image = strtolower($image); 137 | $valid_defaults = array('404' => 1, 'mm' => 1, 'identicon' => 1, 'monsterid' => 1, 'wavatar' => 1, 'retro' => 1); 138 | if(!isset($valid_defaults[$_image])) 139 | { 140 | if(!filter_var($image, FILTER_VALIDATE_URL)) 141 | { 142 | throw new InvalidArgumentException('The default image specified is not a recognized gravatar "default" and is not a valid URL'); 143 | } 144 | else 145 | { 146 | $this->default_image = rawurlencode($image); 147 | } 148 | } 149 | else 150 | { 151 | $this->default_image = $_image; 152 | } 153 | 154 | return $this; 155 | } 156 | 157 | /** 158 | * Get the current maximum allowed rating for avatars. 159 | * @return string - The string representing the current maximum allowed rating ('g', 'pg', 'r', 'x'). 160 | */ 161 | public function getMaxRating() 162 | { 163 | return $this->max_rating; 164 | } 165 | 166 | /** 167 | * Set the maximum allowed rating for avatars. 168 | * @param string $rating - The maximum rating to use for avatars ('g', 'pg', 'r', 'x'). 169 | * @return \emberlabs\GravatarLib\Gravatar - Provides a fluent interface. 170 | * 171 | * @throws \InvalidArgumentException 172 | */ 173 | public function setMaxRating($rating) 174 | { 175 | // Wipe out the param cache. 176 | $this->param_cache = NULL; 177 | 178 | $rating = strtolower($rating); 179 | $valid_ratings = array('g' => 1, 'pg' => 1, 'r' => 1, 'x' => 1); 180 | if(!isset($valid_ratings[$rating])) 181 | { 182 | throw new InvalidArgumentException(sprintf('Invalid rating "%s" specified, only "g", "pg", "r", or "x" are allowed to be used.', $rating)); 183 | } 184 | 185 | $this->max_rating = $rating; 186 | 187 | return $this; 188 | } 189 | 190 | /** 191 | * Check if we are using the secure protocol for the image URLs. 192 | * @return boolean - Are we supposed to use the secure protocol? 193 | */ 194 | public function usingSecureImages() 195 | { 196 | return $this->use_secure_url; 197 | } 198 | 199 | /** 200 | * Enable the use of the secure protocol for image URLs. 201 | * @return \emberlabs\GravatarLib\Gravatar - Provides a fluent interface. 202 | */ 203 | public function enableSecureImages() 204 | { 205 | $this->use_secure_url = true; 206 | 207 | return $this; 208 | } 209 | 210 | /** 211 | * Disable the use of the secure protocol for image URLs. 212 | * @return \emberlabs\GravatarLib\Gravatar - Provides a fluent interface. 213 | */ 214 | public function disableSecureImages() 215 | { 216 | $this->use_secure_url = false; 217 | 218 | return $this; 219 | } 220 | 221 | /** 222 | * Build the avatar URL based on the provided email address. 223 | * @param string $email - The email to get the gravatar for. 224 | * @param string $hash_email - Should we hash the $email variable? (Useful if the email address has a hash stored already) 225 | * @return string - The XHTML-safe URL to the gravatar. 226 | */ 227 | public function buildGravatarURL($email, $hash_email = true) 228 | { 229 | // Start building the URL, and deciding if we're doing this via HTTPS or HTTP. 230 | if($this->usingSecureImages()) 231 | { 232 | $url = static::HTTPS_URL; 233 | } 234 | else 235 | { 236 | $url = static::HTTP_URL; 237 | } 238 | 239 | // Tack the email hash onto the end. 240 | if($hash_email == true && !empty($email)) 241 | { 242 | $url .= $this->getEmailHash($email); 243 | } 244 | elseif(!empty($email)) 245 | { 246 | $url .= $email; 247 | } 248 | else 249 | { 250 | $url .= str_repeat('0', 32); 251 | } 252 | 253 | // Check to see if the param_cache property has been populated yet 254 | if($this->param_cache === NULL) 255 | { 256 | // Time to figure out our request params 257 | $params = array(); 258 | $params[] = 's=' . $this->getAvatarSize(); 259 | $params[] = 'r=' . $this->getMaxRating(); 260 | if($this->getDefaultImage()) 261 | { 262 | $params[] = 'd=' . $this->getDefaultImage(); 263 | } 264 | 265 | // Stuff the request params into the param_cache property for later reuse 266 | $this->params_cache = (!empty($params)) ? '?' . implode('&', $params) : ''; 267 | } 268 | 269 | // Handle "null" gravatar requests. 270 | $tail = ''; 271 | if(empty($email)) 272 | { 273 | $tail = !empty($this->params_cache) ? '&f=y' : '?f=y'; 274 | } 275 | 276 | // And we're done. 277 | return $url . $this->params_cache . $tail; 278 | } 279 | 280 | /** 281 | * Get the email hash to use (after cleaning the string). 282 | * @param string $email - The email to get the hash for. 283 | * @return string - The hashed form of the email, post cleaning. 284 | */ 285 | public function getEmailHash($email) 286 | { 287 | // Using md5 as per gravatar docs. 288 | return hash('md5', strtolower(trim($email))); 289 | } 290 | 291 | /** 292 | * ...Yeah, it's just an alias of buildGravatarURL. This is just to make it easier to use as a twig asset. 293 | * @see \emberlabs\GravatarLib\Gravatar::buildGravatarURL() 294 | */ 295 | public function get($email, $hash_email = true) 296 | { 297 | // Just an alias. Makes it easy to use this as a twig asset. 298 | return $this->buildGravatarURL($email, $hash_email); 299 | } 300 | } 301 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) 2011 emberlabs.org 2 | 3 | Permission is hereby granted, free of charge, to any person obtaining a copy 4 | of this software and associated documentation files (the "Software"), to deal 5 | in the Software without restriction, including without limitation the rights 6 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 7 | copies of the Software, and to permit persons to whom the Software is furnished 8 | to do so, subject to the following conditions: 9 | 10 | The above copyright notice and this permission notice shall be included in all 11 | copies or substantial portions of the Software. 12 | 13 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 14 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 15 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 16 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 17 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 18 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 19 | THE SOFTWARE. 20 | -------------------------------------------------------------------------------- /README.markdown: -------------------------------------------------------------------------------- 1 | # GravatarLib 2 | 3 | GravatarLib is a small library intended to provide easy integration of gravatar-provided avatars. 4 | 5 | ## copyright 6 | 7 | (c) 2011 emberlabs.org 8 | 9 | ## license 10 | 11 | This library is licensed under the MIT license; you can find a full copy of the license itself in the file /LICENSE 12 | 13 | ## requirements 14 | 15 | * PHP 5.3.0 or newer 16 | * hash() function must be available, along with the md5 algorithm 17 | 18 | ## usage 19 | 20 | We'll assume you're using this git repository as a git submodule, and have it located at `includes/emberlabs/GravatarLib/` according to namespacing rules, for easy autoloading. 21 | 22 | ### general example 23 | 24 | ``` php 25 | setDefaultImage('mm') 30 | ->setAvatarSize(150); 31 | // example: setting maximum allowed avatar rating 32 | $gravatar->setMaxRating('pg'); 33 | $avatar = $gravatar->buildGravatarURL('someemail@domain.com'); 34 | ``` 35 | 36 | ### setting the default image 37 | 38 | Gravatar provides several pre-fabricated default images for use when the email address provided does not have a gravatar or when the gravatar specified exceeds your maximum allowed content rating. 39 | The provided images are 'mm', 'identicon', 'monsterid', 'retro', and 'wavatar'. To set the default iamge to use on your site, use the method `\emberlabs\GravatarLib\Gravatar->setDefaultImage()` 40 | In addition, you can also set your own default image to be used by providing a valid URL to the image you wish to use. 41 | 42 | Here are a couple of examples... 43 | 44 | ``` php 45 | $gravatar->setDefaultImage('wavatar'); 46 | ``` 47 | 48 | ``` php 49 | $gravatar->setDefaultImage('http://yoursitehere.com/path/to/image.png'); 50 | ``` 51 | 52 | 53 | 54 | #### WARNING 55 | If an invalid default image is specified (both an invalid prefab default image and an invalid URL is provided), this method will throw an exception of class `\InvalidArgumentException`. 56 | 57 | ### setting avatar size 58 | 59 | Gravatar allows avatar images ranging from 1px to 512px in size -- and you, the developer or site administrator can specify the exact size of avatar that you want. 60 | By default, the avatar size provided is 80px. To set the avatar size for use on your site, use the method `\emberlabs\GravatarLib\Gravatar->setAvatarSize()`, and specify the avatar size with an integer representing the size in pixels. 61 | 62 | An example of setting the avatar size is provided below: 63 | 64 | ``` php 65 | $gravatar->setAvatarSize(184); 66 | ``` 67 | 68 | 69 | 70 | #### WARNING 71 | If an invalid size (less than 1, greater than 512) or a non-integer value is specified, this method will throw an exception of class `\InvalidArgumentException`. 72 | 73 | ### setting the maximum content rating 74 | 75 | Gravatar provides four levels for rating avatars by, which are named similar to entertainment media ratings scales used in the United States. They are, by order of severity (first is safe for everyone to see, last is explicit), "g", "pg", "r", and "x". 76 | By default, the maximum content rating is set to "g". You can set the maximum allowable rating on avatars embedded within your site by using the method `\emberlabs\GravatarLib\Gravatar->setMaxRating()`. Please note that any avatars that do not fall under your maximum content rating will be replaced with the default image you have specified. 77 | 78 | Here's an example of how to set the maximum content rating: 79 | 80 | ``` php 81 | $gravatar->setMaxRating('r'); 82 | ``` 83 | 84 | 85 | 86 | #### WARNING 87 | If an invalid maximum rating is specified, this method will throw an exception of class `\InvalidArgumentException`. 88 | 89 | ### enabling secure images 90 | 91 | If your site is served over HTTPS, you'll likely want to serve gravatars over HTTPS as well to avoid "mixed content warnings". 92 | To enable "secure images" mode, call the method `\emberlabs\GravatarLib\Gravatar->enableSecureImages()` before generating any gravatar URLs. 93 | To check to see if you are using "secure images" mode, call the method `\emberlabs\GravatarLib\Gravatar->usingSecureImages()`, which will return a boolean value regarding whether or not secure images mode is enabled. 94 | 95 | ### twig integration 96 | 97 | It's extremely easy to hook this library up as a template asset to the [Twig template engine](http://www.twig-project.org/). 98 | 99 | When you've got an instance of the Twig_Environment ready, add in your instantiated gravatar object as a twig "global" like so: 100 | 101 | ``` php 102 | addGlobal('gravatar', $gravatar); 112 | ``` 113 | 114 | Now in your twig templates, you can get a user's gravatar with something like this snip of code: 115 | 116 | (note: this template snip assumes that the "email" template variable contains the email of the user to grab the gravatar for) 117 | 118 | ``` 119 | 120 | ``` 121 | 122 | We are also using the raw filter here to preserve XHTML 1.0 Strict compliance; the generated gravatar URL contains the `&` character, and if the filter was not used it would be double-escaped. 123 | -------------------------------------------------------------------------------- /composer.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "emberlabs/gravatarlib", 3 | "description": "A lightweight PHP 5.3 OOP library providing easy gravatar integration.", 4 | "keywords": ["gravatar", "templating", "twig"], 5 | "type": "library", 6 | "homepage": "http://emberlabs.org/", 7 | "license": "MIT", 8 | "authors": [{ 9 | "name" : "Sam Thompson", 10 | "email" : "sam@emberlabs.org" 11 | }, 12 | { 13 | "name" : "Damian Bushong", 14 | "email" : "damian@emberlabs.org" 15 | }], 16 | "require": { 17 | "php": ">=5.3.0" 18 | }, 19 | "suggest" : { 20 | "twig/twig" : ">=1.4.0" 21 | }, 22 | "autoload": { 23 | "psr-0": { 24 | "emberlabs\\gravatarlib\\": "" 25 | } 26 | }, 27 | "target-dir" : "emberlabs/gravatarlib" 28 | } --------------------------------------------------------------------------------