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

dev-latest / 1.0.x-dev 2020-09-18 23:03 UTC

This package is auto-updated.

Last update: 2020-09-21 01:23:02 UTC


README

Latest Version Total Downloads Packagist PHP Version Support Software License
Build Status Scrutinizer coverage (GitHub/BitBucket) Scrutinizer code quality (GitHub/Bitbucket) CII Best Practices Summary Psalm coverage

unicorn-fail/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 unicorn-fail/emoji

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

use UnicornFail\Emoji\Converter;
use UnicornFail\Emoji\Emojibase\DatasetInterface;
use UnicornFail\Emoji\Emojibase\ShortcodeInterface;

// Default configuration.
$configuration = [
    'convertEmoticons'  => true,
    'exclude'           => [
        'shortcodes' => [],
    ],
    'locale'            => 'en',
    'native'            => null, // auto, true or false depending on locale set.
    'presentation'      => DatasetInterface::EMOJI,
    'preset'            => ShortcodeInterface::DEFAULT_PRESETS,
];

$converter = new Converter($configuration);

// Convert applicable values to unicodes (emojis).
echo $converter->convert('We <3 :unicorn: :D!');
// or
echo $converter->convertToUnicode('We <3 :unicorn: :D!');
// We ❤️ 🦄 😀!

// Convert applicable values to HTML entities.
echo  $converter->convertToHtml('We <3 :unicorn: :D!');
// We \&#x2764; \&#x1F984; \&#x1F600;!

// Convert applicable values to shortcodes.
echo  $converter->convertToShortcode('We <3 :unicorn: :D!');
// We :red-heart: :unicorn-face: :grinning-face:!

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

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

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

🏛️ Governance

This project is primarily maintained by Mark Carver.