Identicon Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require bitverse/identicon
   

   Add to composer.json if using a monorepo or custom package setup.

2. First Use Case: Generate a Basic Identicon

   use Bitverse\Identicon\Identicon;
   use Bitverse\Identicon\Generator\RingsGenerator;
   use Bitverse\Identicon\Preprocessor\MD5Preprocessor;
   
   $identicon = new Identicon(new MD5Preprocessor(), new RingsGenerator());
   $svg = $identicon->getIcon('user@example.com');
   file_put_contents(public_path('avatars/user.svg'), $svg);
   

   • Where to look first: The RingsGenerator is the default and most visually distinct option. For quick testing, use MD5Preprocessor (default) to ensure consistent hashing.

Implementation Patterns

Core Workflow

1. Preprocessing

   • Use MD5Preprocessor for deterministic hashing (default).
   • Override with custom logic (e.g., SHA1Preprocessor) if needed:

     $preprocessor = new \Bitverse\Identicon\Preprocessor\SHA1Preprocessor();
     

2. Generator Selection

   • RingsGenerator: Classic circular pattern (best for avatars).
   • BlocksGenerator: Grid-based (simpler, faster).
   • Custom Generators: Extend \Bitverse\Identicon\Generator\AbstractGenerator for unique styles.

3. Dynamic Generation in Controllers

   public function showAvatar(Request $request, $email)
   {
       $identicon = app(Identicon::class);
       return response($identicon->getIcon($email))
           ->header('Content-Type', 'image/svg+xml');
   }
   

4. Caching Identicons

   • Cache the SVG output in Redis or filesystem to avoid reprocessing:

     $cacheKey = 'identicon:' . md5($email);
     $svg = cache()->remember($cacheKey, now()->addDays(30), function() use ($email) {
         return $identicon->getIcon($email);
     });
     

5. Integration with Blade

   // In a service provider
   Blade::directive('identicon', function ($email) {
       return "<?php echo (new \\Bitverse\\Identicon\\Identicon())->getIcon($email); ?>";
   });
   

   Usage:

   <img src="{{ identicon('user@example.com') }}" alt="Identicon">
   

Gotchas and Tips

Pitfalls

1. SVG Output Size

   • Default SVG is not optimized. Use DOMDocument to minify:

     $dom = new DOMDocument();
     $dom->loadXML($svg);
     $dom->formatOutput = true;
     $minified = $dom->saveXML();
     

   • Tip: Store minified SVGs in production.

2. Color Consistency

   • Colors are derived from the hash. Use Color::parseHex() for custom palettes:

     $generator->setBackgroundColor(Color::parseHex('#f0f0f0'));
     $generator->setForegroundColors([Color::parseHex('#3498db'), Color::parseHex('#e74c3c')]);
     

   • Gotcha: Hardcoding colors breaks determinism. Use Color::fromHash() for dynamic but consistent colors.

3. Performance

   • BlocksGenerator is faster than RingsGenerator (2-3x speedup).
   • Tip: Benchmark generators if processing >1000 identicons/sec.

4. Deprecated Methods

   • Avoid Identicon::generate() (deprecated). Use getIcon() instead.

5. Last Release (2015)

   • Risk: No active maintenance. Test thoroughly in production.
   • Mitigation: Fork and update dependencies (e.g., phpseclib for hashing) if critical.

Debugging

1. Invalid SVG Output

   • Check for malformed strings (e.g., null or non-string inputs).
   • Validate with simplexml_load_string($svg).

2. Color Clashes

   • Use Color::parseHex() with high-contrast pairs (e.g., #2c3e50 + #ecf0f1).

3. Caching Issues

   • Clear cache when updating generators/preprocessors:

     cache()->forget('identicon:*');
     

Extension Points

1. Custom Generators Extend AbstractGenerator to create new patterns:

   class HexagonGenerator extends AbstractGenerator {
       protected function generatePattern($hash) {
           // Custom logic
       }
   }
   

2. Preprocessor Overrides Implement \Bitverse\Identicon\Preprocessor\PreprocessorInterface for custom hashing (e.g., user ID + salt):

   class CustomPreprocessor implements PreprocessorInterface {
       public function preprocess($input) {
           return hash('sha256', $input . config('app.salt'));
       }
   }
   

3. Symfony Integration Use BitverseIdenticonBundle for Twig filters and routing helpers (if upgrading to Symfony 5+).