Getting Started

Minimal Steps to First Use

Installation:
```
composer require symfony/emoji
```
For PHP 8.4+ (Symfony 8.0+) or PHP 8.1+ (Symfony 7.4+).
Compress Data (Optional): If zlib is enabled, run:
```
php vendor/symfony/emoji/Resources/bin/compress
```
Reduces memory usage by ~50%.

First Use Case: Validate Emoji Input

use Symfony\Component\Emoji\EmojiData;

$input = "Hello 😊!";
if (EmojiData::isEmoji($input)) {
    // Handle emoji-only input
}

First Use Case: Convert Text to Emoji

$emoji = EmojiData::getEmoji('heart');
// Returns "❤️"

First Use Case: Get Emoji Metadata

$metadata = EmojiData::getMetadata('👨‍👩‍👧‍👦');
// Returns array with categories, keywords, etc.

Where to Look First

Official Documentation for API reference.
EmojiData class in vendor/symfony/emoji/EmojiData.php for core methods.
Resources/data/ directory for raw emoji datasets (uncompressed).

Implementation Patterns

Core Workflows

1. Emoji Validation

Use Case: Ensure user input contains only emoji (e.g., reactions, usernames).

use Symfony\Component\Emoji\EmojiData;

$reaction = request('reaction');
if (EmojiData::isEmoji($reaction)) {
    // Valid emoji
} else {
    return back()->withErrors(['reaction' => 'Invalid emoji']);
}

2. Normalization

Use Case: Standardize emoji sequences (e.g., family emoji with skin tones).

$normalized = EmojiData::normalize('👨👩👧👦'); // Returns "👨‍👩‍👧‍👦"

3. Text-to-Emoji Conversion

Use Case: Replace aliases (e.g., :heart:) with Unicode emoji.

$emoji = EmojiData::getEmoji('heart', 'text'); // Returns "❤️"

4. Emoji Picker Integration

Use Case: Fetch emoji by category for autocomplete.

$smileyEmojis = EmojiData::getEmojisByCategory('Smileys & Emotion');
// Returns array of emoji characters in the category

5. Localization Support

Use Case: Handle emoji aliases in non-English contexts.

$emoji = EmojiData::getEmoji('thumbs_up', 'text'); // Returns "👍"

Laravel-Specific Patterns

1. Service Provider Integration

public function register()
{
    $this->app->singleton(EmojiData::class, function () {
        return new EmojiData();
    });
}

Now inject EmojiData into controllers/services:

public function __construct(private EmojiData $emojiData) {}

2. Blade Directives

Create a Blade directive for quick emoji resolution:

Blade::directive('emoji', function ($expression) {
    return "<?php echo Symfony\Component\Emoji\EmojiData::getEmoji({$expression}, 'text'); ?>";
});

Usage:

@emoji('heart') <!-- Renders ❤️ -->

3. Caching Emoji Data

Cache metadata to reduce lookup overhead:

$metadata = Cache::remember("emoji_{$emoji}", now()->addHour(), function () use ($emoji) {
    return EmojiData::getMetadata($emoji);
});

4. Form Request Validation

Extend FormRequest to validate emoji fields:

public function rules()
{
    return [
        'reaction' => ['required', function ($attribute, $value, $fail) {
            if (!EmojiData::isEmoji($value)) {
                $fail('The :attribute must be a valid emoji.');
            }
        }],
    ];
}

5. Database Storage

Store normalized emoji to avoid inconsistencies:

$normalizedEmoji = EmojiData::normalize($userInput);
$user->reaction()->create(['content' => $normalizedEmoji]);

Integration Tips

1. Frontend Integration

For text emoji: Use the package directly in Blade templates.
For emoji images: Pair with a frontend library like emoji-mart or use native HTML entities.

Example (Vue.js):

// Fetch emoji metadata via API
axios.get('/api/emojis/smileys').then(response => {
    this.emojiList = response.data;
});

2. API Endpoints

Create a controller to expose emoji data:

public function getEmojisByCategory(string $category)
{
    return EmojiData::getEmojisByCategory($category);
}

Route:

Route::get('/api/emojis/{category}', [EmojiController::class, 'getEmojisByCategory']);

3. Testing

Mock EmojiData in tests:

$this->app->instance(EmojiData::class, Mockery::mock(EmojiData::class));

4. Unicode Updates

The package auto-updates with Symfony releases. Monitor Symfony’s changelog for emoji-related changes.
For critical apps, test updates in a staging environment.

Gotchas and Tips

Pitfalls

1. Skin Tone and ZWJ Sequences

Issue: Complex emoji like 👨‍👩‍👧‍👦 (family) may not normalize as expected if the input is split (e.g., 👨👩👧👦).
Fix: Always use EmojiData::normalize() before storage or validation.

$normalized = EmojiData::normalize('👨👩👧👦'); // Returns "👨‍👩‍👧‍👦"

2. Locale-Specific Behavior

Issue: The text locale may not cover all edge cases (e.g., rare emoji or custom aliases).
Fix: Test with your app’s supported locales. Extend the package if needed (see "Extension Points").

3. Memory Usage

Issue: Uncompressed data (~1–2MB) may impact high-traffic APIs.
Fix: Enable zlib compression via compress script (see "Getting Started").

4. Frontend Rendering

Issue: The package provides Unicode text, not images. Some browsers/OS may render emoji inconsistently.
Fix: Use a frontend library (e.g., emoji-mart) or CSS customization for consistent rendering.

5. PHP Version Requirements

Issue: Requires PHP 8.1+ (Symfony 7.4+) or PHP 8.4+ (Symfony 8.0+).
Fix: Upgrade PHP if using older versions. Check Symfony’s requirements.

Debugging Tips

1. Verify Emoji Data

Dump raw emoji data to debug:

dd(EmojiData::getEmojiData());

2. Check Normalization

Compare input vs. normalized output:

$input = '👨👩👧👦';
$normalized = EmojiData::normalize($input);
dd(bin2hex($input), bin2hex($normalized)); // Compare hex representations

Emoji Laravel Package