Merge branch '5.4' into 6.3

* 5.4:
  Reword the contents about bundles' logical paths

Author: javiereguiluz

bundles/best_practices.rst

@@ -531,16 +531,12 @@ 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``).
+you can use physical paths (e.g. ``__DIR__/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``.
+In the past, we recommended to only use logical paths (e.g.
+``@AcmeBlogBundle/config/services.xml``) and resolve them with the
+:ref:`resource locator <http-kernel-resource-locator>` provided by the Symfony
+kernel, but this is no longer a recommended practice.
 
 Learn more
 ----------

bundles/override.rst

@@ -5,14 +5,6 @@ When using a third-party bundle, you might want to customize or override some of
 its features. This document describes ways of overriding the most common
 features of a bundle.
 
-.. 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.
-
 .. _override-templates:
 
 Templates

components/http_kernel.rst

@@ -727,19 +727,17 @@ 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::
+applications. One of the key features of the bundles is that you can use logic
+paths instead of physical paths to refer to any of their resources (config files,
+templates, controllers, translation files, etc.)
+
+This allows to import resources even if you don't know where in the filesystem a
+bundle will be installed. For example, the ``services.xml`` file stored in the
+``Resources/config/`` directory of a bundle called FooBundle can be referenced as
+``@FooBundle/Resources/config/services.xml`` instead of ``__DIR__/Resources/config/services.xml``.
+
+This is possible thanks to the :method:`Symfony\\Component\\HttpKernel\\Kernel::locateResource`
+method provided by the kernel, which transforms logical paths into physical paths::
 
     $path = $kernel->locateResource('@FooBundle/Resources/config/services.xml');