Getting Started

Minimal Steps

Installation:
```
composer require symfony/emoji
```
For PHP 8.4+ (Symfony 8.0+), use ^8.0. For Laravel 10.x, ^7.4 is recommended.

First Use Case: Validate if a string contains only emoji:

use Symfony\Component\Emoji\EmojiData;

$input = "😊❤️";
if (EmojiData::isEmoji($input)) {
    // Process emoji-only input
}

Where to Look First:
- Official Documentation for API reference.
- EmojiData class for core functionality (validation, normalization, lookup).
- EmojiRegistry for accessing emoji metadata (names, groups, skin tones).

Implementation Patterns

Core Workflows

1. Emoji Validation

Use Case: Restrict user input to emoji-only (e.g., reactions, usernames).

use Symfony\Component\Emoji\EmojiData;

$reaction = "👍";
if (EmojiData::isEmoji($reaction)) {
    // Valid emoji
}

Laravel Integration:

use Illuminate\Support\Facades\Validator;

$validator = Validator::make(['reaction' => $request->reaction], [
    'reaction' => 'required|string|emoji', // Custom rule
]);

Create a custom validation rule:

namespace App\Rules;
use Symfony\Component\Emoji\EmojiData;

class Emoji implements Rule {
    public function passes($attribute, $value) {
        return EmojiData::isEmoji($value);
    }
}

2. Normalization

Use Case: Ensure consistent emoji sequences (e.g., skin tones, ZWJ families).

use Symfony\Component\Emoji\EmojiData;

$emoji = "👨‍👩‍👧‍👦";
$normalized = EmojiData::normalize($emoji); // Standardized sequence

Laravel Eloquent:

use Illuminate\Database\Eloquent\Model;

class Reaction extends Model {
    protected $casts = [
        'emoji' => 'string', // Store normalized emoji
    ];

    public function setEmojiAttribute($value) {
        $this->attributes['emoji'] = EmojiData::normalize($value);
    }
}

3. Emoji Lookup and Metadata

Use Case: Power emoji pickers, autocomplete, or categorized search.

use Symfony\Component\Emoji\EmojiRegistry;

$registry = new EmojiRegistry();
$emoji = $registry->getEmoji('heart'); // Returns "❤️"
$group = $registry->getGroup('Smileys & Emotion'); // List of emoji in group

Laravel Service Provider:

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Symfony\Component\Emoji\EmojiRegistry;

class EmojiServiceProvider extends ServiceProvider {
    public function register() {
        $this->app->singleton(EmojiRegistry::class, function () {
            return new EmojiRegistry();
        });
    }
}

Bind in config/app.php:

'aliases' => [
    'Emoji' => App\Providers\EmojiServiceProvider::class,
],

4. Localization (Text Aliases)

Use Case: Support :heart: syntax for non-technical users.

use Symfony\Component\Emoji\EmojiData;

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

Blade Directive:

// app/Providers/BladeServiceProvider.php
Blade::directive('emoji', function ($alias) {
    return "<?php echo Symfony\Component\Emoji\EmojiData::getEmojiForTextAlias({$alias}, 'text'); ?>";
});

Usage:

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

5. Caching Emoji Data

Use Case: Reduce memory usage in high-traffic apps.

use Symfony\Component\Emoji\EmojiRegistry;
use Illuminate\Support\Facades\Cache;

$registry = Cache::remember('emoji.registry', 3600, function () {
    return new EmojiRegistry();
});

Integration Tips

Compress Emoji Data (Optional): If zlib is enabled, run:
```
php vendor/symfony/emoji/Resources/bin/compress
```
This reduces memory usage by ~50%.
Laravel Cache Integration: Cache emoji metadata for performance:
```
Cache::forever('emoji.groups', $registry->getGroups());
```

Frontend Integration:

For emoji rendering, use a frontend library like emoji-mart or Laravel’s native support:

// Example with emoji-mart (Vue/React)
import Picker from '@emoji-mart/vue';
<Picker @emoji-select={handleEmojiSelect} />

For Blade, use the directive above or output raw emoji:

{!! $emoji !!} <!-- Escaped via Blade's auto-escaping -->

Testing: Use Laravel’s testing helpers to assert emoji validation:

use Symfony\Component\Emoji\EmojiData;

$this->assertTrue(EmojiData::isEmoji("😊"));
$this->assertFalse(EmojiData::isEmoji("hello"));

Gotchas and Tips

Pitfalls

Emoji Sequences vs. Characters:
- Some emoji are multi-character sequences (e.g., 👨‍👩‍👧‍👦). Use EmojiData::isEmoji() for validation, not ctype_alnum().
- Fix: Always normalize emoji before validation:
```
EmojiData::isEmoji(EmojiData::normalize($input));
```
Skin Tones and ZWJ:
- Emoji with skin tones (e.g., 👨🏽‍👩🏽‍👧🏽‍👦) or Zero-Width Joiners (ZWJ) may render inconsistently across platforms.
- Fix: Normalize sequences before storage:
```
$normalized = EmojiData::normalize("👨🏽‍👩🏽‍👧🏽‍👦");
```
Locale-Specific Aliases:
- The text locale supports aliases like :heart:, but not all emoji have aliases.
- Fix: Fall back to Unicode lookup:
```
$emoji = EmojiData::getEmojiForTextAlias($alias, 'text') ?: EmojiData::getEmoji($alias);
```
Memory Usage:
- The uncompressed dataset is ~1MB. In high-traffic apps, cache the EmojiRegistry instance.
- Fix: Use Laravel’s cache or singleton pattern:
```
$registry = app()->singleton(EmojiRegistry::class, fn() => new EmojiRegistry());
```
PHP Version Requirements:
- Requires PHP 8.1+. Laravel 10.x (PHP 8.2+) is fully compatible.
- Fix: Use ^7.4 for Laravel 9.x (PHP 8.1) or ^8.0 for PHP 8.4+.
Emoji Groups and Categories:
- Groups like "Smileys & Emotion" are Unicode-defined but may not match your app’s taxonomy.
- Fix: Map groups to your own categories:
```
$groupMap = [
    'Smileys & Emotion' => 'Positive',
    'Flags' => 'Regional',
];
```

Debugging Tips

Validate Emoji Data: Dump emoji metadata for debugging:

$registry = new EmojiRegistry();
dd($registry->getEmoji('heart')); // Returns array with name, group, etc.

Check for Invalid Sequences: Use EmojiData::isEmoji() to debug malformed input:
```
if
```

Emoji Laravel Package