forxer / gravatar
A library providing easy gravatar integration.
Installs: 183 176
Dependents: 7
Suggesters: 0
Security: 0
Stars: 30
Watchers: 3
Forks: 2
Open Issues: 0
Requires
- php: ^8.2
Requires (Dev)
- laravel/pint: ^1.16.0
- rector/rector: ^1.1.0
README
Gravatar
Gravatar is a small library intended to provide easy integration of... Gravatar :) It will help you generate the URL for Gravatar images and profiles in many ways.
To use it in a Laravel project, please look at: laravel-gravatar
$avatar = gravatar('email@example.com') ->size(120) ->defaultImage('robohash') ->extension('jpg'); //... echo $avatar;
Index
Installation
Requirements
- PHP 8.2 or newer
If you want to use it with a version earlier than PHP 8.2, please use one of the previous versions that suits your needs: v4, v3, v2 or v1.
With Composer
The easiest way to install Gravatar is via Composer. Run the following command in the root of your project:
composer require forxer/Gravatar
Without Composer
You should use composer, it's so convenient. However, if you really do not want, or can not, you can download the latest version and unpack the archive.
Then, you do what it takes to use it with your own autoloader. The examples below use the Composer autoloader.
Usage
There are many ways to use this library:
- Use helpers fonctions
- Use the Gravatar base class with its
Gravatar::image()
andGravatar::profile()
methods - Instantiate the dedicated classes
Gravatar\Image()
andGravatar\Profile()
All of these ways return instances of Gravatar\Image
and Gravatar\Profile
that allow you to define specific settings/parameters as needed.
Whatever method you use, you could use the url()
method to retrieve it. Or display the URL directly because they implement the __toString()
method.
Use helpers
The easiest way to use this library is to use the helper functions.
Since version 4, in order to avoid conflicts with other packages, we no longer define the gravatar()
and gravatar_profile()
helpers. It's up to you to do this in your app with names that work for you and don't conflict with others. Here's how to do it; it's simple.
In a file dedicated to the helper functions, define the version 3 functions using the names that suit you.
<?php use Gravatar\Image; use Gravatar\Profile; if (! function_exists('gravatar')) { /** * Return a new Gravatar Image instance. * * @param string|null $email * @return Image */ function gravatar(?string $email = null): Image { return new Image($email); } } if (! function_exists('gravatar_profile')) { /** * Return a new Gravatar Profile instance. * * @param string|null $email * @return Profile */ function gravatar_profile(?string $email = null): Profile { return new Profile($email); } }
If you do not have a helpers functions file, you can create one for example at the root of your project, which you name helpers.php
and which you fill in the composer.json
file so that it is autoloaded. For example :
"autoload" : { "psr-4" : { "YourProject\\" : "src" }, "files" : [ "src/helpers.php" ] },
This way you can use them like this:
<?php require 'vendor/autoload.php'; // Get a Gravatar image instance: $image = gravatar('email@example.com'); // return: Gravatar\Image // Get a Gravatar image URL: $imageUrl = gravatar('email@example.com')->url(); // return: //www.gravatar.com/avatar/5658ffccee7f0ebfda2b226238b1eb6e // Show a Gravatar image URL: echo gravatar('email@example.com'); // output: //www.gravatar.com/avatar/5658ffccee7f0ebfda2b226238b1eb6e // Get a Gravatar profile instance: $profile = gravatar_profile('email@example.com'); // return: Gravatar\Profile // Get a Gravatar profile URL: echo gravatar_profile('email@example.com'); // output: https//www.gravatar.com/5658ffccee7f0ebfda2b226238b1eb6e
Use the Gravatar base class
But it is also possible to use the static methods of the base Gravatar class.
Single Gravatar image/profile
If you want to retrieve a single Gravatar image/profile URL you can use the main Gravatar class like this:
<?php require 'vendor/autoload.php'; use Gravatar\Gravatar; // Get a Gravatar image instance: $image = Gravatar::image('email@example.com'); // return: Gravatar\Image // Get a single Gravatar image URL: $imageUrl = Gravatar::image('email@example.com')->url(); // return: //www.gravatar.com/avatar/5658ffccee7f0ebfda2b226238b1eb6e // Show a single Gravatar image URL: echo Gravatar::image('email@example.com'); // output: //www.gravatar.com/avatar/5658ffccee7f0ebfda2b226238b1eb6e // Get a Gravatar profile instance: $profile = Gravatar::profile('email@example.com'); // return Gravatar\Profile // Get a Gravatar profile URL: echo Gravatar::profile('email@example.com'); // output: https//www.gravatar.com/5658ffccee7f0ebfda2b226238b1eb6e
Multiples Gravatar images/profiles
If you want to retrieve multiples Gravatar images/profiles URL you can also use the main Gravatar class with Gravatar::images()
and Gravatar::profiles()
methods.
Note the presence of the "s" character at the end of methods names.
<?php require 'vendor/autoload.php'; use Gravatar\Gravatar; $emails = ['email1@example.com', 'email2@example.com','email3@example.com', /* ... */ ]; // Get multiples Gravatar images: foreach (Gravatar::images($emails) as $image) { echo $image; } // Get multiples Gravatar profiles: foreach (Gravatar::profiles($emails) as $profile) { echo $profile; }
The Gravatar::images()
and Gravatar::profiles()
methods return an array of instances of Gravatar\Image
and Gravatar\Profile
.
Instanciate the dedicated classes
In fact, either gravatar()
and gravatar_profile()
helpers functions or Gravatar::image()
, Gravatar::images()
, Gravatar::profile()
and Gravatar::profiles()
static methods are just shortcuts for convenient use.
Behind these helpers functions and static methods, there are two classes : Gravatar\Image
and Gravatar\Profile
.
In some case, for some reason, you would use the library in another way. For exemple with a dependency injection container.
<?php require 'vendor/autoload.php'; use Gravatar\Image as GravatarImage; use Gravatar\Profile as GravatarProfile; // emails list $emails = ['email1@example.com', 'email2@example.com','email3@example.com', /* ... */ ]; // Get multiples Gravatar images with size and default image: $gravatarImage = new GravatarImage(); $gravatarImage ->setSize(120) ->setDefaultImage('mp'); foreach ($emails as $email) { echo $gravatarImage->email($email)->url(); } // Get multiples Gravatar profiles in JSON $gravatarProfile = new GravatarProfile(); $gravatarProfile->setFormat('json'); foreach ($emails as $email) { echo $gravatarProfile->email($email)->url(); }
Mandatory parameter
Obviously the email address is a mandatory parameter that can be entered in different ways.
// pass it as argument of the helper $gravatarImage = gravatar($email); // the first argument of `Gravatar::image()` and `Gravatar::images()` $gravatarImage = Gravatar::image($email); $gravatarImages = Gravatar::images($emails); // or pass it to the `Gravatar\Image` constructor $gravatarImage = new Gravatar\Image($email); // or use the `setEmail()` method of a `Gravatar\Image` instance $gravatarImage = gravatar(); $gravatarImage->setEmail($email); $gravatarImage = new Gravatar\Image(); $gravatarImage->setEmail($email); // or the `email()` helper method of a `Gravatar\Image` instance $gravatarImage = gravatar(); $gravatarImage->email($email); $gravatarImage = new Gravatar\Image(); $gravatarImage->email($email);
These previous examples are also valid for the profile.
// pass it as argument of the helper $gravatarProfile = gravatar_profile($email); // the first argument of `Gravatar::profile()` and `Gravatar::profiles()` $gravatarProfile = Gravatar::profile($email); $gravatarProfiles = Gravatar::profiles($emails); // or pass it to the `Gravatar\Profile` constructor $gravatarProfile = new Gravatar\Profile($email); // or use the `setEmail()` method of a `Gravatar\Profile` instance $gravatarProfile = gravatar_profile(); $gravatarProfile->setEmail($email); $gravatarProfile = new Gravatar\Profile(); $gravatarProfile->setEmail($email); // or the `email()` helper method of a `Gravatar\Profile` instance $gravatarProfile = gravatar_profile(); $gravatarProfile->email($email); $gravatarProfile = new Gravatar\Profile(); $gravatarProfile->email($email);
Optional parameters
Gravatar image size
By default, images are presented at 80px by 80px if no size parameter is supplied. You may request a specific image size, which will be dynamically delivered from Gravatar. You may request images anywhere from 1px up to 2048px, however note that many users have lower resolution images, so requesting larger sizes may result in pixelation/low-quality images.
An avatar size should be an integer representing the size in pixels.
// pass the size as second argument of `Gravatar::image()` and `Gravatar::images()` $gravatarImage = Gravatar::image($email, 120); $gravatarImages = Gravatar::images($emails, 120); // or use the `setSize()` method of a `Gravatar\Image` instance $gravatarImage = gravatar($email); $gravatarImage->setSize(120); $gravatarImage = new Gravatar\Image($email); $gravatarImage->setSize(120); // or the `size()` helper method of a `Gravatar\Image` instance $gravatarImage = gravatar($email); $gravatarImage->size(120); $gravatarImage = new Gravatar\Image($email); $gravatarImage->size(120); // or its alias `s()` (as in the generated query string) $gravatarImage = new Gravatar\Image($email); $gravatarImage->s(120);
If you want to retrieve the currently set avatar size, you can use one of following methods:
// call the `getSize()` method of a `Gravatar\Image` instance without argument $gravatarImage = gravatar(); $gravatarImage->getSize(); $gravatarImage = new Gravatar\Image(); $gravatarImage->getSize(); // or the `size()` helper method of a `Gravatar\Image` instance without argument $gravatarImage = gravatar(); $gravatarImage->size(); $gravatarImage = new Gravatar\Image(); $gravatarImage->size(); // or its alias `s()` $gravatarImage = gravatar(); $gravatarImage->s(); $gravatarImage = new Gravatar\Image(); $gravatarImage->s();
Default Gravatar image
What happens when an email address has no matching Gravatar image or when the gravatar specified exceeds your maximum allowed content rating?
By default, this:
If you'd prefer to use your own default image, then you can easily do so by supplying the URL to an image. In addition to allowing you to use your own image, Gravatar has a number of built in options which you can also use as defaults. Most of these work by taking the requested email hash and using it to generate a themed image that is unique to that email address. To use these options, just pass one of the following keywords:
- 404: do not load any image if none is associated with the email hash, instead return an HTTP 404 (File Not Found) response
- mp: (mystery-person) a simple, cartoon-style silhouetted outline of a person (does not vary by email hash)
- identicon: a geometric pattern based on an email hash
- monsterid: a generated 'monster' with different colors, faces, etc
- wavatar: generated faces with differing features and backgrounds
- retro: awesome generated, 8-bit arcade-style pixelated faces
- robohash: a generated robot with different colors, faces, etc
- blank: a transparent PNG image
// pass the default Gravatar image as third argument of `Gravatar::image()` and `Gravatar::images()` $gravatarImage = Gravatar::image($email, null, 'mp'); $gravatarImages = Gravatar::images($emails, null, 'mp'); // or with named parameters $gravatarImage = Gravatar::image($email, defaultImage: 'mp'); $gravatarImages = Gravatar::images($emails, defaultImage: 'mp'); // or use the `setDefaultImage()` method of a `Gravatar\Image` instance $gravatarImage = gravatar($email); $gravatarImage->setDefaultImage('mp'); $gravatarImage = new Gravatar\Image($email); $gravatarImage->setDefaultImage('mp'); // or the `defaultImage()` helper method of a `Gravatar\Image` instance $gravatarImage = gravatar($email); $gravatarImage->defaultImage('mp'); $gravatarImage = new Gravatar\Image($email); $gravatarImage->defaultImage('mp'); // or its alias `d()` (as in the generated query string) $gravatarImage = new Gravatar\Image($email); $gravatarImage->d('mp');
If you want to retrieve the currently set avatar default image, you can use one of following methods:
// call the `getDefaultImage()` method of a `Gravatar\Image` instance without argument $gravatarImage = gravatar(); $gravatarImage->getDefaultImage(); $gravatarImage = new Gravatar\Image(); $gravatarImage->getDefaultImage(); // or the `defaultImage()` helper method of a `Gravatar\Image` instance without argument $gravatarImage = gravatar(); $gravatarImage->defaultImage(); $gravatarImage = new Gravatar\Image(); $gravatarImage->defaultImage(); // or its alias `d()` $gravatarImage = gravatar(); $gravatarImage->d(); $gravatarImage = new Gravatar\Image(); $gravatarImage->d();
Gravatar image max rating
Gravatar allows users to self-rate their images so that they can indicate if an image is appropriate for a certain audience. By default, only 'g' rated images are displayed unless you indicate that you would like to see higher ratings.
You may specify one of the following ratings to request images up to and including that rating:
- g: suitable for display on all websites with any audience type.
- pg: may contain rude gestures, provocatively dressed individuals, the lesser swear words, or mild violence.
- r: may contain such things as harsh profanity, intense violence, nudity, or hard drug use.
- x: may contain hardcore sexual imagery or extremely disturbing violence.
// pass the Gravatar image max rating as fourth argument of `Gravatar::image()` and `Gravatar::images()` $gravatarImage = Gravatar::image($email, null, null, 'g'); $gravatarImages = Gravatar::images($emails, null, null, 'g'); // or with named parameters $gravatarImage = Gravatar::image($email, rating: 'g'); $gravatarImages = Gravatar::images($emails, rating: 'g'); // or use the `setMaxRating()` method of a `Gravatar\Image` instance $gravatarImage = gravatar($email); $gravatarImage->setMaxRating('g'); $gravatarImage = new Gravatar\Image($email); $gravatarImage->setMaxRating('g'); // or the `maxRating()` helper method of a `Gravatar\Image` instance $gravatarImage = gravatar($email); $gravatarImage->maxRating('g'); $gravatarImage = new Gravatar\Image($email); $gravatarImage->maxRating('g'); // or its alias `r()` (as in the generated query string) $gravatarImage = gravatar($email); $gravatarImage->r('g'); $gravatarImage = new Gravatar\Image($email); $gravatarImage->r('g');
If you want to retrieve the currently set avatar max rating, you can use one of following methods:
// call the `getMaxRating()` method of a `Gravatar\Image` instance without argument $gravatarImage = gravatar(); $gravatarImage->getMaxRating(); $gravatarImage = new Gravatar\Image(); $gravatarImage->getMaxRating(); // or the `maxrating()` helper method of a `Gravatar\Image` instance without argument $gravatarImage = gravatar(); $gravatarImage->maxrating(); $gravatarImage = new Gravatar\Image(); $gravatarImage->maxrating(); // or its alias `r()` $gravatarImage = gravatar(); $gravatarImage->r(); $gravatarImage = new Gravatar\Image(); $gravatarImage->r();
Gravatar image file-type extension
If you require a file-type extension (some places do) then you may also specify it.
You can specify one of the following extensions for the generated URL:
- 'jpg'
- 'jpeg'
- 'gif'
- 'png'
- 'webp'
// pass the Gravatar image file-type extension as fifth argument of `Gravatar::image()` and `Gravatar::images()` Gravatar::image($email, null, null, null, 'jpg'); Gravatar::images($emails, null, null, null, 'jpg'); // or with named parameters $gravatarImage = Gravatar::image($email, extension: 'jpg'); $gravatarImages = Gravatar::images($emails, extension: 'jpg'); // or use the `setExtension()` method of a `Gravatar\Image` instance $gravatarImage = gravatar($email); $gravatarImage->setExtension('jpg'); $gravatarImage = new Gravatar\Image($email); $gravatarImage->setExtension('jpg'); // or the `extension()` helper method of a `Gravatar\Image` instance $gravatarImage = gravatar($email); $gravatarImage->extension('jpg'); $gravatarImage = new Gravatar\Image($email); $gravatarImage->extension('jpg'); // or its alias `e()` (as in the generated query string) $gravatarImage = gravatar($email); $gravatarImage->e('jpg'); $gravatarImage = new Gravatar\Image($email); $gravatarImage->e('jpg');
If you want to retrieve the currently set avatar file-type extension, you can use one of following methods:
// call the `getExtension()` method of a `Gravatar\Image` instance without argument $gravatarImage = gravatar(); $gravatarImage->getExtension(); $gravatarImage = new Gravatar\Image(); $gravatarImage->getExtension(); // or the `extension()` helper method of a `Gravatar\Image` instance without argument $gravatarImage = gravatar(); $gravatarImage->getExtension(); $gravatarImage = new Gravatar\Image(); $gravatarImage->extension(); // or its alias `e()` $gravatarImage = gravatar(); $gravatarImage->getExtension(); $gravatarImage = new Gravatar\Image(); $gravatarImage->e();
Force to always use the default image
If for some reason you wanted to force the default image to always be load, you can do it:
// to force to always use the default image, set the sixth argument of `Gravatar::image()` and `Gravatar::images()` to `true` Gravatar::image($email, null, null, null, null, true); Gravatar::images($emails, null, null, null, null, true); // or with named parameters $gravatarImage = Gravatar::image($email, forceDefault: true); $gravatarImages = Gravatar::images($emails, forceDefault: true); // or use the `setForceDefault()` method of a `Gravatar\Image` instance $gravatarImage = gravatar($email); $gravatarImage->setForceDefault(true); $gravatarImage = new Gravatar\Image($email); $gravatarImage->setForceDefault(true); // or the `forceDefault()` helper method of a `Gravatar\Image` instance $gravatarImage = gravatar($email); $gravatarImage->forceDefault(true); $gravatarImage = new Gravatar\Image($email); $gravatarImage->forceDefault(true); // or its alias `f()` (as in the generated query string) $gravatarImage = gravatar($email); $gravatarImage->f(true); $gravatarImage = new Gravatar\Image($email); $gravatarImage->f(true); // or use the `enableForceDefault()` method of a `Gravatar\Image` instance $gravatarImage = gravatar($email); $gravatarImage->setForceDefault(true); $gravatarImage = new Gravatar\Image($email); $gravatarImage->enableForceDefault();
To check to see if you are forcing default image, call the method forcingDefault()
of Gravatar\Image
,
which will return a boolean value regarding whether or not forcing default is enabled.
$gravatarImage = gravatar(); $gravatarImage->enableForceDefault(); //... $gravatarImage->forcingDefault(); // true //... $gravatarImage->disableForceDefault(); //... $gravatarImage->forcingDefault(); // false
Gravatar profile format
Gravatar profile data may be requested in different data formats for simpler programmatic access.
// pass the Gravatar profile format as second argument of `Gravatar::profile()` and `Gravatar::profiles()` Gravatar::profile($email, 'json'); // or use the `setFormat()` method of `Gravatar\Profile` instance $gravatarProfile = new Gravatar\Profile($email); $gravatarProfile->setFormat('json'); // or the `format()` helper method of a `Gravatar\Profile` instance $gravatarProfile = new Gravatar\Profile($email); $gravatarProfile->format('json'); // or its alias `f()` (as in the generated query string) $gravatarProfile = new Gravatar\Profile($email); $gravatarProfile->f('json');
The following formats are supported:
- JSON ; use 'json' as argument
- XML ; use 'xml' as argument
- PHP ; use 'php' as argument
- VCF/vCard ; use 'vcf' as argument
- QR Code ; use 'qr' as argument
License
This library is licensed under the MIT license; you can find a full copy of the license itself in the file /LICENSE