Merge branch '2.8' into 3.4

* 2.8:
  Updated HttpKernel component diagrams
  Change value for opcache.memory_consumption
  Improved a routing example to show annotations
  Clearer wording of allow_delete template behavior

Author: javiereguiluz

_images/components/http_kernel/01-workflow.png

@@ -27,9 +27,14 @@ The Workflow of a Request
 Every HTTP web interaction begins with a request and ends with a response.
 Your job as a developer is to create PHP code that reads the request information
 (e.g. the URL) and creates and returns a response (e.g. an HTML page or JSON string).
+This is a simplified overview of the request workflow in Symfony applications:
 
-.. image:: /_images/components/http_kernel/request-response-flow.png
-   :align: center
+#. The **user** asks for a **resource** in a **browser**;
+#. The **browser** sends a **request** to the **server**;
+#. **Symfony** gives the **application** a **Request** object;
+#. The **application** generates a **Response** object using the data of the **Request** object;
+#. The **server** sends back the **response** to the **browser**;
+#. The **browser** displays the **resource** to the **user**.
 
 Typically, some sort of framework or system is built to handle all the repetitive
 tasks (e.g. routing, security, etc) so that a developer can easily build
@@ -62,8 +67,9 @@ the concrete implementation of :method:`HttpKernelInterface::handle() <Symfony\\
 defines a workflow that starts with a :class:`Symfony\\Component\\HttpFoundation\\Request`
 and ends with a :class:`Symfony\\Component\\HttpFoundation\\Response`.
 
-.. image:: /_images/components/http_kernel/01-workflow.png
-   :align: center
+.. raw:: html
+
+    <object data="../_images/components/http_kernel/http-workflow.svg" type="image/svg+xml"></object>
 
 The exact details of this workflow are the key to understanding how the kernel
 (and the Symfony Framework or any other library that uses the kernel) works.
@@ -149,9 +155,6 @@ layer that denies access).
 The first event that is dispatched inside :method:`HttpKernel::handle <Symfony\\Component\\HttpKernel\\HttpKernel::handle>`
 is ``kernel.request``, which may have a variety of different listeners.
 
-.. image:: /_images/components/http_kernel/02-kernel-request.png
-   :align: center
-
 Listeners of this event can be quite varied. Some listeners - such as a security
 listener - might have enough information to create a ``Response`` object immediately.
 For example, if a security listener determined that a user doesn't have access,
@@ -161,9 +164,6 @@ to the login page or a 403 Access Denied response.
 If a ``Response`` is returned at this stage, the process skips directly to
 the :ref:`kernel.response <component-http-kernel-kernel-response>` event.
 
-.. image:: /_images/components/http_kernel/03-kernel-request-response.png
-   :align: center
-
 Other listeners simply initialize things or add more information to the request.
 For example, a listener might determine and set the locale on the ``Request``
 object.
@@ -216,9 +216,6 @@ to your application. This is the job of the "controller resolver" - a class
 that implements :class:`Symfony\\Component\\HttpKernel\\Controller\\ControllerResolverInterface`
 and is one of the constructor arguments to ``HttpKernel``.
 
-.. image:: /_images/components/http_kernel/04-resolve-controller.png
-   :align: center
-
 Your job is to create a class that implements the interface and fill in its
 two methods: ``getController()`` and ``getArguments()``. In fact, one default
 implementation already exists, which you can use directly or learn from:
@@ -302,9 +299,6 @@ some part of the system that needs to be initialized after certain things
 have been determined (e.g. the controller, routing information) but before
 the controller is executed. For some examples, see the Symfony section below.
 
-.. image:: /_images/components/http_kernel/06-kernel-controller.png
-   :align: center
-
 Listeners to this event can also change the controller callable completely
 by calling :method:`FilterControllerEvent::setController <Symfony\\Component\\HttpKernel\\Event\\FilterControllerEvent::setController>`
 on the event object that's passed to listeners on this event.
@@ -336,9 +330,6 @@ should be passed to that controller. Exactly how this is done is completely
 up to your design, though the built-in :class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentResolver`
 is a good example.
 
-.. image:: /_images/components/http_kernel/07-controller-arguments.png
-   :align: center
-
 At this point the kernel has a PHP callable (the controller) and an array
 of arguments that should be passed when executing that callable.
 
@@ -379,9 +370,6 @@ of arguments that should be passed when executing that callable.
 
 The next step is simple! ``HttpKernel::handle()`` executes the controller.
 
