Skip to content

[Emoji][String] Extract Emoji from String documentation #20216

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 19, 2024
Merged

[Emoji][String] Extract Emoji from String documentation #20216

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion components/intl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <string-emoji-transliteration>`
in all languages. Read the documentation about :ref:`emoji transliteration <emoji-transliteration>`
to learn more about this feature.

Disk Space
Expand Down
143 changes: 143 additions & 0 deletions emoji.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,143 @@
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 спагеті'

You can also combine the ``EmojiTransliterator`` with the :ref:`slugger <string-slugger-emoji>`
to transform any emojis into their textual representation.

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.

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 🍕'

.. note::

Github, Gitlab and Slack are currently available services in
``EmojiTransliterator``.

.. _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 <reference-twig-filter-emojify>`:

.. code-block:: twig

{{ 'I like :kiwi-fruit:'|emojify }} {# renders: I like 🥝 #}

Check failure on line 116 in emoji.rst

View workflow job for this annotation

GitHub Actions / Code Blocks 

[Twig] Unknown "emojify" filter.
{{ 'I like :kiwi:'|emojify }} {# renders: I like 🥝 #}
{{ 'I like :kiwifruit:'|emojify }} {# renders: I like 🥝 #}

By default, ``emojify`` uses the :ref:`text catalog <text-emoji>`, 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 #}

Check failure on line 126 in emoji.rst

View workflow job for this annotation

GitHub Actions / Code Blocks 

[Twig] Unknown "emojify" filter.
{{ ':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
174 changes: 1 addition & 173 deletions string.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -507,177 +507,6 @@ 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 <reference-twig-filter-emojify>`:

.. 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 <string-text-emoji>`, 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!'

.. _string-slugger:

Slugger
Expand Down Expand Up @@ -752,7 +581,7 @@ the injected slugger is the same as the request locale::
Slug Emojis
~~~~~~~~~~~

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

use Symfony\Component\String\Slugger\AsciiSlugger;
Expand Down Expand Up @@ -822,4 +651,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
Loading