Skip to content

Commit 876cbc0

Browse files
smnandrejaviereguiluz
smnandre
authored and
javiereguiluz
committed
[Emoji] Emoji component
1 parent d82fae0 commit 876cbc0

File tree

2 files changed

+131
-48
lines changed

2 files changed

+131
-48
lines changed

‎components/emoji.rst

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
The Emoji Component
2+
===================
3+
4+
The Emoji component provides utilities to work with emoji characters and
5+
sequences from the `Unicode CLDR dataset`_.
6+
7+
Installation
8+
------------
9+
10+
.. code-block:: terminal
11+
12+
$ composer require symfony/emoji
13+
14+
.. include:: /components/require_autoload.rst.inc
15+
16+
17+
Emoji Transliteration
18+
---------------------
19+
20+
The ``EmojiTransliterator`` class offers a way to translate emojis into their
21+
textual representation in all languages based on the `Unicode CLDR dataset`_::
22+
23+
use Symfony\Component\Emoji\EmojiTransliterator;
24+
25+
// Describe emojis in English
26+
$transliterator = EmojiTransliterator::create('en');
27+
$transliterator->transliterate('Menus with 🍕 or 🍝');
28+
// => 'Menus with pizza or spaghetti'
29+
30+
// Describe emojis in Ukrainian
31+
$transliterator = EmojiTransliterator::create('uk');
32+
$transliterator->transliterate('Menus with 🍕 or 🍝');
33+
// => 'Menus with піца or спагеті'
34+
35+
36+
The ``EmojiTransliterator`` also provides special locales that convert emojis to
37+
short codes and vice versa in specific platforms, such as GitHub and Slack.
38+
39+
GitHub
40+
~~~~~~
41+
42+
Convert GitHub emojis to short codes with the ``emoji-github`` locale::
43+
44+
$transliterator = EmojiTransliterator::create('emoji-github');
45+
$transliterator->transliterate('Teenage 🐢 really love 🍕');
46+
// => 'Teenage :turtle: really love :pizza:'
47+
48+
Convert GitHub short codes to emojis with the ``github-emoji`` locale::
49+
50+
$transliterator = EmojiTransliterator::create('github-emoji');
51+
$transliterator->transliterate('Teenage :turtle: really love :pizza:');
52+
// => 'Teenage 🐢 really love 🍕'
53+
54+
Slack
55+
~~~~~
56+
57+
Convert Slack emojis to short codes with the ``emoji-slack`` locale::
58+
59+
$transliterator = EmojiTransliterator::create('emoji-slack');
60+
$transliterator->transliterate('Menus with 🥗 or 🧆');
61+
// => 'Menus with :green_salad: or :falafel:'
62+
63+
Convert Slack short codes to emojis with the ``slack-emoji`` locale::
64+
65+
$transliterator = EmojiTransliterator::create('slack-emoji');
66+
$transliterator->transliterate('Menus with :green_salad: or :falafel:');
67+
// => 'Menus with 🥗 or 🧆'
68+
69+
70+
Emoji Slugger
71+
-------------
72+
73+
Combine the emoji transliterator with the :doc:`/components/string`
74+
to improve the slugs of contents that include emojis (e.g. for URLs).
75+
76+
Call the ``AsciiSlugger::withEmoji()`` method to enable the emoji transliterator in the Slugger::
77+
78+
use Symfony\Component\String\Slugger\AsciiSlugger;
79+
80+
$slugger = new AsciiSlugger();
81+
$slugger = $slugger->withEmoji();
82+
83+
$slug = $slugger->slug('a 😺, 🐈‍⬛, and a 🦁 go to 🏞️', '-', 'en');
84+
// $slug = 'a-grinning-cat-black-cat-and-a-lion-go-to-national-park';
85+
86+
$slug = $slugger->slug('un 😺, 🐈‍⬛, et un 🦁 vont au 🏞️', '-', 'fr');
87+
// $slug = 'un-chat-qui-sourit-chat-noir-et-un-tete-de-lion-vont-au-parc-national';
88+
89+
.. tip::
90+
91+
Integrating the Emoji Component with the String component is straightforward and requires no additional
92+
configuration.string.
93+
94+
Removing Emojis
95+
---------------
96+
97+
The ``EmojiTransliterator`` can also be used to remove all emojis from a string, via the
98+
special ``strip`` locale::
99+
100+
use Symfony\Component\Emoji\EmojiTransliterator;
101+
102+
$transliterator = EmojiTransliterator::create('strip');
103+
$transliterator->transliterate('🎉Hey!🥳 🎁Happy Birthday!🎁');
104+
// => 'Hey! Happy Birthday!'
105+
106+
Disk space
107+
----------
108+
109+
The data needed to store the transliteration of all emojis (~5,000) into all
110+
languages take a considerable disk space.
111+
112+
If you need to save disk space (e.g. because you deploy to some service with tight
113+
size constraints), run this command (e.g. as an automated script after ``composer install``)
114+
to compress the internal Symfony emoji data files using the PHP ``zlib`` extension:
115+
116+
.. code-block:: terminal
117+
118+
# adjust the path to the 'compress' binary based on your application installation
119+
$ php ./vendor/symfony/emoji/Resources/bin/compress
120+
121+
122+
.. _`Unicode CLDR dataset`: https://github.com/unicode-org/cldr