-.. image:: /_images/components/http_kernel/08-call-controller.png
-   :align: center
-
 The job of the controller is to build the response for the given resource.
 This could be an HTML page, a JSON string or anything else. Unlike every
 other part of the process so far, this step is implemented by the "end-developer",
@@ -391,9 +379,6 @@ Usually, the controller will return a ``Response`` object. If this is true,
 then the work of the kernel is just about done! In this case, the next step
 is the :ref:`kernel.response <component-http-kernel-kernel-response>` event.
 
-.. image:: /_images/components/http_kernel/09-controller-returns-response.png
-   :align: center
-
 But if the controller returns anything besides a ``Response``, then the kernel
 has a little bit more work to do - :ref:`kernel.view <component-http-kernel-kernel-view>`
 (since the end goal is *always* to generate a ``Response`` object).
@@ -418,9 +403,6 @@ another event - ``kernel.view``. The job of a listener to this event is to
 use the return value of the controller (e.g. an array of data or an object)
 to create a ``Response``.
 
-.. image:: /_images/components/http_kernel/10-kernel-view.png
-   :align: center
-
 This can be useful if you want to use a "view" layer: instead of returning
 a ``Response`` from the controller, you return data that represents the page.
 A listener to this event could then use this data to create a ``Response`` that
@@ -549,8 +531,9 @@ function is wrapped in a try-catch block. When any exception is thrown, the
 ``kernel.exception`` event is dispatched so that your system can somehow respond
 to the exception.
 
-.. image:: /_images/components/http_kernel/11-kernel-exception.png
-   :align: center
+.. raw:: html
+
+    <object data="../_images/components/http_kernel/http-workflow-exception.svg" type="image/svg+xml"></object>
 
 Each listener to this event is passed a :class:`Symfony\\Component\\HttpKernel\\Event\\GetResponseForExceptionEvent`
 object, which you can use to access the original exception via the
@@ -706,8 +689,9 @@ a page instead of a full page. You'll most commonly make sub-requests from
 your controller (or perhaps from inside a template, that's being rendered by
 your controller).
 
-.. image:: /_images/components/http_kernel/sub-request.png
-   :align: center
+.. raw:: html
+
+    <object data="../_images/components/http_kernel/http-workflow-subrequest.svg" type="image/svg+xml"></object>
 
 To execute a sub request, use ``HttpKernel::handle()``, but change the second
 argument as follows::

_images/components/http_kernel/02-kernel-request.png

@@ -616,9 +616,11 @@ Now, you need to put some code into the ``removeTag()`` method of ``Task``::
 Template Modifications
 ~~~~~~~~~~~~~~~~~~~~~~
 
-The ``allow_delete`` option has one consequence: if an item of a collection
+The ``allow_delete`` option means that if an item of a collection
 isn't sent on submission, the related data is removed from the collection
-on the server. The solution is to remove the form element from the DOM.
+on the server. In order for this to work in an HTML form, you must remove 
+the DOM element for the collection item to be removed, before submitting
+the form.
 
 First, add a "delete this tag" link to each tag form:
 

_images/components/http_kernel/03-kernel-request-response.png

@@ -130,7 +130,7 @@ it's recommended to change these settings as follows:
 
     ; php.ini
     ; maximum memory that OPcache can use to store compiled PHP files
-    opcache.memory_consumption=256M
+    opcache.memory_consumption=256
 
     ; maximum number of files that can be stored in the cache
     opcache.max_accelerated_files=20000

_images/components/http_kernel/04-resolve-controller.png

@@ -85,15 +85,29 @@ This can be done by importing routing resources from the main routing file:
     When importing resources from YAML, the key (e.g. ``app_file``) is meaningless.
     Just be sure that it's unique so no other lines override it.
 
-Prefixing Imported Routes
-~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _prefixing-imported-routes:
+
+Prefixing the URLs of Imported Routes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can also choose to provide a "prefix" for the imported routes. For example,
 suppose you want to prefix all routes in the AppBundle with ``/site`` (e.g.
 ``/site/blog/{slug}`` instead of ``/blog/{slug}``):
 
 .. configuration-block::
 
+    .. code-block:: php-annotations
+
+        use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
+
+        /**
+         * @Route("/site")
+         */
+        class DefaultController
+        {
+            // ...
+        }
+
     .. code-block:: yaml
 
         # app/config/routing.yml