LitEmoji

LitEmoji (elvanto/litemoji) is a small PHP library that simplifies converting emoji between three representations: unicode characters, HTML entities, and colon-style shortcodes like :fire:. With one call you can normalize user input into shortcodes for storage, render shortcodes back to unicode or HTML for display, or strip emoji from a string entirely.

It detects the encoding of the provided text automatically, falls back to UTF-8 when detection is impossible, and supports configuration for excluding specific shortcodes and defining custom aliases. Backed by well-maintained emoji datasets (including Emojibase), it keeps its shortcode mappings current across Unicode releases.

What You Get

• encodeShortcode, encodeHtml, and encodeUnicode conversion functions
• removeEmoji to strip all emoji from a string
• Automatic encoding detection with a UTF-8 fallback
• Configurable excludeShortcodes to skip specific mappings
• aliasShortcodes support for defining custom shortcode names

Common Use Cases

• Normalizing emoji in user input to shortcodes before storing in a database
• Rendering stored shortcodes back to unicode or HTML for display
• Stripping emoji from text for search indexing or plain-text output
• Supporting custom or branded shortcode aliases in a messaging product

Under The Hood

Architecture - The library centers on a single static LitEmoji class under the LitEmoji namespace, backed by generated data arrays (cldr.php, emojibase.php, github.php, iamcal.php, joypixels.php) that map between unicode codepoints and shortcodes across popular shortcode dialects. Conversion methods run regex and mbstring transformations over the input using these lookup tables, with config state (excluded shortcodes, aliases) applied during resolution.

Tech Stack - Requires PHP 7.4+ and the ext-mbstring extension, with no other runtime dependencies. Emoji data is generated at build time from milesj/emojibase via bin/generate-shortcodes-array.php. Tests run on PHPUnit 9.

Code Quality - The code is compact and stable, with a LitEmojiTest suite plus fixture corpora (ShortcodeIpsum, UnicodeIpsum) that exercise round-trip conversions on realistic text. Because the heavy data is generated rather than hand-maintained, the logic surface stays small and easy to verify.

API Design - The API is deliberately minimal and static: encodeShortcode, encodeHtml, encodeUnicode, and removeEmoji cover the common paths, and config() toggles behavior globally. This gives a near-zero learning curve for the common case, at the cost of global static configuration state.