Skip to content

Commit 8323695

Browse files
javiereguiluzjaviereguiluz
committed
minor #20216 [Emoji][String] Extract Emoji from String documentation (MrYamous)
This PR was squashed before being merged into the 7.1 branch. Discussion ---------- [Emoji][String] Extract Emoji from String documentation Give a try for #20114 I've mainly copy/paste current documentation, with following changes : - change name for internal ref link (remove string part) - remove a versionadded directive for Inverse Emoji Transliteration (Emoji component was added in 7.1, I think it's not necessary to indicate this feature has been add in 7.1 too) - remove Gitlab and Slack example for transliterating services emojis as short code and replace it with a note to mention which services are available - add a sentence about slug emojis as this part stay in String documentation Commits ------- 2e11836 [Emoji][String] Extract Emoji from String documentation
2 parents 398fa47 + 2e11836 commit 8323695

File tree

3 files changed

+145
-174
lines changed

3 files changed

+145
-174
lines changed

‎components/intl.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -386,7 +386,7 @@ Emoji Transliteration
386386
~~~~~~~~~~~~~~~~~~~~~
387387

388388
Symfony provides utilities to translate emojis into their textual representation
389-
in all languages. Read the documentation on :ref:`working with emojis in strings <string-emoji-transliteration>`
389+
in all languages. Read the documentation about :ref:`emoji transliteration <emoji-transliteration>`
390390
to learn more about this feature.
391391

392392
Disk Space

