From 382816247ac1d10c43d6d38892fc18044719cf4c Mon Sep 17 00:00:00 2001
From: Javier Eguiluz <javier.eguiluz@gmail.com>
Date: Fri, 12 Sep 2014 15:39:49 +0200
Subject: [PATCH 1/3] Added a note about the side effects of enabling both PHP
 and Twig

---
 cookbook/templating/PHP.rst | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/cookbook/templating/PHP.rst b/cookbook/templating/PHP.rst
index a07b489fdfc..85dde322939 100644
--- a/cookbook/templating/PHP.rst
+++ b/cookbook/templating/PHP.rst
@@ -77,6 +77,24 @@ shortcut to render the default ``AcmeHelloBundle:Hello:index.html.php`` template
         return array('name' => $name);
     }
 
+.. caution::
+
+    Enabling the ``php`` and ``twig`` template engines simultaneously is
+    allowed but it will produce an important side effect in your application:
+    template namespaces will no longer work::
+
+        public function indexAction()
+        {
+            // ...
+
+            // namespaced templates will no longer work
+            $this->render('@Acme/Default/index.html.twig');
+
+            // traditional template notation will work
+            $this->render('AcmeBundle:Default:index.html.twig');
+        }
+
+
 .. index::
   single: Templating; Layout
   single: Layout

From 5e47417c857bd2d066e81c0a75a38b7b331f3085 Mon Sep 17 00:00:00 2001
From: Javier Eguiluz <javier.eguiluz@gmail.com>
Date: Sat, 13 Sep 2014 13:05:46 +0200
Subject: [PATCH 2/3] Improved the explanation thanks to @stof comments

---
 cookbook/templating/PHP.rst | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/cookbook/templating/PHP.rst b/cookbook/templating/PHP.rst
index 85dde322939..328b823377d 100644
--- a/cookbook/templating/PHP.rst
+++ b/cookbook/templating/PHP.rst
@@ -80,20 +80,28 @@ shortcut to render the default ``AcmeHelloBundle:Hello:index.html.php`` template
 .. caution::
 
     Enabling the ``php`` and ``twig`` template engines simultaneously is
-    allowed but it will produce an important side effect in your application:
-    template namespaces will no longer work::
+    allowed but it will produce an undesirable side effect in your application.
+    Template namespaces will no longer work except inside Twig templates::
 
         public function indexAction()
         {
             // ...
 
-            // namespaced templates will no longer work
+            // namespaced templates will no longer work in controllers
             $this->render('@Acme/Default/index.html.twig');
 
-            // traditional template notation will work
+            // you must use the traditional template notation
             $this->render('AcmeBundle:Default:index.html.twig');
         }
 
+    .. code-block:: jinja
+
+        {# inside a Twig template, namespaced templates work as expected #}
+        {{ include('@Acme/Default/index.html.twig') }}
+
+        {# traditional template notation will also work #}
+        {{ include('AcmeBundle:Default:index.html.twig') }}
+
 
 .. index::
   single: Templating; Layout

From fbbabb186143cdeb6dca50dcf1f99c978eb3e32b Mon Sep 17 00:00:00 2001
From: Javier Eguiluz <javier.eguiluz@gmail.com>
Date: Sat, 13 Sep 2014 18:21:53 +0200
Subject: [PATCH 3/3] Reworded the explanation about the limitation of enablin
 PHP templates

---
 cookbook/templating/PHP.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/cookbook/templating/PHP.rst b/cookbook/templating/PHP.rst
index 328b823377d..ea763823261 100644
--- a/cookbook/templating/PHP.rst
+++ b/cookbook/templating/PHP.rst
@@ -80,8 +80,9 @@ shortcut to render the default ``AcmeHelloBundle:Hello:index.html.php`` template
 .. caution::
 
     Enabling the ``php`` and ``twig`` template engines simultaneously is
-    allowed but it will produce an undesirable side effect in your application.
-    Template namespaces will no longer work except inside Twig templates::
+    allowed, but it will produce an undesirable side effect in your application:
+    the ``@`` notation for Twig namespaces will no longer be supported for the
+    ``render()`` method::
 
         public function indexAction()
         {