Gravatar Laravel Package

Getting Started

Install with Composer:

composer require gravatarphp/gravatar

This is a framework-agnostic URL builder — there is no Laravel service provider or auto-discovery. You get one job out of it: turn an email address into a Gravatar image URL.

First use case, the 30-second version:

use Gravatar\Gravatar;

$gravatar = new Gravatar();

$url = $gravatar->getUrl('[email protected]');
// https://www.gravatar.com/avatar/<md5-of-email>?...

Drop that URL into an <img> tag and you're done. If you need size, a fallback image, or a rating filter, pass options through the builder/constructor before calling getUrl() (e.g. setSize(200), setDefaultImage('identicon'), or an options array — check the README for the exact surface; the release you're on is from Jan 2019).

Where to look first:

1. src/ — the main Gravatar class plus any Image/Url value object. That's the entire API surface.
2. composer.json — the PHP version constraint. A 2019 release will target PHP 7.x; verify it runs on your current runtime before adopting.
3. README.md — the options map (size/default/rating/force) and the constructor signature.

Implementation Patterns

Config-driven instance. Don't scatter options across call sites. Build one configured instance and reuse it:

$gravatar = (new Gravatar())
    ->setSize(120)
    ->setDefaultImage('identicon')
    ->setRating('pg');

echo $gravatar->getUrl($user->email);

Laravel binding. Since there's no provider, register it yourself in AppServiceProvider:

$this->app->singleton(Gravatar::class, function () {
    return (new Gravatar())
        ->setSize(config('services.gravatar.size', 120))
        ->setDefaultImage(config('services.gravatar.default', 'mm'));
});

Then inject Gravatar anywhere, or add a thin Gravatar facade for Gravatar::getUrl($email) in views.

Blade component. Wrap it once instead of calling the library from templates:

{{-- resources/views/components/avatar.blade.php --}}
<img src="{{ app(Gravatar::class)->getUrl($email) }}"
     alt="{{ $name ?? 'Avatar' }}"
     width="{{ $size ?? 120 }}" height="{{ $size ?? 120 }}">

Cache the derived URL, not the image. Hashing is cheap, but if you render avatars in lists, cache url keyed by md5(strtolower(trim($email))) so repeat renders skip the whole builder. Invalidate on email change only.

Normalize before you hash. Gravatar matches on the MD5 of the lowercased, trimmed email. Normalize once at the boundary (form request, model accessor) and pass a canonical string to the library:

$email = strtolower(trim($user->email));

Retina / responsive. Gravatar is a plain image endpoint — request 2x and let CSS downscale:

$url2x = (clone $gravatar)->setSize(240)->getUrl($email);

Testing. Assert against a known hash rather than a fixture URL: md5('[email protected]') is deterministic, so URL assertions are stable and won't break when defaults change.

Gotchas and Tips

• MD5, not SHA. Gravatar's identifier is md5(strtolower(trim($email))). If avatars silently 404/default, a SHA hash or an un-trimmed email is almost always the cause.
• Default-image URLs must be encoded. d= accepts both keywords (identicon, monsterid, wavatar, retro, robohash, mm) and a full URL. A raw custom URL with its own query string will break the Gravatar URL — URL-encode it, or let the library do it (verify it does).
• Size is clamped 1–2048. Values outside the range are ignored by Gravatar and fall back to 80px, which looks like a "size option didn't work" bug rather than a validation error.
• Rating is advisory only. g/pg/r/x filters on Gravatar's side; your account-level setting wins. Don't rely on it for content moderation.
• HTTPS everywhere. Build https://www.gravatar.com/avatar/...; old secure.gravatar.com and gravatar.com variants still work but mixed-content warnings on http:// are a common copy-paste bug.
• Privacy/GDPR. Every avatar render sends an MD5 of your user's email to a third party. If that's a concern, proxy through your own endpoint or default to a generated identicon (e.g. UI Avatars) and only fall back to Gravatar on opt-in.
• Package age. Last release 2019-01-08, 12 stars. It's a small, stable surface, so low churn is fine — but there's no active maintenance. Pin it and expect to vendor/patch if PHP deprecations appear. Check composer.json for a ^7.x-only constraint before adding to an 8.3 project.
• No auto-discovery. Forgetting to bind it in Laravel is the most common "class not found" moment — there is no provider to discover.
• Debugging. Copy the generated URL into a browser and strip the query string to confirm the hash resolves. curl -I the URL to see whether you're getting a 302 (valid Gravatar) vs. a default image straight through.
• Extension points. The class is small; if you need signed URLs, local caching proxies, or multi-provider fallbacks, wrap it in a decorator (AvatarProvider interface with GravatarProvider and UiAvatarsProvider implementations) rather than subclassing and fighting the API.