league/emoji

league/emoji is a comprehensive PHP parser and converter of emoticons, HTML entities, shortcodes and unicodes (emojis); utilizing milesj/emojibase as its data source.

📦 Installation & Basic Usage

This project requires PHP 7.2.5 or higher with the mbstring and zlib PHP extensions. To install it via Composer simply run:

$ composer require league/emoji

NOTE: Until this is actually published in the league namespace on packagist.com, you will need to add the following to your composer.json file:

    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/unicorn-fail/emoji.git"
        }
    ],
    "require": {
        "league/emoji": "dev-main"
    }

The League\Emoji\Emoji class provides a simple wrapper for converting emoticons, HTML entities and shortcodes to proper unicode characters (emojis):

use League\Emoji\EmojiConverter;
use League\Emoji\Emojibase\EmojibaseDatasetInterface;
use League\Emoji\Emojibase\EmojibaseShortcodeInterface;

$defaultConfiguration = [
    /** @var array<string, string> (see EmojiConverter::TYPES) */
    'convert' => [
        EmojiConverter::EMOTICON    => EmojiConverter::UNICODE,
        EmojiConverter::HTML_ENTITY => EmojiConverter::UNICODE,
        EmojiConverter::SHORTCODE   => EmojiConverter::UNICODE,
        EmojiConverter::UNICODE     => EmojiConverter::UNICODE,
    ],

    /** @var array<string, mixed> */
    'exclude' => [
        /** @var string[] */
        'shortcodes' => [],
    ],

    /** @var string */
    'locale' => 'en',

    /** @var ?bool */
    'native' => null, // Auto (null), becomes true or false depending on locale set.

    /** @var int */
    'presentation' => EmojibaseDatasetInterface::EMOJI,

    /** @var string[] */
    'preset' => EmojibaseShortcodeInterface::DEFAULT_PRESETS,
];

// Convert all applicable values to unicode emojis (default configuration).
$converter = EmojiConverter::create();
echo $converter->convert('We <3 :unicorn: :D!');
// We ❤️ 🦄 😀!

// Convert all applicable values to HTML entities.
$converter = EmojiConverter::create(['convert' => EmojiConverter::HTML_ENTITY]);
echo  $converter->convert('We <3 :unicorn: :D!');
// We \&#x2764; \&#x1F984; \&#x1F600;!

// Convert all applicable values to shortcodes.
$converter = EmojiConverter::create(['convert' => EmojiConverter::SHORTCODE]);
echo  $converter->convert('We <3 :unicorn: :D!');
// We :heart: :unicorn: :grinning:!

Please note that only UTF-8 and ASCII encodings are supported. If your content uses a different encoding please convert it to UTF-8 before running it through this library.

📓 Documentation

@todo

⏫ Upgrading

@todo

🏷️ Versioning

SemVer is followed closely. Minor and patch releases should not introduce breaking changes to the codebase; however, they might change the resulting AST or HTML output of parsed Markdown (due to bug fixes, spec changes, etc.) As a result, you might get slightly different HTML, but any custom code built onto this library should still function correctly.

Any classes or methods marked @internal are not intended for use outside of this library and are subject to breaking changes at any time, so please avoid using them.

🛠️ Maintenance & Support

@todo

👷‍♀️ Contributing

@todo

🧪 Testing

$ composer test

Or, to include coverage support:

$ composer test-coverage

👥 Credits & Acknowledgements

• Mark Halliwell
• Colin O'Dell
• Ben Sinclair (elvanto/litemoji)
• Miles Johnson (milesj/emojibase)
• All Contributors

This code originally based on elvanto/litemoji, maintained and copyrighted by Ben Sinclair. Currently, this project still uses milesj/emojibase as its datasource, maintained and copyrighted by Miles Johnson. This project simply wouldn't exist without either of their works!

📄 License

league/emoji is licensed under the BSD-3 license. See the LICENSE file for more details.

🏛️ Governance

This project is primarily maintained by Mark Halliwell.