Emoji Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/emoji
   

   No additional configuration is required—just autoload.

2. First Use Case: Convert text to emoji in a Blade view:

   use Spatie\Emoji\Emoji;
   
   // In a controller or service
   $converted = Emoji::emojify('Hello :heart: world!');
   echo $converted; // Outputs: Hello ♥ world!
   

3. Where to Look First:

   • Documentation (official docs are minimal but clear).
   • Spatie\Emoji\Emoji class methods: emojify(), emojifyShortcodes(), emojifyUnicode().
   • Test cases in the package’s tests/ directory for edge cases.

Implementation Patterns

Core Workflows

1. Text Conversion:

   • Shortcodes to Unicode:

     Emoji::emojify(':smile:') // → 😊
     Emoji::emojifyShortcodes('I :thumbsup: this!') // → I ✅ this!
     

   • Unicode Preservation:

     Emoji::emojifyUnicode('Already has 😊') // → 😊 (unchanged)
     

2. Blade Directives (for reusable templates):

   // In AppServiceProvider::boot()
   Blade::directive('emoji', function ($expression) {
       return "<?php echo \\Spatie\\Emoji\\Emoji::emojify({$expression}); ?>";
   });
   
   // Usage in Blade:
   @emoji('$message')
   

3. Dynamic Emoji Handling:

   • Filter user input (e.g., comments) before storage:

     $cleanedText = Emoji::emojify($request->input('comment'));
     

   • Sanitize emoji in API responses:

     return response()->json(['content' => Emoji::emojify($data['content'])]);
     

4. Custom Shortcodes: Extend the package by adding custom mappings (see "Gotchas" for implementation).

Integration Tips

• Database Storage: Store emoji as Unicode in the DB (e.g., ♥ as U+2665). Avoid shortcodes in DB if possible for consistency.
• Localization: Use Emoji::emojify() with locale-aware text (e.g., 🇺🇸 for flags).
• Performance: Cache converted strings if processing large volumes (e.g., bulk comments):

  $cacheKey = 'emoji_'.$text;
  $converted = Cache::remember($cacheKey, now()->addHours(1), fn() => Emoji::emojify($text));
  

Gotchas and Tips

Pitfalls

1. Double Conversion: Converting already-converted text (e.g., Unicode → shortcode → Unicode) may corrupt emoji. Always check input type:

   if (str_contains($text, ':')) {
       return Emoji::emojifyShortcodes($text);
   }
   return Emoji::emojifyUnicode($text);
   

2. Shortcode Conflicts: Shortcodes like :thumbsup: may clash with user input (e.g., :thumbs up:). Use emojifyShortcodes() sparingly or pre-process text.

3. Non-Standard Emoji: The package uses a subset of Unicode emoji. For custom emoji (e.g., Slack-style), extend the package (see below).

4. Blade Caching: If using @emoji directives, clear Blade cache after adding custom shortcodes:

   php artisan view:clear
   

Debugging Tips

• Verify Emoji Support: Check if your terminal/editor supports Unicode output. Test with:

  echo Emoji::emojify(':grinning:');
  

  If it shows ?:grinning:?, your environment lacks Unicode support.

• Log Unmatched Shortcodes: Override the emojifyShortcodes method to log unknown shortcodes:

  Emoji::emojifyShortcodes($text, true); // Second param enables logging
  

Extension Points

1. Custom Shortcodes: Extend the Spatie\Emoji\Shortcode class or override the getShortcodeReplacements() method:

   // In a service provider
   Emoji::extend(function ($emoji) {
       $emoji->addShortcode('custom', '🎨');
   });
   

2. Custom Emoji Sets: Replace the default emoji list by binding a custom Emoji instance:

   $app->bind(Spatie\Emoji\Emoji::class, function ($app) {
       return new CustomEmoji();
   });
   

3. Whitelist/Blacklist: Filter emoji by Unicode block (e.g., block flags only):

   $flags = Emoji::emojify('🇺🇸🇬🇧', ['flags']);
   

Pro Tips

• Slack/MS Teams Integration: Use emojifyShortcodes() to convert Slack-style :emoji: to Unicode before displaying in Laravel apps.
• Markdown Support: Combine with parsedown or commonmark to convert Markdown with emoji:

  use League\CommonMark\CommonMarkConverter;
  $converter = new CommonMarkConverter();
  $html = $converter->convert(Emoji::emojify($markdownText));
  

• Testing: Use the package’s EmojiTest class as a reference for unit tests:

  $this->assertEquals('😊', Emoji::emojify(':smile:'));