Litemoji Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**
   ```bash
   composer require elvanto/litemoji:^5.2.0

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:` (now includes Emojibase 16.0 mappings)
   

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 (now updated for PHP 8.3/8.4 and Emojibase 16.0).
   • Emoji Data to explore new Emojibase 16.0 additions (e.g., :person_balancing:).
   • Tests for edge-case examples with updated emoji mappings.

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); // Now includes Emojibase 16.0 mappings
   $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 (now includes Emojibase 16.0):

   $customEmoji = [
       '🪐' => ':new_earth_asia:' // Example of a new Emojibase 16.0 emoji
   ];
   $converter = new Litemoji($customEmoji);
   

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(':person_balancing:') !!} <!-- New Emojibase 16.0 emoji -->
   

5. API Responses Normalize emoji formats in JSON responses:

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

6. PHP 8.3/8.4 Features Leverage new PHP features for cleaner code:

   // Use named arguments (PHP 8.1+) for constructor options
   $converter = new Litemoji(
       cdnUrl: 'https://your-cdn.com/emoji/',
       htmlTemplate: '<img src="{url}" alt="{alt}" class="emoji {size}">'
   );
   

Gotchas and Tips

Pitfalls

1. Unicode Normalization

   • Some new Emojibase 16.0 emoji (e.g., :person_balancing:) may require explicit handling:

     $converter->normalizedToShortcode('🪀'); // Returns `:person_balancing:` (if supported).
     

2. HTML Output Quirks

   • Customize the HTML template via the constructor (now compatible with PHP 8.3/8.4):

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

3. Shortcode Collisions

   • New Emojibase 16.0 shortcodes (e.g., :new_earth_asia:) may conflict with custom mappings. Validate with:

     if (!$converter->hasShortcode(':new_earth_asia:')) {
         // Handle customization
     }
     

4. Performance

   • Cache converted results in Laravel (now optimized for PHP 8.3/8.4):

     $cacheKey = 'emoji_'.hash('xxh128', $text); // Use PHP 8.3's xxHash for better performance
     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 new Emojibase 16.0 additions:

   dd($converter->getEmojiData()); // Look for new entries like `:person_balancing:`
   

3. Custom Emoji Extension Override the default emoji set by passing a custom array (now includes Emojibase 16.0):

   $customEmoji = [
       '🪐' => ':new_earth_asia:',
       ':new_earth_asia:' => ['alt' => 'earth asia', 'url' => '/path/to/new-earth-asia.png']
   ];
   $converter = new Litemoji($customEmoji);
   

Configuration Quirks

• Image Paths: The package uses a default CDN for emoji images. Override in the constructor (PHP 8.3/8.4 compatible):

  $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 (now with PHP 8.3/8.4 support):

   public function unicodeToShortcode(string $text): string {
       // 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 (now with Emojibase 16.0 data).

3. Laravel Service Provider Bind the converter to the container for dependency injection (PHP 8.3/8.4 compatible):

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

4. New Emojibase 16.0 Features Explore new emoji additions like:

   • :person_balancing: (🪀)
   • :new_earth_asia: (🪐)
   • Use $converter->getEmojiData() to discover all updates.

NO_UPDATE_NEEDED would not apply here due to the meaningful updates in PHP version support and Emojibase 16.0 integration.