Litemoji Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require elvanto/litemoji
   

   No additional configuration is required—just autoload the package.

2. First Use Case: Convert Unicode to Shortcode

   use Elvanto\Litemoji\Litemoji;
   
   $converter = new Litemoji();
   $shortcode = $converter->unicodeToShortcode('🔥'); // Returns `:fire:`
   

3. First Use Case: Convert Shortcode to HTML

   $html = $converter->shortcodeToHtml(':fire:'); // Returns `<img src="..." alt="fire" class="emoji">`
   

4. Where to Look First

   • Source Code (if available) for customization.
   • Emoji Data to understand mappings.
   • Tests for edge-case examples.

Implementation Patterns

Core Workflows

1. Emoji Conversion Pipeline Use the package to standardize emoji formats across your app:

   $text = "Hello 🔥! Use :fire: in code.";
   $shortcodes = $converter->unicodeToShortcode($text); // "Hello :fire:! Use :fire: in code."
   $html = $converter->shortcodeToHtml($shortcodes);    // Renders emoji images.
   

2. Validation & Sanitization Ensure input is safe before conversion:

   if ($converter->isValidShortcode(':fire:')) {
       $html = $converter->shortcodeToHtml(':fire:');
   }
   

3. Custom Emoji Handling Extend the default emoji set (see Gotchas for details).

4. Integration with Laravel Blade Create a helper for views:

   // app/Helpers/EmojiHelper.php
   use Elvanto\Litemoji\Litemoji;
   
   function emoji($text) {
       return app(Litemoji::class)->shortcodeToHtml($text);
   }
   

   Use in Blade:

   {!! emoji(':fire:') !!}
   

5. API Responses Normalize emoji formats in JSON responses:

   return response()->json([
       'message' => 'Check this out: ' . $converter->unicodeToShortcode('🚀')
   ]);
   

Gotchas and Tips

Pitfalls

1. Unicode Normalization

   • Some Unicode emoji may not map directly (e.g., skin-tone modifiers like 👨🏽). Use normalizedToShortcode() for consistency:

     $converter->normalizedToShortcode('👨🏽'); // Returns `:man:🏽` (if supported).
     

2. HTML Output Quirks

   • Customize the HTML template via the constructor:

     $converter = new Litemoji([
         'html_template' => '<img src="{url}" alt="{alt}" class="emoji {size}">'
     ]);
     

   • Ensure your template includes {url}, {alt}, and {size} placeholders.

3. Shortcode Collisions

   • If you add custom emoji, avoid conflicts with existing shortcodes (e.g., :flag: for flags).

4. Performance

   • Caching is not built-in. Cache converted results in Laravel:

     $cacheKey = 'emoji_'.md5($text);
     return Cache::remember($cacheKey, now()->addHours(1), function() use ($converter, $text) {
         return $converter->shortcodeToHtml($text);
     });
     

Debugging Tips

1. Check Emoji Existence

   if (!$converter->hasShortcode(':nonexistent:')) {
       // Handle unknown emoji (e.g., fallback to text).
   }
   

2. Inspect Mappings Dump the emoji data to understand mappings:

   dd($converter->getEmojiData());
   

3. Custom Emoji Extension Override the default emoji set by passing a custom array:

   $customEmoji = [
       '🔥' => ':custom_fire:',
       ':custom_fire:' => ['alt' => 'custom fire', 'url' => '/path/to/custom-fire.png']
   ];
   $converter = new Litemoji($customEmoji);
   

Configuration Quirks

• Image Paths: The package uses a default CDN for emoji images. Override in the constructor:

  $converter = new Litemoji([
      'cdn_url' => 'https://your-cdn.com/emoji/'
  ]);
  

• Size Classes: Adjust emoji sizes via the size key in the HTML template or constructor options.

Extension Points

1. Event Hooks Extend functionality by subclassing Litemoji and overriding methods like:

   public function unicodeToShortcode($text) {
       // Pre-process text (e.g., replace custom patterns).
       return parent::unicodeToShortcode($text);
   }
   

2. Custom Storage Replace the emoji data source by extending the Emoji class or injecting a custom repository.

3. Laravel Service Provider Bind the converter to the container for dependency injection:

   // app/Providers/AppServiceProvider.php
   public function register() {
       $this->app->singleton(Litemoji::class, function () {
           return new Litemoji();
       });
   }