unicorn-fail/emoji

Comprehensive PHP parser of emoticons, HTML entities, shortcodes and unicodes (emojis).

dev-main / 1.0.x-dev 2021-03-18 20:14 UTC

Requires

• php: ^7.2.5 || ^8.0
• ext-json: *
• ext-mbstring: *
• ext-zlib: *
• doctrine/lexer: ^1.2
• league/configuration: dev-main
• psr/event-dispatcher: ^1.0
• symfony/polyfill-php80: ^1.22.1
• vimeo/psalm: ^4.6.4

Requires (Dev)

• friendsofphp/php-cs-fixer: ^2.18.3
• phpstan/phpstan: ^0.12.81
• phpunit/phpunit: ^8.5.15
• sempro/phpunit-pretty-print: ^1.4.0
• squizlabs/php_codesniffer: ^3.5.8
• unleashedtech/php-coding-standard: ^2.7.0

BSD-3-Clause

• Mark Halliwell
• Colin O'Dell

• php
• json
• data
• markdown
• github
• loader
• helper
• emoji
• unicode
• regex
• dataset
• shortcode
• cldr
• slack
• gfm
• discord
• php-emoji
• JoyPixels
• emojibase
• iamcal

README

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.