Emojibase Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require milesj/emojibase
   

   The package provides no configuration—just autoloads JSON datasets and utility classes.

2. First Use Case: Fetching Emoji Data

   use MilesJ\EmojiBase\Facades\EmojiBase;
   
   // Get all emojis as an array
   $emojis = EmojiBase::all();
   
   // Get a specific emoji by shortcode (e.g., "😊")
   $emoji = EmojiBase::get('smile');
   

3. Where to Look First

   • Facade: MilesJ\EmojiBase\Facades\EmojiBase (primary entry point).
   • JSON Datasets: Located in vendor/milesj/emojibase/resources/data/ (e.g., emojis.json, emoji-sequences.json).
   • Regex Patterns: Available via EmojiBase::regex() for validation/extraction.

Implementation Patterns

Core Workflows

1. Emoji Lookup & Rendering

// Get emoji details (shortcode, name, unicode, etc.)
$details = EmojiBase::get('heart_eyes')->toArray();

// Render emoji in a Blade view
echo EmojiBase::render('grinning_face'); // Outputs: 😀

2. Validation & Sanitization

// Check if a string contains valid emojis
$isValid = EmojiBase::containsEmoji('Hello 👋!');

// Extract emoji shortcodes from text
$shortcodes = EmojiBase::extractShortcodes('I ❤️ coding!');
// Returns: ['heart_eyes']

3. Localized Emoji Support

// Get emojis for a specific locale (e.g., Japanese)
$jpEmojis = EmojiBase::locale('ja')->all();

// Render emoji with localized name
echo EmojiBase::locale('es')->render('thumbs_up'); // "👍 Pulgar arriba"

4. Regex Integration

// Validate user input for emoji-only strings
$pattern = EmojiBase::regex()->emojiOnly();
preg_match($pattern, '🚀', $matches);

// Extract emoji sequences (e.g., "👨‍👩‍👧‍👦")
$sequences = EmojiBase::regex()->sequences();

5. Custom Emoji Sets

// Merge with custom emojis (e.g., for a branded app)
$customEmojis = [
    'rocket' => ['unicode' => '🚀', 'name' => 'Custom Rocket']
];
EmojiBase::merge($customEmojis);

Integration Tips

Laravel Blade Directives

Create a custom Blade directive for emoji rendering:

// In AppServiceProvider@boot()
Blade::directive('emoji', function ($expression) {
    return "<?php echo \\MilesJ\\EmojiBase\\Facades\\EmojiBase::render({$expression}); ?>";
});

Usage in Blade:

@emoji('smiling_face_with_tear')

Form Request Validation

use MilesJ\EmojiBase\Facades\EmojiBase;

public function rules()
{
    return [
        'bio' => [
            'string',
            function ($attribute, $value, $fail) {
                if (EmojiBase::containsEmoji($value) && !EmojiBase::isValid($value)) {
                    $fail('Invalid emoji used.');
                }
            },
        ],
    ];
}

API Responses

return response()->json([
    'message' => 'Success!',
    'emoji' => EmojiBase::get('fire')->toArray(),
]);

Gotchas and Tips

Pitfalls

1. Unicode Normalization

   • Emoji sequences (e.g., "👨‍👩‍👧‍👦") may not render correctly in all environments. Test in production early.
   • Fix: Use EmojiBase::normalize() to ensure consistent output.

2. Locale-Specific Shortcodes

   • Some emojis have locale-specific shortcodes (e.g., a vs. jp_a for "👋").
   • Tip: Always specify a locale when working with shortcodes:

     EmojiBase::locale('ja')->get('a'); // Japanese "wave"
     

3. Regex Performance

   • The emojiOnly regex is strict and may slow down large inputs.
   • Optimization: Cache regex patterns if used frequently:

     $cachedRegex = EmojiBase::regex()->emojiOnly();
     

4. Custom Emoji Overrides

   • Merging custom emojis replaces existing ones with the same shortcode.
   • Workaround: Use unique shortcodes for custom emojis.

5. Deprecated Emojis

   • The dataset includes deprecated emojis (marked with deprecated: true).
   • Filtering:

     $activeEmojis = EmojiBase::all()->where('deprecated', false);
     

Debugging Tips

1. Inspect Raw Data Dump the full dataset to debug:

   dd(EmojiBase::all()->toArray());
   

2. Check for Missing Emojis If an emoji isn’t found, verify the shortcode:

   $emoji = EmojiBase::get('unknown_shortcode');
   if (!$emoji) {
       // Shortcode doesn’t exist
   }
   

3. Unicode Rendering Issues

   • If emojis display as boxes (□), your environment lacks proper font support.
   • Fix: Use a Unicode-compatible font (e.g., Noto Color Emoji) in your app.

4. Regex Debugging Test regex patterns separately:

   $pattern = EmojiBase::regex()->emojiOnly();
   preg_last_error_msg(); // Check for errors
   

Extension Points

1. Custom Data Sources Extend the package by adding your own JSON dataset:

   EmojiBase::extend('custom', function () {
       return collect(json_decode(file_get_contents('path/to/custom.json'), true));
   });
   

   Usage:

   EmojiBase::source('custom')->all();
   

2. Hooks for Preprocessing Override the EmojiBase class to modify data before rendering:

   class CustomEmojiBase extends \MilesJ\EmojiBase\EmojiBase {
       public function render($shortcode) {
           $emoji = $this->get($shortcode);
           if ($emoji && $emoji->unicode === '🔥') {
               return '🔥 (Custom!)';
           }
           return parent::render($shortcode);
       }
   }
   

   Bind in AppServiceProvider:

   $this->app->bind(\MilesJ\EmojiBase\Contracts\EmojiBase::class, CustomEmojiBase::class);
   

3. Event Listeners Listen for emoji events (e.g., emoji.rendering):

   EmojiBase::listen('emoji.rendering', function ($shortcode, $emoji) {
       // Log or modify emoji before rendering
   });
   

4. Testing Use the EmojiBaseTestCase trait for unit tests:

   use MilesJ\EmojiBase\Testing\EmojiBaseTestCase;
   
   class EmojiTest extends EmojiBaseTestCase {
       public function testRenderEmoji() {
           $this->assertEquals('😊', EmojiBase::render('smile'));
       }
   }