diff --git a/components/intl.rst b/components/intl.rst index 008d9161fd7..ba3cbdcb959 100644 --- a/components/intl.rst +++ b/components/intl.rst @@ -386,7 +386,7 @@ Emoji Transliteration ~~~~~~~~~~~~~~~~~~~~~ Symfony provides utilities to translate emojis into their textual representation -in all languages. Read the documentation on :ref:`working with emojis in strings ` +in all languages. Read the documentation about :ref:`emoji transliteration ` to learn more about this feature. Disk Space diff --git a/emoji.rst b/emoji.rst new file mode 100644 index 00000000000..551497f0c76 --- /dev/null +++ b/emoji.rst @@ -0,0 +1,173 @@ +Working with Emojis +=================== + +.. versionadded:: 7.1 + + The emoji component was introduced in Symfony 7.1. + +Symfony provides several utilities to work with emoji characters and sequences +from the `Unicode CLDR dataset`_. They are available via the Emoji component, +which you must first install in your application: + +.. _installation: + +.. code-block:: terminal + + $ composer require symfony/emoji + +.. include:: /components/require_autoload.rst.inc + +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 + +.. _emoji-transliteration: + +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 спагСті' + +.. tip:: + + When using the :ref:`slugger ` from the String component, + you can combine it with the ``EmojiTransliterator`` to :ref:`slugify emojis `. + +Transliterating Emoji Text Short Codes +-------------------------------------- + +Services like GitHub and Slack allows to include emojis in your messages using +text short codes (e.g. you can add the ``:+1:`` code to render the πŸ‘ emoji). + +Symfony also provides a feature to transliterate emojis into short codes and vice +versa. The short codes are slightly different on each service, so you must pass +the name of the service as an argument when creating the transliterator. + +GitHub Emoji Short Codes Transliteration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Convert emojis to GitHub 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 πŸ•' + +Gitlab Emoji Short Codes Transliteration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Convert emojis to Gitlab short codes with the ``emoji-gitlab`` locale:: + + $transliterator = EmojiTransliterator::create('emoji-gitlab'); + $transliterator->transliterate('Breakfast with πŸ₯ or πŸ₯›'); + // => 'Breakfast with :kiwi: or :milk:' + +Convert Gitlab short codes to emojis with the ``gitlab-emoji`` locale:: + + $transliterator = EmojiTransliterator::create('gitlab-emoji'); + $transliterator->transliterate('Breakfast with :kiwi: or :milk:'); + // => 'Breakfast with πŸ₯ or πŸ₯›' + +Slack Emoji Short Codes Transliteration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Convert emojis to Slack 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 πŸ§†' + +.. _text-emoji: + +Universal Emoji Short Codes Transliteration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you don't know which service was used to generate the short codes, you can use +the ``text-emoji`` locale, which combines all codes from all services:: + + $transliterator = EmojiTransliterator::create('text-emoji'); + + // Github short codes + $transliterator->transliterate('Breakfast with :kiwi-fruit: or :milk-glass:'); + // Gitlab short codes + $transliterator->transliterate('Breakfast with :kiwi: or :milk:'); + // Slack short codes + $transliterator->transliterate('Breakfast with :kiwifruit: or :glass-of-milk:'); + + // all the above examples produce the same result: + // => 'Breakfast with πŸ₯ or πŸ₯›' + +You can convert emojis to short codes with the ``emoji-text`` locale:: + + $transliterator = EmojiTransliterator::create('emoji-text'); + $transliterator->transliterate('Breakfast with πŸ₯ or πŸ₯›'); + // => 'Breakfast with :kiwifruit: or :milk-glass: + +Inverse Emoji Transliteration +----------------------------- + +Given the textual representation of an emoji, you can reverse it back to get the +actual emoji thanks to the :ref:`emojify filter `: + +.. code-block:: twig + + {{ 'I like :kiwi-fruit:'|emojify }} {# renders: I like πŸ₯ #} + {{ 'I like :kiwi:'|emojify }} {# renders: I like πŸ₯ #} + {{ 'I like :kiwifruit:'|emojify }} {# renders: I like πŸ₯ #} + +By default, ``emojify`` uses the :ref:`text catalog `, which +merges the emoji text codes of all services. If you prefer, you can select a +specific catalog to use: + +.. code-block:: twig + + {{ 'I :green-heart: this'|emojify }} {# renders: I πŸ’š this #} + {{ ':green_salad: is nice'|emojify('slack') }} {# renders: πŸ₯— is nice #} + {{ 'My :turtle: has no name yet'|emojify('github') }} {# renders: My 🐒 has no name yet #} + {{ ':kiwi: is a great fruit'|emojify('gitlab') }} {# renders: πŸ₯ is a great fruit #} + +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!' + +.. _`Unicode CLDR dataset`: https://github.com/unicode-org/cldr diff --git a/string.rst b/string.rst index f2856976986..3fb4238ff13 100644 --- a/string.rst +++ b/string.rst @@ -516,176 +516,10 @@ requested during the program execution. You can also create lazy strings from a // hash computation only if it's needed $lazyHash = LazyString::fromStringable(new Hash()); -.. _working-with-emojis: - Working with Emojis ------------------- -.. versionadded:: 7.1 - - The emoji component was introduced in Symfony 7.1. - -Symfony provides several utilities to work with emoji characters and sequences -from the `Unicode CLDR dataset`_. They are available via the Emoji component, -which you must first install in your application: - -.. code-block:: terminal - - $ composer require symfony/emoji - -.. include:: /components/require_autoload.rst.inc - -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 - -.. _string-emoji-transliteration: - -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 спагСті' - -Transliterating Emoji Text Short Codes -...................................... - -Services like GitHub and Slack allows to include emojis in your messages using -text short codes (e.g. you can add the ``:+1:`` code to render the πŸ‘ emoji). - -Symfony also provides a feature to transliterate emojis into short codes and vice -versa. The short codes are slightly different on each service, so you must pass -the name of the service as an argument when creating the transliterator: - -GitHub Emoji Short Codes Transliteration -######################################## - -Convert emojis to GitHub 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 πŸ•' - -Gitlab Emoji Short Codes Transliteration -######################################## - -Convert emojis to Gitlab short codes with the ``emoji-gitlab`` locale:: - - $transliterator = EmojiTransliterator::create('emoji-gitlab'); - $transliterator->transliterate('Breakfast with πŸ₯ or πŸ₯›'); - // => 'Breakfast with :kiwi: or :milk:' - -Convert Gitlab short codes to emojis with the ``gitlab-emoji`` locale:: - - $transliterator = EmojiTransliterator::create('gitlab-emoji'); - $transliterator->transliterate('Breakfast with :kiwi: or :milk:'); - // => 'Breakfast with πŸ₯ or πŸ₯›' - -Slack Emoji Short Codes Transliteration -####################################### - -Convert emojis to Slack 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 πŸ§†' - -.. _string-text-emoji: - -Universal Emoji Short Codes Transliteration -########################################### - -If you don't know which service was used to generate the short codes, you can use -the ``text-emoji`` locale, which combines all codes from all services:: - - $transliterator = EmojiTransliterator::create('text-emoji'); - - // Github short codes - $transliterator->transliterate('Breakfast with :kiwi-fruit: or :milk-glass:'); - // Gitlab short codes - $transliterator->transliterate('Breakfast with :kiwi: or :milk:'); - // Slack short codes - $transliterator->transliterate('Breakfast with :kiwifruit: or :glass-of-milk:'); - - // all the above examples produce the same result: - // => 'Breakfast with πŸ₯ or πŸ₯›' - -You can convert emojis to short codes with the ``emoji-text`` locale:: - - $transliterator = EmojiTransliterator::create('emoji-text'); - $transliterator->transliterate('Breakfast with πŸ₯ or πŸ₯›'); - // => 'Breakfast with :kiwifruit: or :milk-glass: - -Inverse Emoji Transliteration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 7.1 - - The inverse emoji transliteration was introduced in Symfony 7.1. - -Given the textual representation of an emoji, you can reverse it back to get the -actual emoji thanks to the :ref:`emojify filter `: - -.. code-block:: twig - - {{ 'I like :kiwi-fruit:'|emojify }} {# renders: I like πŸ₯ #} - {{ 'I like :kiwi:'|emojify }} {# renders: I like πŸ₯ #} - {{ 'I like :kiwifruit:'|emojify }} {# renders: I like πŸ₯ #} - -By default, ``emojify`` uses the :ref:`text catalog `, which -merges the emoji text codes of all services. If you prefer, you can select a -specific catalog to use: - -.. code-block:: twig - - {{ 'I :green-heart: this'|emojify }} {# renders: I πŸ’š this #} - {{ ':green_salad: is nice'|emojify('slack') }} {# renders: πŸ₯— is nice #} - {{ 'My :turtle: has no name yet'|emojify('github') }} {# renders: My 🐒 has no name yet #} - {{ ':kiwi: is a great fruit'|emojify('gitlab') }} {# renders: πŸ₯ is a great fruit #} - -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!' +These contents have been moved to the :doc:`Emoji component docs `. .. _string-slugger: @@ -761,7 +595,7 @@ the injected slugger is the same as the request locale:: Slug Emojis ~~~~~~~~~~~ -You can also combine the :ref:`emoji transliterator ` +You can also combine the :ref:`emoji transliterator ` with the slugger to transform any emojis into their textual representation:: use Symfony\Component\String\Slugger\AsciiSlugger; @@ -831,4 +665,3 @@ possible to determine a unique singular/plural form for the given word. .. _`Code points`: https://en.wikipedia.org/wiki/Code_point .. _`Grapheme clusters`: https://en.wikipedia.org/wiki/Grapheme .. _`Unicode equivalence`: https://en.wikipedia.org/wiki/Unicode_equivalence -.. _`Unicode CLDR dataset`: https://github.com/unicode-org/cldr