<commit_before>Puli at a Glance
================

Puli_ (pronounced "poo-lee") is a PHP library based on Composer_ that manages
the resources of your project and its dependencies. *Resources* can be anything,
but usually we use the term for machine-processed files that are *not* PHP, such
as CSS, JavaScript, XLIFF, YAML, XML or HTML files.

Puli is efficient, platform-agnostic and independent of any single framework.

Resource Loading
----------------

Just like Composer builds a PSR-4_ autoloader that knows how to load your
classes, Puli builds a *resource repository* from the files in your packages.
You can load these files using normalized paths. These *Puli paths* start with
the name of the package:

.. code-block:: php

    echo $twig->render('/acme/blog/views/footer.html.twig');

Every package developer is responsible for mapping their resources with the
"map" command of `Puli's Command Line Interface`_ (CLI):

.. code-block:: text

    # Map the prefix "/acme/blog" to the "res" directory
    $ puli map /acme/blog res

The configuration is stored in a ``puli.json`` file that is distributed with the
package - just like ``composer.json``. Puli reads the ``puli.json`` files of all
installed packages and makes their resources available to your project.

Read :doc:`mapping-resources` if you want to learn more.

Web Resources
-------------

Some resources - such as templates or configuration files - are needed by the
web server only. Others - like CSS files and images - need to be placed in
a public directory, where browsers can download them.

`Puli's Web Resource Plugin`_ provides a generic solution for this problem.
With that plugin, you can map resources to paths in so-called *install targets*
(local directories, web servers, CDNs, ...):

.. code-block:: text

    # Create target "local" pointing to the "public_html" directory
    $ puli target add local public_html

    # Map resources to the "public_html/blog" directory
    $ puli web add /acme/blog/public /blog

Puli's "web install" command takes care of copying the resources to their
targets:

.. code-block:: text

    $ puli web install
    Installing /acme/blog/public into public_html/blog via symlink...

With Puli's URL generator, you can finally generate the URLs for the published
resources. The following example uses `Puli's Twig Extension`_:

.. code-block:: jinja

    <img src="{{ resource_url('/acme/blog/images/header.png') }}" />

Read :doc:`web-resources` if you want to learn more.

Resource Overriding
-------------------

When working with third-party packages, it is often necessary to customize
files provided by these packages. With Puli this becomes a no-brainer: You
simply copy the files to your project and override the path mappings:

.. code-block:: text

    $ puli map /acme/blog/views/footer.html res/views/footer.html


The file ``res/views/footer.html`` stored in your project will now be used
whenever the resource ``/acme/blog/views/footer.html`` is requested.

Stream Wrappers
---------------

Did you know PHP's `stream wrapper`_ feature? With Puli's stream wrapper, you
can use Puli resources like ordinary files:

.. code-block:: php

    use Puli\Repository\StreamWrapper\ResourceStreamWrapper;

    ResourceStreamWrapper::register('puli', $repo);

In this example, the resource repository is registered for the "puli://" scheme
through Puli's :class:`Puli\\Repository\\StreamWrapper\\ResourceStreamWrapper`.
Now you can access Puli resources like normal files, as long as you prefix them
with "puli://":

.. code-block:: php

    // vendor/acme/blog/res/trans/en.yml
    echo file_get_contents('puli:///acme/blog/trans/en.yml');

Resource Discovery
------------------<commit_msg>Shortened stream wrapper description in "Puli at a Glance"<commit_after>Puli at a Glance
================

Puli_ (pronounced "poo-lee") is a PHP library based on Composer_ that manages
the resources of your project and its dependencies. *Resources* can be anything,
but usually we use the term for machine-processed files that are *not* PHP, such
as CSS, JavaScript, XLIFF, YAML, XML or HTML files.

Puli is efficient, platform-agnostic and independent of any single framework.

Resource Loading
----------------

Just like Composer builds a PSR-4_ autoloader that knows how to load your
classes, Puli builds a *resource repository* from the files in your packages.
You can load these files using normalized paths. These *Puli paths* start with
the name of the package:

.. code-block:: php

    echo $twig->render('/acme/blog/views/footer.html.twig');

Every package developer is responsible for mapping their resources with the
"map" command of `Puli's Command Line Interface`_ (CLI):

.. code-block:: text

    # Map the prefix "/acme/blog" to the "res" directory
    $ puli map /acme/blog res

The configuration is stored in a ``puli.json`` file that is distributed with the
package - just like ``composer.json``. Puli reads the ``puli.json`` files of all
installed packages and makes their resources available to your project.

Read :doc:`mapping-resources` if you want to learn more.

Resource Overriding
-------------------

When working with third-party packages, it is often necessary to customize
files provided by these packages. With Puli this becomes a no-brainer: You
simply copy the files to your project and override the path mappings:

.. code-block:: text

    $ puli map /acme/blog/views/footer.html res/views/footer.html


The file ``res/views/footer.html`` stored in your project will now be used
whenever the resource ``/acme/blog/views/footer.html`` is requested.

Read :doc:`mapping-resources` if you want to learn more.

Web Resources
-------------

Some resources - such as templates or configuration files - are needed by the
web server only. Others - like CSS files and images - need to be placed in
a public directory, where browsers can download them.

`Puli's Web Resource Plugin`_ provides a generic solution for this problem.
With that plugin, you can map resources to paths in so-called *install targets*
(local directories, web servers, CDNs, ...):

.. code-block:: text

    # Create target "local" pointing to the "public_html" directory
    $ puli target add local public_html

    # Map resources to the "public_html/blog" directory
    $ puli web add /acme/blog/public /blog

Puli's "web install" command takes care of copying the resources to their
targets:

.. code-block:: text

    $ puli web install
    Installing /acme/blog/public into public_html/blog via symlink...

With Puli's URL generator, you can finally generate the URLs for the published
resources. The following example uses `Puli's Twig Extension`_:

.. code-block:: jinja

    <img src="{{ resource_url('/acme/blog/images/header.png') }}" />

Read :doc:`web-resources` if you want to learn more.

Stream Wrappers
---------------

Did you know PHP's `stream wrapper`_ feature? With Puli's stream wrapper, you
can use Puli resources like ordinary files:

.. code-block:: php

    // vendor/acme/blog/res/trans/en.yml
    echo file_get_contents('puli:///acme/blog/trans/en.yml');

Read :doc:`stream-wrapper` if you want to learn more.

Resource Discovery
------------------
{'fraction_non_alphanumeric': 0.10910354412786658, 'fraction_numerical': 0.0002779708130646282, 'mean_word_length': 3.5863607393244106, 'pattern_counts': {'":': 1, '<': 5, '<?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': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6046948', 'n_tokens_mistral': 2021, 'n_tokens_neox': 1948, 'n_words': 906}