<commit_before>Tags
====

This guide explains how you can use tags to group and find Puli_ resources by
their functionality.

If you don't know what Puli is or why you should use it, read :doc:`at-a-glance`
first.

Tagging with Composer
---------------------

You can tag mapped resources in order to indicate that they support specific
features. For example, assume that all XLIFF translation files in the
"acme/blog" package should be registered with the ``\Acme\Translator`` class.
You can tag resources by adding them to the "tags" key in composer.json:

.. code-block:: json

    {
        "name": "acme/blog",
        "extra": {
            "puli": {
                "resources": {
                    "/acme/blog": "resources"
                },
                "tags": {
                    "/acme/blog/translations/*.xlf": "acme/translator/xlf"
                }
            }
        }
    }

The left side of the array is a path or a glob that selects one or more
resources in the repository. The right side contains one or more tags that
should be added to the selected resources.

Fetching Tagged Resources
-------------------------

The tagged resources can be retrieved with the
:method:`Puli\\Repository\\ResourceRepositoryInterface::findByTag` method of the
resource repository:

.. code-block:: php

    foreach ($repo->findByTag('acme/translator/xlf') as $resource) {
        // ...
    }

Use :method:`Puli\\Repository\\ResourceRepositoryInterface::getTags` to read all
tags that have been registered with the repository:

.. code-block:: php

    $tags = $repo->getTags();<commit_msg>[docs] Wording<commit_after>Tags
====

This guide explains how you can use tags to group and find Puli_ resources by
their functionality.

If you don't know what Puli is or why you should use it, read :doc:`at-a-glance`
first.

Tagging with Composer
---------------------

You can tag mapped resources in order to indicate that they support specific
features. For example, assume that all XLIFF translation files in the
"acme/blog" package should be registered with the ``\Acme\Translator`` class.
You can tag resources by adding them to the "tags" key in composer.json:

.. code-block:: json

    {
        "name": "acme/blog",
        "extra": {
            "puli": {
                "resources": {
                    "/acme/blog": "resources"
                },
                "tags": {
                    "/acme/blog/translations/*.xlf": "acme/translator/xlf"
                }
            }
        }
    }

The left side of the array is a path or a glob that selects one or more
resources in the repository. The right side contains one or more tags that
should be added to the selected resources.

Finding Tagged Resources
------------------------

The tagged resources can be retrieved with the
:method:`Puli\\Repository\\ResourceRepositoryInterface::findByTag` method of the
resource repository:

.. code-block:: php

    foreach ($repo->findByTag('acme/translator/xlf') as $resource) {
        // ...
    }

Use :method:`Puli\\Repository\\ResourceRepositoryInterface::getTags` to read all
tags that have been registered with the repository:

.. code-block:: php

    $tags = $repo->getTags();
{'fraction_non_alphanumeric': 0.12184481146774696, 'fraction_numerical': 0.0, 'mean_word_length': 2.340270551508845, 'pattern_counts': {'":': 14, '<': 3, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2677325', 'n_tokens_mistral': 881, 'n_tokens_neox': 847, 'n_words': 344}