Identicon Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require yzalis/identicon
   

   No additional configuration is required—just autoload the package.

2. First Use Case: Basic Identicon Generation

   use Yzalis\Identicon\Facades\Identicon;
   
   // Generate a simple identicon from a string (e.g., email or username)
   $identicon = Identicon::generate('user@example.com');
   
   // Output to a file (e.g., for avatar storage)
   $identicon->save(storage_path('app/public/avatars/user.png'));
   

3. Where to Look First

   • Facade: Yzalis\Identicon\Facades\Identicon (simplifies usage).
   • Builder: Yzalis\Identicon\IdenticonBuilder (for advanced customization).
   • Documentation: Check the GitHub repo for examples and API details.

Implementation Patterns

Core Workflows

1. Dynamic Avatar Generation

   // Generate and store avatars for users on registration/login
   $user->avatar_path = storage_path('app/public/avatars/' . $user->email_hash . '.png');
   Identicon::generate($user->email)->save($user->avatar_path);
   

2. Customizing Appearance

   // Use the builder for fine-grained control
   $identicon = Identicon::builder()
       ->size(200) // Width/height in pixels
       ->margin(10) // Padding around the identicon
       ->colors(['#FF5733', '#33FF57', '#3357FF']) // Custom palette
       ->generate('custom@user.com');
   

3. Integration with Laravel Views

   // Blade directive for easy templating
   @identicon('user@example.com', ['width' => 50, 'height' => 50])
   

   Register the directive in a service provider:

   Blade::directive('identicon', function ($expression) {
       return "<?php echo Yzalis\Identicon\Facades\Identicon::generate(" . $expression[0] . ")->toBase64(); ?>";
   });
   

4. Caching for Performance

   // Cache generated identicons to avoid reprocessing
   $cacheKey = 'identicon_' . md5($user->email);
   $path = cache()->remember($cacheKey, now()->addYears(1), function () use ($user) {
       $identicon = Identicon::generate($user->email);
       return $identicon->save(storage_path('app/public/avatars/' . $user->email_hash . '.png'));
   });
   

5. API Responses

   // Return identicons as base64 in JSON APIs
   return response()->json([
       'avatar' => Identicon::generate($user->email)->toBase64()
   ]);
   

Gotchas and Tips

Common Pitfalls

1. Input Hashing for Consistency

   • Identicons are generated from input strings. Always hash inputs (e.g., md5($user->email)) to ensure the same user gets the same identicon.
   • Example:

     $hash = md5(strtolower(trim($user->email)));
     Identicon::generate($hash)->save(...);
     

2. File Permissions

   • Ensure the storage/app/public directory is writable:

     chmod -R 755 storage/app/public
     

   • Symlink the directory if using Laravel’s public storage:

     php artisan storage:link
     

3. Color Clashes

   • Default color palettes may produce low-contrast identicons for light/dark backgrounds. Override colors for accessibility:

     Identicon::builder()->colors(['#000000', '#FFFFFF', '#FF0000'])->generate($input);
     

4. Size Limitations

   • The package defaults to 128x128 pixels. Large sizes (>500px) may degrade performance or exceed memory limits. Test with ->size() before production use.

5. Base64 vs. File Output

   • toBase64() returns a data URI (e.g., data:image/png;base64,...). Avoid embedding large base64 strings in HTML—use files or CDN-hosted assets instead.

Debugging Tips

1. Verify Input

   • Log the input string before generation to debug inconsistent outputs:

     \Log::debug('Generating identicon for:', ['input' => $user->email]);
     

2. Check Output Paths

   • Use storage_path() or public_path() to avoid hardcoding paths. Example:

     $path = public_path("avatars/{$user->id}.png");
     

3. Clear Cache

   • If identicons appear stale, clear Laravel’s cache:

     php artisan cache:clear
     php artisan view:clear
     

Extension Points

1. Custom Color Palettes

   • Extend the package by adding a Palette class or trait to manage dynamic color schemes (e.g., brand colors):

     class BrandPalette {
         public static function get(): array {
             return ['#2B5CE6', '#FF7A59', '#FF5733'];
         }
     }
     Identicon::builder()->colors(BrandPalette::get())->generate($input);
     

2. Shape Customization

   • The package uses a fixed grid. For advanced use, fork the library and modify Yzalis\Identicon\IdenticonGenerator to support custom shapes (e.g., circles, polygons).

3. Laravel Service Provider

   • Bind the builder to the container for dependency injection:

     $this->app->bind(IdenticonBuilder::class, function () {
         return new IdenticonBuilder(config('identicon.defaults'));
     });
     

4. Queue Jobs for Async Generation

   • Offload identicon generation to a queue (e.g., for large-scale user imports):

     dispatch(new GenerateIdenticonJob($user->email, $user->avatar_path));
     

     class GenerateIdenticonJob implements ShouldQueue {
         public function handle() {
             Identicon::generate($this->email)->save($this->path);
         }
     }