Document how to embed a controller as a service

Grégoire Paris · Grégoire Paris · commit 05e4f3d1dda6 · 2017-06-13T18:49:51.000+02:00
diff --git 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 embed your controller in a template, 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
@@ -98,4 +98,36 @@ string syntax for controllers (i.e. **bundle**:**controller**:**action**):
             ) ?>
         </div>
 
+If your controller should be used as a service, you can reference it like that
+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>`
