From 071b1198e10ce3113859c3538225ec0f1c0ed020 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gr=C3=A9goire=20Paris?= <gparis@universcine.com>
Date: Tue, 13 Jun 2017 18:49:51 +0200
Subject: [PATCH] Document how to embed a controller as a service

---
 controller/service.rst               | 32 ++++++++++++++++++++++++++++
 templating/embedding_controllers.rst | 32 ++++++++++++++++++++++++++++
 2 files changed, 64 insertions(+)

diff --git a/controller/service.rst b/controller/service.rst
index 6ee5faeaf0b..2ceb4594024 100644
--- a/controller/service.rst
+++ b/controller/service.rst
@@ -71,6 +71,38 @@ syntax:
     You cannot drop the ``Action`` part of the method name when using the
     single colon notation.
 
+Embedding your controller in a template
+---------------------------------------
+
+If you want to :doc:`embed your controller in a template </templating/embedding_controllers>`,
+you need to use the following syntax:
+
+.. configuration-block::
+
+    .. code-block:: html+twig
+
+        {# app/Resources/views/base.html.twig #}
+
+        {# ... #}
+        <div id="sidebar">
+            {{ render(controller(
+                'AppBundle\\Controller\\HelloController:indexAction',
+            )) }}
+        </div>
+
+    .. code-block:: html+php
+
+        <!-- app/Resources/views/base.html.php -->
+
+        <!-- ... -->
+        <div id="sidebar">
+            <?php echo $view['actions']->render(
+                new \Symfony\Component\HttpKernel\Controller\ControllerReference(
+                    'AppBundle\\Controller\\HelloController:indexAction'
+                )
+            ) ?>
+        </div>
+
 .. _controller-service-invoke:
 
 Invokable Controllers
diff --git a/templating/embedding_controllers.rst b/templating/embedding_controllers.rst
index 228ae4053ee..6fcb1bcf32a 100644
--- a/templating/embedding_controllers.rst
+++ b/templating/embedding_controllers.rst
@@ -98,4 +98,36 @@ string syntax for controllers (i.e. **bundle**:**controller**:**action**):
             ) ?>
         </div>
 
+If your controller should be used :doc:`as a service </controller/service>`,
+you can reference it like this instead:
+
+.. configuration-block::
+
+    .. code-block:: html+twig
+
+        {# app/Resources/views/base.html.twig #}
+
+        {# ... #}
+        <div id="sidebar">
+            {{ render(controller(
+                'AppBundle\\Controller\\ArticleController:recentArticlesAction',
+                { 'max': 3 }
+            )) }}
+        </div>
+
+    .. code-block:: html+php
+
+        <!-- app/Resources/views/base.html.php -->
+
+        <!-- ... -->
+        <div id="sidebar">
+            <?php echo $view['actions']->render(
+                new \Symfony\Component\HttpKernel\Controller\ControllerReference(
+                    'AppBundle\\Controller\\ArticleController:recentArticlesAction',
+                    array('max' => 3)
+                )
+            ) ?>
+        </div>
+
+
 The result of an embedded controler can also be :doc:`cached </http_cache/esi>`