Laravel Gravatar Laravel Package

Getting Started

1. Install the package:

   composer require thomaswelton/laravel-gravatar
   

2. Laravel 5.5+ auto-discovers Thomaswelton\LaravelGravatar\LaravelGravatarServiceProvider and the Gravatar facade. On older apps, register manually in config/app.php:

   'providers' => [Thomaswelton\LaravelGravatar\LaravelGravatarServiceProvider::class],
   'aliases'   => ['Gravatar' => Thomaswelton\LaravelGravatar\Facades\Gravatar::class],
   

3. Publish the config so defaults (size, rating, default image, secure URL) are editable:

   php artisan vendor:publish --provider="Thomaswelton\LaravelGravatar\LaravelGravatarServiceProvider"
   

   You should now have config/gravatar.php.
4. First use case: replace a hardcoded avatar URL in a Blade view. Open resources/views/... and swap the <img src="..."> for the helper, then smoke-test in Tinker with Gravatar::src('[email protected]') to confirm you get a https://secure.gravatar.com/avatar/<md5>?... URL.

The library is a thin URL builder around Gravatar's public API — the core surface is src($email), image($email, $alt, $attributes), and exists($email). Verify the exact signatures against the version you install before spreading them across the codebase.

Implementation Patterns

Blade component (the 90% case). Wrap it once so views never call the facade directly:

{{-- resources/views/components/avatar.blade.php --}}
@props(['user', 'size' => 48])
<img src="{{ Gravatar::src($user->email) }}"
     alt="{{ $user->name }}"
     width="{{ $size }}" height="{{ $size }}"
     class="rounded-full">

Model accessor. Centralize the email normalization and expose a stable attribute:

public function getAvatarUrlAttribute(): string
{
    return Gravatar::src(strtolower(trim($this->email)));
}

Service wrapper for portability. Because the package is archived, hide it behind your own contract so swapping to creativeorange/gravatar or a raw URL builder is a one-file change:

interface AvatarProvider { public function url(string $email, int $size = 80): string; }

Bind the Gravatar implementation in a service provider; inject it into controllers and mailables rather than using the facade.

Config-driven defaults. Read env values into config/gravatar.php (GRAVATAR_SIZE, GRAVATAR_DEFAULT=identicon, GRAVATAR_RATING=g) so staging and production can differ without code changes. In mail templates and notifications, use src() (which returns an absolute URL) — relative URLs break in email clients.

Presence checks — cache aggressively. Gravatar::exists($email) performs a synchronous HTTP request. For a users index page, that's an N+1 over the network. Either cache the boolean (Cache::remember("gravatar:{$hash}", now()->addDay(), ...)) or skip exists() entirely and let Gravatar's d=404 return a 404, handling the fallback client-side with onerror.

Testing. Assert on the generated URL rather than hitting Gravatar: $this->assertStringContainsString(md5('[email protected]'), $user->avatar_url);. In feature tests, bind a fake AvatarProvider so no outbound calls occur.

Gotchas and Tips

• Archived since 2020, Laravel 5 era. Before adopting, check the illuminate/support constraint in its composer.json. On Laravel 9/10/11 you will likely need --with-all-dependencies or a fork; PHP 8.1+ may surface deprecation notices from untyped returns. If you want zero maintenance risk, replicate the feature with a five-line URL builder instead of adding the dependency.
• Facade alias collisions. Gravatar is a common alias; if another package registers it, use the fully-qualified facade or alias it as GravatarHelper.
• Email normalization matters. Gravatar hashes the lowercased, trimmed email. If your app stores mixed-case addresses and the package doesn't normalize, users will silently get the mystery-man default. Normalize before calling.
• Parameter limits. Size is clamped to 1–2048; rating must be one of g, pg, r, x; default accepts mp, identicon, monsterid, wavatar, retro, robohash, blank, or a URL-encoded image URL. Invalid values fall back silently, which makes bugs hard to spot.
• Mixed content. Older versions default to http://www.gravatar.com; on HTTPS apps this triggers browser mixed-content blocks. Set the secure config flag (or override the base URL) and confirm the output starts with https://.
• exists() is a network call. It's the single biggest performance trap in this package — never call it inside a loop or a Blade partial rendered per row. Cache results, or default to a local fallback image and skip the check.
• Config caching. After changing GRAVATAR_* env vars, run php artisan config:clear; otherwise you'll debug a config change that never took effect.
• Limited extension points. There's no driver system or event hook. If you need multiple avatar backends (Gravatar + uploaded avatars + initials), wrap the package rather than patching it — a fork is the realistic path for anything beyond URL generation.
• Privacy note. Hashing doesn't hide the email from Gravatar's servers; the md5 is trivially reversible for common addresses. Avoid using it for internal/admin users without a policy decision.