‎emoji.rst‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
Working with Emojis
2+
===================
3+
4+
.. versionadded:: 7.1
5+
6+
The emoji component was introduced in Symfony 7.1.
7+
8+
Symfony provides several utilities to work with emoji characters and sequences
9+
from the `Unicode CLDR dataset`_. They are available via the Emoji component,
10+
which you must first install in your application:
11+
12+
.. _installation:
13+
14+
.. code-block:: terminal
15+
16+
$ composer require symfony/emoji
17+
18+
.. include:: /components/require_autoload.rst.inc
19+
20+
The data needed to store the transliteration of all emojis (~5,000) into all
21+
languages take a considerable disk space.
22+
23+
If you need to save disk space (e.g. because you deploy to some service with tight
24+
size constraints), run this command (e.g. as an automated script after ``composer install``)
25+
to compress the internal Symfony emoji data files using the PHP ``zlib`` extension:
26+
27+
.. code-block:: terminal
28+
29+
# adjust the path to the 'compress' binary based on your application installation
30+
$ php ./vendor/symfony/emoji/Resources/bin/compress
31+
32+
.. _emoji-transliteration:
33+
34+
Emoji Transliteration
35+
~~~~~~~~~~~~~~~~~~~~~
36+
37+
The ``EmojiTransliterator`` class offers a way to translate emojis into their
38+
textual representation in all languages based on the `Unicode CLDR dataset`_::
39+
40+
use Symfony\Component\Emoji\EmojiTransliterator;
41+
42+
// Describe emojis in English
43+
$transliterator = EmojiTransliterator::create('en');
44+
$transliterator->transliterate('Menus with 🍕 or 🍝');
45+
// => 'Menus with pizza or spaghetti'
46+
47+
// Describe emojis in Ukrainian
48+
$transliterator = EmojiTransliterator::create('uk');
49+
$transliterator->transliterate('Menus with 🍕 or 🍝');
50+
// => 'Menus with піца or спагеті'
51+
52+
You can also combine the ``EmojiTransliterator`` with the :ref:`slugger <string-slugger-emoji>`
53+
to transform any emojis into their textual representation.
54+
55+
Transliterating Emoji Text Short Codes
56+
......................................
57+
58+
Services like GitHub and Slack allows to include emojis in your messages using
59+
text short codes (e.g. you can add the ``:+1:`` code to render the 👍 emoji).
60+
61+
Symfony also provides a feature to transliterate emojis into short codes and vice
62+
versa. The short codes are slightly different on each service, so you must pass
63+
the name of the service as an argument when creating the transliterator.
64+
65+
Convert emojis to GitHub short codes with the ``emoji-github`` locale::
66+
67+
$transliterator = EmojiTransliterator::create('emoji-github');
68+
$transliterator->transliterate('Teenage 🐢 really love 🍕');
69+
// => 'Teenage :turtle: really love :pizza:'
70+
71+
Convert GitHub short codes to emojis with the ``github-emoji`` locale::
72+
73+
$transliterator = EmojiTransliterator::create('github-emoji');
74+
$transliterator->transliterate('Teenage :turtle: really love :pizza:');
75+
// => 'Teenage 🐢 really love 🍕'
76+
77+
.. note::
78+
79+
Github, Gitlab and Slack are currently available services in
80+
``EmojiTransliterator``.
81+
82+
.. _text-emoji:
83+
84+
Universal Emoji Short Codes Transliteration
85+
###########################################
86+
87+
If you don't know which service was used to generate the short codes, you can use
88+
the ``text-emoji`` locale, which combines all codes from all services::
89+
90+
$transliterator = EmojiTransliterator::create('text-emoji');
91+
92+
// Github short codes
93+
$transliterator->transliterate('Breakfast with :kiwi-fruit: or :milk-glass:');
94+
// Gitlab short codes
95+
$transliterator->transliterate('Breakfast with :kiwi: or :milk:');
96+
// Slack short codes
97+
$transliterator->transliterate('Breakfast with :kiwifruit: or :glass-of-milk:');
98+
99+
// all the above examples produce the same result:
100+
// => 'Breakfast with 🥝 or 🥛'
101+
102+
You can convert emojis to short codes with the ``emoji-text`` locale::
103+
104+
$transliterator = EmojiTransliterator::create('emoji-text');
105+
$transliterator->transliterate('Breakfast with 🥝 or 🥛');
106+
// => 'Breakfast with :kiwifruit: or :milk-glass:
107+
108+
Inverse Emoji Transliteration
109+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
110+
111+
Given the textual representation of an emoji, you can reverse it back to get the
112+
actual emoji thanks to the :ref:`emojify filter <reference-twig-filter-emojify>`:
113+
114+
.. code-block:: twig
115+
116+
{{ 'I like :kiwi-fruit:'|emojify }} {# renders: I like 🥝 #}
117+
{{ 'I like :kiwi:'|emojify }} {# renders: I like 🥝 #}
118+
{{ 'I like :kiwifruit:'|emojify }} {# renders: I like 🥝 #}
119+
120+
By default, ``emojify`` uses the :ref:`text catalog <text-emoji>`, which
121+
merges the emoji text codes of all services. If you prefer, you can select a
122+
specific catalog to use:
123+
124+
.. code-block:: twig
125+
126+
{{ 'I :green-heart: this'|emojify }} {# renders: I 💚 this #}
127+
{{ ':green_salad: is nice'|emojify('slack') }} {# renders: 🥗 is nice #}
128+
{{ 'My :turtle: has no name yet'|emojify('github') }} {# renders: My 🐢 has no name yet #}
129+
{{ ':kiwi: is a great fruit'|emojify('gitlab') }} {# renders: 🥝 is a great fruit #}
130+
131+
Removing Emojis
132+
~~~~~~~~~~~~~~~
133+
134+
The ``EmojiTransliterator`` can also be used to remove all emojis from a string,
135+
via the special ``strip`` locale::
136+
137+
use Symfony\Component\Emoji\EmojiTransliterator;
138+
139+
$transliterator = EmojiTransliterator::create('strip');
140+
$transliterator->transliterate('🎉Hey!🥳 🎁Happy Birthday!🎁');
141+
// => 'Hey! Happy Birthday!'
142+
143+
.. _`Unicode CLDR dataset`: https://github.com/unicode-org/cldr

‎string.rst‎

Lines changed: 1 addition & 173 deletions
Original file line numberDiff line numberDiff line change
@@ -507,177 +507,6 @@ requested during the program execution. You can also create lazy strings from a
507507
// hash computation only if it's needed
508508
$lazyHash = LazyString::fromStringable(new Hash());
509509

510-
.. _working-with-emojis:
511-
512-
Working with Emojis
513-
-------------------
514-
515-
.. versionadded:: 7.1
516-
517-
The emoji component was introduced in Symfony 7.1.
518-
519-
Symfony provides several utilities to work with emoji characters and sequences
520-
from the `Unicode CLDR dataset`_. They are available via the Emoji component,
521-
which you must first install in your application:
522-
523-
.. code-block:: terminal
524-
525-
$ composer require symfony/emoji
526-
527-
.. include:: /components/require_autoload.rst.inc
528-
529-
The data needed to store the transliteration of all emojis (~5,000) into all
530-
languages take a considerable disk space.
531-
532-
If you need to save disk space (e.g. because you deploy to some service with tight
533-
size constraints), run this command (e.g. as an automated script after ``composer install``)
534-
to compress the internal Symfony emoji data files using the PHP ``zlib`` extension:
535-
536-
.. code-block:: terminal
537-
538-
# adjust the path to the 'compress' binary based on your application installation
539-
$ php ./vendor/symfony/emoji/Resources/bin/compress
540-
541-
.. _string-emoji-transliteration:
542-
543-
Emoji Transliteration
544-
~~~~~~~~~~~~~~~~~~~~~
545-
546-
The ``EmojiTransliterator`` class offers a way to translate emojis into their
547-
textual representation in all languages based on the `Unicode CLDR dataset`_::
548-
549-
use Symfony\Component\Emoji\EmojiTransliterator;
550-
551-
// Describe emojis in English
552-
$transliterator = EmojiTransliterator::create('en');
553-
$transliterator->transliterate('Menus with 🍕 or 🍝');
554-
// => 'Menus with pizza or spaghetti'
555-
556-
// Describe emojis in Ukrainian
557-
$transliterator = EmojiTransliterator::create('uk');
558-
$transliterator->transliterate('Menus with 🍕 or 🍝');
559-
// => 'Menus with піца or спагеті'
560-
561-
Transliterating Emoji Text Short Codes
562-
......................................
563-
564-
Services like GitHub and Slack allows to include emojis in your messages using
565-
text short codes (e.g. you can add the ``:+1:`` code to render the 👍 emoji).
566-
567-
Symfony also provides a feature to transliterate emojis into short codes and vice
568-
versa. The short codes are slightly different on each service, so you must pass
569-
the name of the service as an argument when creating the transliterator:
570-
571-
GitHub Emoji Short Codes Transliteration
572-
########################################
573-
574-
Convert emojis to GitHub short codes with the ``emoji-github`` locale::
575-
576-
$transliterator = EmojiTransliterator::create('emoji-github');
577-
$transliterator->transliterate('Teenage 🐢 really love 🍕');
578-
// => 'Teenage :turtle: really love :pizza:'
579-
580-
Convert GitHub short codes to emojis with the ``github-emoji`` locale::
581-
582-
$transliterator = EmojiTransliterator::create('github-emoji');
583-
$transliterator->transliterate('Teenage :turtle: really love :pizza:');
584-
// => 'Teenage 🐢 really love 🍕'
585-
586-
Gitlab Emoji Short Codes Transliteration
587-
########################################
588-
589-
Convert emojis to Gitlab short codes with the ``emoji-gitlab`` locale::
590-
591-
$transliterator = EmojiTransliterator::create('emoji-gitlab');
592-
$transliterator->transliterate('Breakfast with 🥝 or 🥛');
593-
// => 'Breakfast with :kiwi: or :milk:'
594-
595-
Convert Gitlab short codes to emojis with the ``gitlab-emoji`` locale::
596-
597-
$transliterator = EmojiTransliterator::create('gitlab-emoji');
598-
$transliterator->transliterate('Breakfast with :kiwi: or :milk:');
599-
// => 'Breakfast with 🥝 or 🥛'
600-
601-
Slack Emoji Short Codes Transliteration
602-
#######################################
603-
604-
Convert emojis to Slack short codes with the ``emoji-slack`` locale::
605-
606-
$transliterator = EmojiTransliterator::create('emoji-slack');
607-
$transliterator->transliterate('Menus with 🥗 or 🧆');
608-
// => 'Menus with :green_salad: or :falafel:'
609-
610-
Convert Slack short codes to emojis with the ``slack-emoji`` locale::
611-
612-
$transliterator = EmojiTransliterator::create('slack-emoji');
613-
$transliterator->transliterate('Menus with :green_salad: or :falafel:');
614-
// => 'Menus with 🥗 or 🧆'
615-
616-
.. _string-text-emoji:
617-
618-
Universal Emoji Short Codes Transliteration
619-
###########################################
620-
621-
If you don't know which service was used to generate the short codes, you can use
622-
the ``text-emoji`` locale, which combines all codes from all services::
623-
624-
$transliterator = EmojiTransliterator::create('text-emoji');
625-
626-
// Github short codes
627-
$transliterator->transliterate('Breakfast with :kiwi-fruit: or :milk-glass:');
628-
// Gitlab short codes
629-
$transliterator->transliterate('Breakfast with :kiwi: or :milk:');
630-
// Slack short codes
631-
$transliterator->transliterate('Breakfast with :kiwifruit: or :glass-of-milk:');
632-
633-
// all the above examples produce the same result:
634-
// => 'Breakfast with 🥝 or 🥛'
635-
636-
You can convert emojis to short codes with the ``emoji-text`` locale::
637-
638-
$transliterator = EmojiTransliterator::create('emoji-text');
639-
$transliterator->transliterate('Breakfast with 🥝 or 🥛');
640-
// => 'Breakfast with :kiwifruit: or :milk-glass:
641-
642-
Inverse Emoji Transliteration
643-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
644-
645-
.. versionadded:: 7.1
646-
647-
The inverse emoji transliteration was introduced in Symfony 7.1.
648-
649-
Given the textual representation of an emoji, you can reverse it back to get the
650-
actual emoji thanks to the :ref:`emojify filter <reference-twig-filter-emojify>`:
651-
652-
.. code-block:: twig
653-
654-
{{ 'I like :kiwi-fruit:'|emojify }} {# renders: I like 🥝 #}
655-
{{ 'I like :kiwi:'|emojify }} {# renders: I like 🥝 #}
656-
{{ 'I like :kiwifruit:'|emojify }} {# renders: I like 🥝 #}
657-
658-
By default, ``emojify`` uses the :ref:`text catalog <string-text-emoji>`, which
659-
merges the emoji text codes of all services. If you prefer, you can select a
660-
specific catalog to use:
661-
662-
.. code-block:: twig
663-
664-
{{ 'I :green-heart: this'|emojify }} {# renders: I 💚 this #}
665-
{{ ':green_salad: is nice'|emojify('slack') }} {# renders: 🥗 is nice #}
666-
{{ 'My :turtle: has no name yet'|emojify('github') }} {# renders: My 🐢 has no name yet #}
667-
{{ ':kiwi: is a great fruit'|emojify('gitlab') }} {# renders: 🥝 is a great fruit #}
668-
669-
Removing Emojis
670-
~~~~~~~~~~~~~~~
671-
672-
The ``EmojiTransliterator`` can also be used to remove all emojis from a string,
673-
via the special ``strip`` locale::
674-
675-
use Symfony\Component\Emoji\EmojiTransliterator;
676-
677-
$transliterator = EmojiTransliterator::create('strip');
678-
$transliterator->transliterate('🎉Hey!🥳 🎁Happy Birthday!🎁');
679-
// => 'Hey! Happy Birthday!'
680-
681510
.. _string-slugger:
682511

683512
Slugger
@@ -752,7 +581,7 @@ the injected slugger is the same as the request locale::
752581
Slug Emojis
753582
~~~~~~~~~~~
754583

755-
You can also combine the :ref:`emoji transliterator <string-emoji-transliteration>`
584+
You can also combine the :ref:`emoji transliterator <emoji-transliteration>`
756585
with the slugger to transform any emojis into their textual representation::
757586

758587
use Symfony\Component\String\Slugger\AsciiSlugger;
@@ -822,4 +651,3 @@ possible to determine a unique singular/plural form for the given word.
822651
.. _`Code points`: https://en.wikipedia.org/wiki/Code_point
823652
.. _`Grapheme clusters`: https://en.wikipedia.org/wiki/Grapheme
824653
.. _`Unicode equivalence`: https://en.wikipedia.org/wiki/Unicode_equivalence
825-
.. _`Unicode CLDR dataset`: https://github.com/unicode-org/cldr

0 commit comments

Comments
 (0)