Laravel Emoji Laravel Package

Getting Started

• Check the floor first. 3.0 requires PHP 8.3+ and Laravel 13. Run composer why-not overtrue/laravel-emoji ^3.0 before anything else — on Laravel 11/12 apps this will hard-block, and 2.x is now the maintenance branch for those.
• Install: composer require overtrue/laravel-emoji:^3.0. The service provider is auto-discovered; no manual registration needed.
• Publish the config only if you need to change the client: php artisan vendor:publish --tag=<tag from README>. Use the tag printed in the 3.0 README — the previously documented tag was wrong, so any copy-pasted snippet from a blog post or an old issue is likely to fail silently.
• First use case, in a Blade view:

  {{-- shortcode -> unicode, in prose --}}
  <p>{{ emoji($comment->body) }}</p>
  
  {{-- or as a directive --}}
  @emoji($comment->body)
  

• Where to look first: config/emoji.php (the client entry — should now resolve to JoyPixels), the service provider's container binding for the client class, and the README's corrected class name. If you previously subclassed or rebound the client, verify the FQCN against 3.0.

Implementation Patterns

• Store shortcodes, render unicode. Keep :smile: in the database and convert at render time. It's reversible, diff-friendly, and lets you re-render historical content if the client's emoji set changes.
• Wrap it, don't sprinkle it. Put emoji() behind a small EmojiFormatter service (or a HasEmoji trait / accessor) so views never call the helper directly. This gives you one place to swap clients, one place to add caching, and one place to disable conversion in tests.
• API layer: convert in an API Resource or a ->through() collection callback rather than in the controller, so paginated and single-resource responses stay consistent.
• Blade partial for trusted-content rendering. For comment bodies, threads, and notification emails, funnel everything through one <x-emoji-text :text="$body" /> component. That component is where you decide about escaping and about skipping <code>/<pre> blocks.
• Migration safety net: emoji are 4-byte UTF-8. Confirm the columns and the connection charset are utf8mb4 / utf8mb4_unicode_ci before you start converting output — otherwise the render works but the write path truncates.
• Testing: the client map is local, so assertions are deterministic and offline. Snapshot a handful of representative strings (:smile:, mixed text, unknown shortcode, adjacent emoji) in a unit test against your wrapper — not against the vendor helper — so a future client swap shows up as one failing test rather than a hundred.

Gotchas and Tips

• The 3.0 headline fix is a silent behaviour change. emoji() and @emoji previously resolved the obsolete Emojione client; in 3.0 they resolve JoyPixels. Output for a given shortcode can differ in glyph and in coverage. If you have golden-file tests, HTML snapshots, or cached rendered fragments, re-baseline them once on upgrade.
• Config caching. After editing config/emoji.php, run php artisan config:clear (or re-run config:cache). A stale cached config is the #1 cause of "the fix didn't apply."
• Idempotency. Running the converter over already-converted text is generally a no-op, but don't rely on it — double-processing is a common source of mangled output in nested partials. Convert once, at the boundary.
• False positives in prose. Shortcode syntax uses colons, which collide with timestamps (10:30:), ratios, and ::class in code samples. Scope conversion to user-authored fields; never run it over a whole rendered page or over anything containing code.
• Escaping. Decide deliberately whether output is escaped. {{ }} will entity-encode any HTML the client emits; @emoji / {!! !!} will not. Pick one and document it in the wrapper. Never feed untrusted HTML through an unescaped path just to get emoji.
• Performance is per-call. Conversion scans strings against a large map. On listing pages with dozens of bodies, convert lazily and consider a small in-request memo for repeated strings. If you ever render the same content on every request, cache the converted result keyed on the raw text hash.
• Composer lifecycle scripts were removed. If your CI or local setup had a workaround for the cghooks install failure, delete it — it's dead weight now and may conflict with normal installs.
• Extension point: the client is resolved from the container. If you need a custom set (e.g. a trimmed emoji list for a mobile client), bind your own implementation in a service provider rather than editing the published config, so upgrades don't clobber it.
• Upgrade checklist: bump PHP/Laravel, composer require overtrue/laravel-emoji:^3.0, re-publish or diff the config, confirm the client class in the container is JoyPixels, clear config cache, re-baseline emoji snapshots, and drop any cghooks workaround.