feature #24264 [TwigBundle] Improve the overriding of bundle template…

…s (yceruto)

This PR was merged into the 3.4 branch.

Discussion
----------

[TwigBundle] Improve the overriding of bundle templates

| Q             | A
| ------------- | ---
| Branch?       | 3.4
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | #17557
| License       | MIT
| Doc PR        | -

### [Overriding a Template that also extends itself](https://twig.symfony.com/doc/2.x/recipes.html#overriding-a-template-that-also-extends-itself)

Now that bundles inheritance is deprecated and removed (#24160, #24161), I'm wondering if we can solve this old issue defining an exclusive namespace only for root bundles in `3.4` just bundles in `4.0`:
```yaml
twig:
    paths:
        # adding paths behind the scene into TwigExtension
        app/Resources/FooBundle/views: Foo
        vendor/acme/foo-bundle/Resources/views: Foo
        vendor/acme/foo-bundle/Resources/views: !Foo # exclusive
```
Thus, one can decide when use the exclusive namespace to avoid the issue and then [we could to say also](http://symfony.com/doc/current/templating/overriding.html):

> To override the bundle template partially (which contains `block`) creates a new `index.html.twig` template in `app/Resources/AcmeBlogBundle/views/Blog/index.html.twig` and extends from `@!AcmeBlogBundle/Blog/index.html.twig` to customize the bundle template:

```twig
{# app/Resources/FooBundle/views/layout.html.twig #}

{# this does not work: circular reference to itself #}
{% extends '@Foo/layout.html.twig' %}

{# this will work: load bundle layout template #}
{% extends '@!Foo/layout.html.twig' %}

{% block title 'New title' %}
```
I hear other suggestions about the excluse namespace.

We will need to update http://symfony.com/doc/current/templating.html#referencing-templates-in-a-bundle too to add this convention.

WDYT?

Commits
-------

0a658c6 Add exclusive Twig namespace for bundles path

src/Symfony/Bundle/TwigBundle/CHANGELOG.md

@@ -4,6 +4,7 @@ CHANGELOG
 3.4.0
 -----
 
+ * added exclusive Twig namespace only for root bundles
  * deprecated `Symfony\Bundle\TwigBundle\Command\DebugCommand`, use `Symfony\Bridge\Twig\Command\DebugCommand` instead
  * deprecated relying on the `ContainerAwareInterface` implementation for `Symfony\Bundle\TwigBundle\Command\LintCommand`
  * added option to configure default path templates (via `default_path`)

src/Symfony/Bundle/TwigBundle/DependencyInjection/TwigExtension.php

@@ -130,6 +130,13 @@ public function load(array $configs, ContainerBuilder $container)
             foreach ($bundle['paths'] as $path) {
                 $twigFilesystemLoaderDefinition->addMethodCall('addPath', array($path, $namespace));
             }
+
+            // add exclusive namespace for root bundles only
+            // to override a bundle template that also extends itself
+            if (count($bundle['paths']) > 0 && 0 === count($bundle['parents'])) {
+                // the last path must be the bundle views directory
+                $twigFilesystemLoaderDefinition->addMethodCall('addPath', array(end($bundle['paths']), '!'.$namespace));
+            }
         }
 
         if (file_exists($dir = $container->getParameter('kernel.root_dir').'/Resources/views')) {

src/Symfony/Bundle/TwigBundle/Tests/DependencyInjection/TwigExtensionTest.php

@@ -198,6 +198,7 @@ public function testTwigLoaderPaths($format)
             array(__DIR__.'/Fixtures/Resources/TwigBundle/views', 'Twig'),
             array(__DIR__.'/Fixtures/templates/bundles/TwigBundle', 'Twig'),
             array(realpath(__DIR__.'/../..').'/Resources/views', 'Twig'),
+            array(realpath(__DIR__.'/../..').'/Resources/views', '!Twig'),
             array(__DIR__.'/Fixtures/Bundle/ChildChildChildChildTwigBundle/Resources/views', 'ChildTwig'),
             array(__DIR__.'/Fixtures/Bundle/ChildChildChildTwigBundle/Resources/views', 'ChildTwig'),
             array(__DIR__.'/Fixtures/Bundle/ChildChildTwigBundle/Resources/views', 'ChildTwig'),