Contradicting info about bundle resource loading

[mmarton]

Hi!

in https://symfony.com/doc/current/bundles/best_practices.html#resources it sais that

If the bundle references any resources (config files, translation files, etc.), don’t use physical paths (e.g. __DIR__/config/services.xml) but logical paths (e.g. @AcmeBlogBundle/config/services.xml). The logical paths are required because of the bundle overriding mechanism that lets you override any resource/file of any bundle. See Locating Resources for more details about transforming physical paths into logical paths.

And below that in the 'learn more' section there is a link to https://symfony.com/doc/current/bundles/extension.html Which uses the old __DIR__/config at the https://symfony.com/doc/current/bundles/extension.html#using-the-load-method part.

I coudn't find any info about how to use the $kernel->locateResource() inside a bundle's load method and the ordinary Symfony\Component\Config\FileLocator cant handle logical paths.

Help me out please!

[fri0z]

@yceruto Hi tell me about this issue or appoint a responsible person for this question. Thanks.

[carsonbot]

Thank you for this issue. There has not been a lot of activity here for a while. Has this been resolved?

[mmarton]

Nope, it's still not clear how to do it in the right way :/

[carsonbot]

Thank you for this issue. There has not been a lot of activity here for a while. Has this been resolved?

[carsonbot]

Could I get a reply or should I close this?

[mmarton]

keep it open pls

[javiereguiluz]

@stof we talked about this a few days ago and you suggested to get rid of this bundle resource section related to the kernel locator.

I've found some occurrences of this in the docs, so I'm asking you if you think we should reword/update or just delete the following:

(1) How to Override any Part of a Bundle (https://github.com/symfony/symfony-docs/blob/6.3/bundles/override.rst)

This note at the beginning of the article:

.. tip::

    The bundle overriding mechanism means that you cannot use physical paths to
    refer to bundle's resources (e.g. ``__DIR__/config/services.xml``). Always
    use logical paths in your bundles (e.g. ``@FooBundle/config/services.xml``)
    and call the :ref:`locateResource() method <http-kernel-resource-locator>`
    to turn them into physical paths when needed.

(2) Best Practices for Reusable Bundles (https://github.com/symfony/symfony-docs/blob/6.3/bundles/best_practices.rst)

The entire Resources section:

Resources
---------

If the bundle references any resources (config files, translation files, etc.),
don't use physical paths (e.g. ``__DIR__/config/services.xml``) but logical
paths (e.g. ``@AcmeBlogBundle/config/services.xml``).

The logical paths are required because of the bundle overriding mechanism that
lets you override any resource/file of any bundle. See :ref:`http-kernel-resource-locator`
for more details about transforming physical paths into logical paths.

Beware that templates use a simplified version of the logical path shown above.
For example, an ``index.html.twig`` template located in the ``templates/Default/``
directory of the AcmeBlogBundle, is referenced as ``@AcmeBlog/Default/index.html.twig``.

(3) The HttpKernel Component (https://github.com/symfony/symfony-docs/blob/6.3/components/http_kernel.rst)

The Locating Resources section:

Locating Resources
------------------

The HttpKernel component is responsible of the bundle mechanism used in Symfony
applications. The key feature of the bundles is that they allow to override any
resource used by the application (config files, templates, controllers,
translation files, etc.)

This overriding mechanism works because resources are referenced not by their
physical path but by their logical path. For example, the ``services.xml`` file
stored in the ``Resources/config/`` directory of a bundle called FooBundle is
referenced as ``@FooBundle/Resources/config/services.xml``. This logical path
will work when the application overrides that file and even if you change the
directory of FooBundle.

The HttpKernel component provides a method called :method:`Symfony\\Component\\HttpKernel\\Kernel::locateResource`
which can be used to transform logical paths into physical paths::

    $path = $kernel->locateResource('@FooBundle/Resources/config/services.xml');

Thanks!

[stof]

The bundle overriding feature has been removed in Symfony 4.0.

So I suggest removing entirely the cases 1 and 2. The case 3 might be reworded because Kernel::locateResource still provides a benefit: importing the resource without knowing where FooBundle is in the filesystem. This benefit still applies even without an overriding mechanism.