[Emoji] Emoji component

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

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 </components/emoji>`.
 
-    // 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 <string-slugger-emoji>`
-    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