Gravatar Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require creativeorange/gravatar
   

   Publish the config (optional but recommended for customization):

   php artisan vendor:publish --provider="Creativeorange\Gravatar\GravatarServiceProvider" --tag="config"
   

2. First Use Case: Generate a Gravatar URL for an email in a controller:

   use Creativeorange\Gravatar\Facades\Gravatar;
   
   $url = Gravatar::get('user@example.com');
   

   Or directly in Blade:

   {{ Gravatar::get('user@example.com') }}
   

3. Quick Configuration: Override defaults in config/gravatar.php:

   'size' => 200,
   'default' => 'identicon',
   'rating' => 'pg',
   'secure' => true,
   

Implementation Patterns

Core Workflows

1. User Profile Avatars

• Controller:

  public function showProfile(User $user) {
      $avatarUrl = Gravatar::get($user->email, [
          'size' => 300,
          'default' => 'mp',
      ]);
      return view('profile', compact('avatarUrl'));
  }
  

• Blade:

  <img src="{{ Gravatar::get($user->email, ['size' => 300]) }}" alt="Profile">
  

2. Comment Threads (Bulk Processing)

• Cache URLs to avoid rate limits:

  public function showComments() {
      $comments = Comment::with('user')->get();
      foreach ($comments as $comment) {
          $comment->avatar = Gravatar::get($comment->user->email, [
              'size' => 80,
              'default' => 'wavatar',
          ]);
      }
      return view('comments', compact('comments'));
  }
  

3. Multi-Tenant Fallbacks

• Override defaults per tenant:

  Gravatar::setConfig([
      'default' => Tenant::current()->fallback ?? 'retro',
  ]);
  

4. Existence Checks

• Verify if a Gravatar exists for an email:

  if (Gravatar::exists('user@example.com')) {
      // Use Gravatar
  } else {
      // Fallback logic
  }
  

5. Blade Directives

• Shortcut for common use cases:

  {{ Gravatar::image('user@example.com', ['size' => 150]) }}
  

  Renders:

  <img src="..." alt="Gravatar" width="150" height="150">
  

Integration Tips

Service Container Binding

• Bind a custom HTTP client for testing/mocking:

  $this->app->bind('gravatar.http.client', function () {
      return new MockHttpClient();
  });
  

Event Listeners

• Cache Gravatar URLs on user creation/update:

  use Creativeorange\Gravatar\Events\GravatarCached;
  
  GravatarCached::dispatch($user->email, $url);
  

Queue Jobs

• Offload avatar generation for high-traffic pages:

  Gravatar::queueGet($email, $options);
  

Dynamic Configs

• Override configs per request:

  Gravatar::setConfig(['size' => request()->wantsJson() ? 50 : 200]);
  

Gotchas and Tips

Pitfalls

1. Cache Invalidation

• Issue: Cached URLs may not update if the email changes (e.g., user updates email).
• Fix: Clear cache manually or use events:

  Gravatar::clearCache($oldEmail);
  Gravatar::clearCache($newEmail);
  

2. Rate Limiting

• Issue: Gravatar limits to 1,000 requests/hour/IP. Bulk operations may hit this.
• Fix: Use caching or queue jobs:

  Gravatar::queueGet($email); // Process asynchronously
  

3. SHA-256 Hashing

• Issue: Older code may use MD5 hashing (deprecated by Gravatar).
• Fix: The package auto-updates to SHA-256 (since v1.0.25). No action needed unless customizing hashing.

4. Blade Context

• Issue: Blade directives may fail in non-Blade contexts (e.g., API responses).
• Fix: Use the facade directly:

  $url = Gravatar::get($email); // Instead of {{ Gravatar::get($email) }}
  

5. Config Overrides

• Issue: Global config may conflict with per-request overrides.
• Fix: Use setConfig() sparingly or merge configs:

  Gravatar::setConfig(array_merge(config('gravatar'), ['size' => 200]));
  

Debugging Tips

1. Enable Debug Mode

• Log Gravatar API requests/responses:

  'debug' => env('GRAVATAR_DEBUG', false),
  

2. Mock HTTP Client

• Test without hitting Gravatar’s API:

  $this->app->bind('gravatar.http.client', function () {
      return new MockHttpClient();
  });
  

3. Validate Email Hashing

• Ensure emails are hashed correctly (SHA-256):

  $hash = Gravatar::hash('user@example.com');
  // Should match Gravatar's output
  

4. Check Headers

• Verify Gravatar’s response headers for errors:

  $response = Gravatar::getHttpClient()->get($url);
  $response->getHeaders();
  

Extension Points

1. Custom Hashing

• Override the hashing algorithm:

  Gravatar::setHashAlgorithm(function ($email) {
      return hash('sha1', strtolower(trim($email)));
  });
  

2. HTTP Client

• Replace the default Guzzle client:

  $this->app->bind('gravatar.http.client', function () {
      return new SymfonyHttpClient();
  });
  

3. Events

• Listen for Gravatar-related events:

  GravatarCached::listen(function ($email, $url) {
      // Log or cache the URL
  });
  

4. Blade Extensions

• Add custom Blade directives:

  Blade::directive('gravatar', function ($email) {
      return "<?php echo Creativeorange\Gravatar\Facades\Gravatar::get($email); ?>";
  });
  

5. Fallback Logic

• Extend fallback behavior:

  Gravatar::setFallback(function ($email) {
      return "https://example.com/fallback/{$email}.png";
  });