diff --git a/components/emoji.rst b/components/emoji.rst new file mode 100644 index 00000000000..b3f725a2585 --- /dev/null +++ b/components/emoji.rst @@ -0,0 +1,122 @@ +The Emoji Component +=================== + + The Emoji component provides utilities to work with emoji characters and + sequences from the `Unicode CLDR dataset`_. + +Installation +------------ + +.. code-block:: terminal + + $ composer require symfony/emoji + +.. include:: /components/require_autoload.rst.inc + + +Emoji Transliteration +--------------------- + +The ``EmojiTransliterator`` class offers a way to translate emojis into their +textual representation in all languages based on the `Unicode CLDR dataset`_:: + + use Symfony\Component\Emoji\EmojiTransliterator; + + // Describe emojis in English + $transliterator = EmojiTransliterator::create('en'); + $transliterator->transliterate('Menus with πŸ• or 🍝'); + // => 'Menus with pizza or spaghetti' + + // Describe emojis in Ukrainian + $transliterator = EmojiTransliterator::create('uk'); + $transliterator->transliterate('Menus with πŸ• or 🍝'); + // => 'Menus with ΠΏΡ–Ρ†Π° or спагСті' + + +The ``EmojiTransliterator`` also provides special locales that convert emojis to +short codes and vice versa in specific platforms, such as GitHub and Slack. + +GitHub +~~~~~~ + +Convert GitHub emojis to short codes with the ``emoji-github`` locale:: + + $transliterator = EmojiTransliterator::create('emoji-github'); + $transliterator->transliterate('Teenage 🐒 really love πŸ•'); + // => 'Teenage :turtle: really love :pizza:' + +Convert GitHub short codes to emojis with the ``github-emoji`` locale:: + + $transliterator = EmojiTransliterator::create('github-emoji'); + $transliterator->transliterate('Teenage :turtle: really love :pizza:'); + // => 'Teenage 🐒 really love πŸ•' + +Slack +~~~~~ + +Convert Slack emojis to short codes with the ``emoji-slack`` locale:: + + $transliterator = EmojiTransliterator::create('emoji-slack'); + $transliterator->transliterate('Menus with πŸ₯— or πŸ§†'); + // => 'Menus with :green_salad: or :falafel:' + +Convert Slack short codes to emojis with the ``slack-emoji`` locale:: + + $transliterator = EmojiTransliterator::create('slack-emoji'); + $transliterator->transliterate('Menus with :green_salad: or :falafel:'); + // => 'Menus with πŸ₯— or πŸ§†' + + +Emoji Slugger +------------- + +Combine the emoji transliterator with the :doc:`/components/string` +to improve the slugs of contents that include emojis (e.g. for URLs). + +Call the ``AsciiSlugger::withEmoji()`` method to enable the emoji transliterator in the Slugger:: + + use Symfony\Component\String\Slugger\AsciiSlugger; + + $slugger = new AsciiSlugger(); + $slugger = $slugger->withEmoji(); + + $slug = $slugger->slug('a 😺, πŸˆβ€β¬›, and a 🦁 go to 🏞️', '-', 'en'); + // $slug = 'a-grinning-cat-black-cat-and-a-lion-go-to-national-park'; + + $slug = $slugger->slug('un 😺, πŸˆβ€β¬›, et un 🦁 vont au 🏞️', '-', 'fr'); + // $slug = 'un-chat-qui-sourit-chat-noir-et-un-tete-de-lion-vont-au-parc-national'; + +.. tip:: + + Integrating the Emoji Component with the String component is straightforward and requires no additional + configuration.string. + +Removing Emojis +--------------- + +The ``EmojiTransliterator`` can also be used to remove all emojis from a string, via the +special ``strip`` locale:: + + use Symfony\Component\Emoji\EmojiTransliterator; + + $transliterator = EmojiTransliterator::create('strip'); + $transliterator->transliterate('πŸŽ‰Hey!πŸ₯³ 🎁Happy Birthday!🎁'); + // => 'Hey! Happy Birthday!' + +Disk space +---------- + +The data needed to store the transliteration of all emojis (~5,000) into all +languages take a considerable disk space. + +If you need to save disk space (e.g. because you deploy to some service with tight +size constraints), run this command (e.g. as an automated script after ``composer install``) +to compress the internal Symfony emoji data files using the PHP ``zlib`` extension: + +.. code-block:: terminal + + # adjust the path to the 'compress' binary based on your application installation + $ php ./vendor/symfony/emoji/Resources/bin/compress + + +.. _`Unicode CLDR dataset`: https://github.com/unicode-org/cldr diff --git a/components/intl.rst b/components/intl.rst index bbd088c830e..768ea30903c 100644 --- a/components/intl.rst +++ b/components/intl.rst @@ -28,7 +28,6 @@ This component provides the following ICU data: * `Locales`_ * `Currencies`_ * `Timezones`_ -* `Emoji Transliteration`_ Language and Script Names ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -386,56 +385,19 @@ to catching the exception, you can also check if a given timezone ID is valid:: Emoji Transliteration ~~~~~~~~~~~~~~~~~~~~~ -The ``EmojiTransliterator`` class provides a utility to translate emojis into -their textual representation in all languages based on the `Unicode CLDR dataset`_:: +.. note:: - use Symfony\Component\Intl\Transliterator\EmojiTransliterator; + The ``EmojiTransliterator`` class provides a utility to translate emojis into + their textual representation in all languages based on the Unicode CLDR dataset. - // describe emojis in English - $transliterator = EmojiTransliterator::create('en'); - $transliterator->transliterate('Menus with πŸ• or 🍝'); - // => 'Menus with pizza or spaghetti' +Discover all the available Emoji manipulations in the :doc:`component documentation `. - // describe emojis in Ukrainian - $transliterator = EmojiTransliterator::create('uk'); - $transliterator->transliterate('Menus with πŸ• or 🍝'); - // => 'Menus with ΠΏΡ–Ρ†Π° or спагСті' - -The ``EmojiTransliterator`` class also provides two extra catalogues: ``github`` -and ``slack`` that converts any emojis to the corresponding short code in those -platforms:: - - use Symfony\Component\Intl\Transliterator\EmojiTransliterator; - - // describe emojis in Slack short code - $transliterator = EmojiTransliterator::create('slack'); - $transliterator->transliterate('Menus with πŸ₯— or πŸ§†'); - // => 'Menus with :green_salad: or :falafel:' - - // describe emojis in Github short code - $transliterator = EmojiTransliterator::create('github'); - $transliterator->transliterate('Menus with πŸ₯— or πŸ§†'); - // => 'Menus with :green_salad: or :falafel:' - -Furthermore the ``EmojiTransliterator`` provides a special ``strip`` locale -that removes all the emojis from a string:: - - use Symfony\Component\Intl\Transliterator\EmojiTransliterator; - - $transliterator = EmojiTransliterator::create('strip'); - $transliterator->transliterate('πŸŽ‰Hey!πŸ₯³ 🎁Happy Birthday!🎁'); - // => 'Hey! Happy Birthday!' - -.. tip:: - - Combine this emoji transliterator with the :ref:`Symfony String slugger ` - to improve the slugs of contents that include emojis (e.g. for URLs). +Disk space +---------- -The data needed to store the transliteration of all emojis (~5,000) into all -languages take a considerable disk space. If you need to save disk space (e.g. -because you deploy to some service with tight size constraints), run this command -(e.g. as an automated script after ``composer install``) to compress the internal -Symfony emoji data files using the PHP ``zlib`` extension: +If you need to save disk space (e.g. because you deploy to some service with tight size +constraints), run this command (e.g. as an automated script after ``composer install``) to compress the +internal Symfony Intl data files using the PHP ``zlib`` extension: .. code-block:: terminal @@ -464,4 +426,3 @@ Learn more .. _`daylight saving time (DST)`: https://en.wikipedia.org/wiki/Daylight_saving_time .. _`ISO 639-1 alpha-2`: https://en.wikipedia.org/wiki/ISO_639-1 .. _`ISO 639-2 alpha-3 (2T)`: https://en.wikipedia.org/wiki/ISO_639-2 -.. _`Unicode CLDR dataset`: https://github.com/unicode-org/cldr