‎components/intl.rst

Lines changed: 9 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,6 @@ This component provides the following ICU data:
2828
* `Locales`_
2929
* `Currencies`_
3030
* `Timezones`_
31-
* `Emoji Transliteration`_
3231

3332
Language and Script Names
3433
~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -386,56 +385,19 @@ to catching the exception, you can also check if a given timezone ID is valid::
386385
Emoji Transliteration
387386
~~~~~~~~~~~~~~~~~~~~~
388387

389-
The ``EmojiTransliterator`` class provides a utility to translate emojis into
390-
their textual representation in all languages based on the `Unicode CLDR dataset`_::
388+
.. note::
391389

392-
use Symfony\Component\Intl\Transliterator\EmojiTransliterator;
390+
The ``EmojiTransliterator`` class provides a utility to translate emojis into
391+
their textual representation in all languages based on the Unicode CLDR dataset.
393392

394-
// describe emojis in English
395-
$transliterator = EmojiTransliterator::create('en');
396-
$transliterator->transliterate('Menus with 🍕 or 🍝');
397-
// => 'Menus with pizza or spaghetti'
393+
Discover all the available Emoji manipulations in the :doc:`component documentation </components/emoji>`.
398394

399-
// describe emojis in Ukrainian
400-
$transliterator = EmojiTransliterator::create('uk');
401-
$transliterator->transliterate('Menus with 🍕 or 🍝');
402-
// => 'Menus with піца or спагеті'
403-
404-
The ``EmojiTransliterator`` class also provides two extra catalogues: ``github``
405-
and ``slack`` that converts any emojis to the corresponding short code in those
406-
platforms::
407-
408-
use Symfony\Component\Intl\Transliterator\EmojiTransliterator;
409-
410-
// describe emojis in Slack short code
411-
$transliterator = EmojiTransliterator::create('slack');
412-
$transliterator->transliterate('Menus with 🥗 or 🧆');
413-
// => 'Menus with :green_salad: or :falafel:'
414-
415-
// describe emojis in Github short code
416-
$transliterator = EmojiTransliterator::create('github');
417-
$transliterator->transliterate('Menus with 🥗 or 🧆');
418-
// => 'Menus with :green_salad: or :falafel:'
419-
420-
Furthermore the ``EmojiTransliterator`` provides a special ``strip`` locale
421-
that removes all the emojis from a string::
422-
423-
use Symfony\Component\Intl\Transliterator\EmojiTransliterator;
424-
425-
$transliterator = EmojiTransliterator::create('strip');
426-
$transliterator->transliterate('🎉Hey!🥳 🎁Happy Birthday!🎁');
427-
// => 'Hey! Happy Birthday!'
428-
429-
.. tip::
430-
431-
Combine this emoji transliterator with the :ref:`Symfony String slugger <string-slugger-emoji>`
432-
to improve the slugs of contents that include emojis (e.g. for URLs).
395+
Disk space
396+
----------
433397

434-
The data needed to store the transliteration of all emojis (~5,000) into all
435-
languages take a considerable disk space. If you need to save disk space (e.g.
436-
because you deploy to some service with tight size constraints), run this command
437-
(e.g. as an automated script after ``composer install``) to compress the internal
438-
Symfony emoji data files using the PHP ``zlib`` extension:
398+
If you need to save disk space (e.g. because you deploy to some service with tight size
399+
constraints), run this command (e.g. as an automated script after ``composer install``) to compress the
400+
internal Symfony Intl data files using the PHP ``zlib`` extension:
439401

440402
.. code-block:: terminal
441403
@@ -464,4 +426,3 @@ Learn more
464426
.. _`daylight saving time (DST)`: https://en.wikipedia.org/wiki/Daylight_saving_time
465427
.. _`ISO 639-1 alpha-2`: https://en.wikipedia.org/wiki/ISO_639-1
466428
.. _`ISO 639-2 alpha-3 (2T)`: https://en.wikipedia.org/wiki/ISO_639-2
467-
.. _`Unicode CLDR dataset`: https://github.com/unicode-org/cldr

0 commit comments

Comments
 (0)