Skip to content

Commit 4cf19f4

Browse files
javiereguiluzjaviereguiluz
committed
Merge branch '7.1' into 7.2
* 7.1: [String] Added a message about the moved Emoji docs [Emoji][String] Extract Emoji from String documentation
2 parents 4e04bb7 + 7815198 commit 4cf19f4

File tree

3 files changed

+176
-170
lines changed

3 files changed

+176
-170
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: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
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+
.. tip::
53+
54+
When using the :ref:`slugger <string-slugger>` from the String component,
55+
you can combine it with the ``EmojiTransliterator`` to :ref:`slugify emojis <string-slugger-emoji>`.
56+
57+
Transliterating Emoji Text Short Codes
58+
--------------------------------------
59+
60+
Services like GitHub and Slack allows to include emojis in your messages using
61+
text short codes (e.g. you can add the ``:+1:`` code to render the 👍 emoji).
62+
63+
Symfony also provides a feature to transliterate emojis into short codes and vice
64+
versa. The short codes are slightly different on each service, so you must pass
65+
the name of the service as an argument when creating the transliterator.
66+
67+
GitHub Emoji Short Codes Transliteration
68+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
69+
70+
Convert emojis to GitHub short codes with the ``emoji-github`` locale::
71+
72+
$transliterator = EmojiTransliterator::create('emoji-github');
73+
$transliterator->transliterate('Teenage 🐢 really love 🍕');
74+
// => 'Teenage :turtle: really love :pizza:'
75+
76+
Convert GitHub short codes to emojis with the ``github-emoji`` locale::
77+
78+
$transliterator = EmojiTransliterator::create('github-emoji');
79+
$transliterator->transliterate('Teenage :turtle: really love :pizza:');
80+
// => 'Teenage 🐢 really love 🍕'
81+
82+
Gitlab Emoji Short Codes Transliteration
83+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
84+
85+
Convert emojis to Gitlab short codes with the ``emoji-gitlab`` locale::
86+
87+
$transliterator = EmojiTransliterator::create('emoji-gitlab');
88+
$transliterator->transliterate('Breakfast with 🥝 or 🥛');
89+
// => 'Breakfast with :kiwi: or :milk:'
90+
91+
Convert Gitlab short codes to emojis with the ``gitlab-emoji`` locale::
92+
93+
$transliterator = EmojiTransliterator::create('gitlab-emoji');
94+
$transliterator->transliterate('Breakfast with :kiwi: or :milk:');
95+
// => 'Breakfast with 🥝 or 🥛'
96+
97+
Slack Emoji Short Codes Transliteration
98+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
99+
100+
Convert emojis to Slack short codes with the ``emoji-slack`` locale::
101+
102+
$transliterator = EmojiTransliterator::create('emoji-slack');
103+
$transliterator->transliterate('Menus with 🥗 or 🧆');
104+
// => 'Menus with :green_salad: or :falafel:'
105+
106+
Convert Slack short codes to emojis with the ``slack-emoji`` locale::
107+
108+
$transliterator = EmojiTransliterator::create('slack-emoji');
109+
$transliterator->transliterate('Menus with :green_salad: or :falafel:');
110+
// => 'Menus with 🥗 or 🧆'
111+
112+
.. _text-emoji:
113+
114+
Universal Emoji Short Codes Transliteration
115+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
116+
117+
If you don't know which service was used to generate the short codes, you can use
118+
the ``text-emoji`` locale, which combines all codes from all services::
119+
120+
$transliterator = EmojiTransliterator::create('text-emoji');
121+
122+
// Github short codes
123+
$transliterator->transliterate('Breakfast with :kiwi-fruit: or :milk-glass:');
124+
// Gitlab short codes
125+
$transliterator->transliterate('Breakfast with :kiwi: or :milk:');
126+
// Slack short codes
127+
$transliterator->transliterate('Breakfast with :kiwifruit: or :glass-of-milk:');
128+
129+
// all the above examples produce the same result:
130+
// => 'Breakfast with 🥝 or 🥛'
131+
132+
You can convert emojis to short codes with the ``emoji-text`` locale::
133+
134+
$transliterator = EmojiTransliterator::create('emoji-text');
135+
$transliterator->transliterate('Breakfast with 🥝 or 🥛');
136+
// => 'Breakfast with :kiwifruit: or :milk-glass:
137+
138+
Inverse Emoji Transliteration
139+
-----------------------------
140+
141+
Given the textual representation of an emoji, you can reverse it back to get the
142+
actual emoji thanks to the :ref:`emojify filter <reference-twig-filter-emojify>`:
143+
144+
.. code-block:: twig
145+
146+
{{ 'I like :kiwi-fruit:'|emojify }} {# renders: I like 🥝 #}
147+
{{ 'I like :kiwi:'|emojify }} {# renders: I like 🥝 #}
148+
{{ 'I like :kiwifruit:'|emojify }} {# renders: I like 🥝 #}
149+
150+
By default, ``emojify`` uses the :ref:`text catalog <text-emoji>`, which
151+
merges the emoji text codes of all services. If you prefer, you can select a
152+
specific catalog to use:
153+
154+
.. code-block:: twig
155+
156+
{{ 'I :green-heart: this'|emojify }} {# renders: I 💚 this #}
157+
{{ ':green_salad: is nice'|emojify('slack') }} {# renders: 🥗 is nice #}
158+
{{ 'My :turtle: has no name yet'|emojify('github') }} {# renders: My 🐢 has no name yet #}
159+
{{ ':kiwi: is a great fruit'|emojify('gitlab') }} {# renders: 🥝 is a great fruit #}
160+
161+
Removing Emojis
162+
---------------
163+
164+
The ``EmojiTransliterator`` can also be used to remove all emojis from a string,
165+
via the special ``strip`` locale::
166+
167+
use Symfony\Component\Emoji\EmojiTransliterator;
168+
169+
$transliterator = EmojiTransliterator::create('strip');
170+
$transliterator->transliterate('🎉Hey!🥳 🎁Happy Birthday!🎁');
171+
// => 'Hey! Happy Birthday!'
172+
173+
.. _`Unicode CLDR dataset`: https://github.com/unicode-org/cldr

‎string.rst

Lines changed: 2 additions & 169 deletions
Original file line numberDiff line numberDiff line change
@@ -516,176 +516,10 @@ requested during the program execution. You can also create lazy strings from a
516516
// hash computation only if it's needed
517517
$lazyHash = LazyString::fromStringable(new Hash());
518518

519-
.. _working-with-emojis:
520-
521519
Working with Emojis
522520
-------------------
523521

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

690524
.. _string-slugger:
691525

@@ -761,7 +595,7 @@ the injected slugger is the same as the request locale::
761595
Slug Emojis
762596
~~~~~~~~~~~
763597

764-
You can also combine the :ref:`emoji transliterator <string-emoji-transliteration>`
598+
You can also combine the :ref:`emoji transliterator <emoji-transliteration>`
765599
with the slugger to transform any emojis into their textual representation::
766600

767601
use Symfony\Component\String\Slugger\AsciiSlugger;
@@ -831,4 +665,3 @@ possible to determine a unique singular/plural form for the given word.
831665
.. _`Code points`: https://en.wikipedia.org/wiki/Code_point
832666
.. _`Grapheme clusters`: https://en.wikipedia.org/wiki/Grapheme
833667
.. _`Unicode equivalence`: https://en.wikipedia.org/wiki/Unicode_equivalence
834-
.. _`Unicode CLDR dataset`: https://github.com/unicode-org/cldr

0 commit comments

Comments
 (0)