Merge branch '2.7' into 2.8

* 2.7:
  [#7939] revert some changes (revert them for 3.2)
  Minor reword
  Update twig_reference.rst
  [#7958] fix minor typo
  improve examples of how we create test doubles
  Minor reword
  Add default indication in input arguments/options description
  Improved the explanation about deployment + parameters.yml
  Explained how to run tests in multiple kernel apps
  Fixed the explanation about PHPUnit event listeners in PHPUnitBridge
  File example update
  [#8003] add XML and PHP config examples
  Reworded the help note
  adding note that CSRF protection has to be enabled in config
  follow best practices for template files
  Added a note about disabling FastCGI buffering in Nginx
  Add some doc on missing options of framework bundle configuration
  Reworded the explanation about the --router option

Author: xabbuh

components/http_foundation.rst

@@ -464,8 +464,12 @@ represented by a PHP callable instead of a string::
     you must call ``ob_flush()`` before ``flush()``.
 
     Additionally, PHP isn't the only layer that can buffer output. Your web
-    server might also buffer based on its configuration. What's more, if you
-    use FastCGI, buffering can't be disabled at all.
+    server might also buffer based on its configuration. Some servers, such as
+    Nginx, let you disable buffering at config level or adding a special HTTP
+    header in the response::
+
+        // disables FastCGI buffering in Nginx only for this response
+        $response->headers->set('X-Accel-Buffering', 'no')
 
 .. _component-http-foundation-serving-files:
 

components/phpunit_bridge.rst

@@ -39,10 +39,16 @@ You can install the component in 2 different ways:
 Usage
 -----
 
-Once the component is installed, it automatically registers a
-`PHPUnit event listener`_ which in turn registers a `PHP error handler`_
-called :class:`Symfony\\Bridge\\PhpUnit\\DeprecationErrorHandler`. After
-running your PHPUnit tests, you will get a report similar to this one:
+Once the component is installed, a ``simple-phpunit`` script is created in the
+``vendor/`` directory to run tests. This script wraps the original PHPUnit binary
+to provide more features:
+
+.. code-block:: terminal
+
+    $ cd my-project/
+    $ ./vendor/bin/simple-phpunit
+
+After running your PHPUnit tests, you will get a report similar to this one:
 
 .. image:: /_images/components/phpunit_bridge/report.png
 
@@ -59,6 +65,21 @@ The summary includes:
     Deprecation notices are all other (non-legacy) notices, grouped by message,
     test class and method.
 
+.. note::
+
+    If you don't want to use the ``simple-phpunit`` script, register the following
+    `PHPUnit event listener`_ in your PHPUnit configuration file to get the same
+    report about deprecations (which is created by a `PHP error handler`_
+    called :class:`Symfony\\Bridge\\PhpUnit\\DeprecationErrorHandler`):
+
+    .. code-block:: xml
+
+        <!-- phpunit.xml.dist -->
+        <!-- ... -->
+        <listeners>
+            <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener" />
+        </listeners>
+
 Trigger Deprecation Notices
 ---------------------------
 

configuration/multiple_kernels.rst

@@ -178,6 +178,43 @@ In order to solve this issue, add the following configuration to your kernel:
             # allows to use app/Resources/views/ templates in the ApiKernel
             "%kernel.root_dir%/../app/Resources/views": ~
 
+Running Tests Using a Different Kernel
+--------------------------------------
+
+In Symfony applications, functional tests extend by default from the
+:class:`Symfony\\Bundle\\FrameworkBundle\\Test\\WebTestCase` class. Inside that
+class, a method called ``getKernelClass()`` tries to find the class of the kernel
+to use to run the application during tests. The logic of this method does not
+support multiple kernel applications, so your tests won't use the right kernel.
+
+The solution is to create a custom base class for functional tests extending
+from ``WebTestCase`` class and overriding the ``getKernelClass()`` method to
+return the fully qualified class name of the kernel to use::
+
+    use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
+
+    // tests needing the ApiKernel to work, now must extend this
+    // ApiTestCase class instead of the default WebTestCase class
+    class ApiTestCase extends WebTestCase
+    {
+        protected static function getKernelClass()
+        {
+            return 'ApiKernel';
+        }
+
+        // this is needed because the KernelTestCase class keeps a reference to
+        // the previously created kernel in its static $kernel property. Thus,
+        // if your functional tests do not run in isolated processes, a later run
+        // test for a different kernel will reuse the previously created instance,
+        // which points to a different kernel
+        protected function tearDown()
+        {
+            parent::tearDown();
+
+            static::$class = null;
+        }
+    }
+
 Adding more Kernels to the Application
 --------------------------------------
 

console/input.rst

@@ -91,11 +91,12 @@ There are three argument variants you can use:
     provided;
 
 ``InputArgument::OPTIONAL``
-    The argument is optional and therefore can be omitted;
+    The argument is optional and therefore can be omitted. This is the default
+    behavior of arguments;
 
 ``InputArgument::IS_ARRAY``
     The argument can contain any number of values. For that reason, it must be
-    used at the end of the argument list
+    used at the end of the argument list.
 
 You can combine ``IS_ARRAY`` with ``REQUIRED`` and ``OPTIONAL`` like this::
 
@@ -177,11 +178,15 @@ There are four option variants you can use:
 
 ``InputOption::VALUE_IS_ARRAY``
     This option accepts multiple values (e.g. ``--dir=/foo --dir=/bar``);
+
 ``InputOption::VALUE_NONE``
-    Do not accept input for this option (e.g. ``--yell``);
+    Do not accept input for this option (e.g. ``--yell``). This is the default
+    behavior of options;
+
 ``InputOption::VALUE_REQUIRED``
     This value is required (e.g. ``--iterations=5``), the option itself is
     still optional;
+
 ``InputOption::VALUE_OPTIONAL``
     This option may or may not have a value (e.g. ``--yell`` or
     ``--yell=loud``).

controller/service.rst

@@ -174,7 +174,7 @@ Symfony's base controller::
         public function indexAction($name)
         {
             return $this->render(
-                '@App/Hello/index.html.twig',
+                'hello/index.html.twig',
                 array('name' => $name)
             );
         }
@@ -210,7 +210,7 @@ service and use it directly::
         public function indexAction($name)
         {
             return $this->templating->renderResponse(
-                '@App/Hello/index.html.twig',
+                'hello/index.html.twig',
                 array('name' => $name)
             );
         }

deployment.rst

@@ -120,11 +120,20 @@ Check if your server meets the requirements by running:
 
     $ php app/check.php
 
-B) Configure your ``app/config/parameters.yml`` File
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _b-configure-your-app-config-parameters-yml-file:
 
-This file should *not* be deployed, but managed through the automatic utilities
-provided by Symfony.
+B) Configure your Parameters File
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Most Symfony applications define configuration parameters in a file called
+``app/config/parameters.yml``. This file should *not* be deployed, because
+Symfony generates it automatically using the ``app/config/parameters.yml.dist``
+file as a template (that's why ``parameters.yml.dist`` must be committed and
+deployed).
+
+If your application uses environment variables instead of these parameters, you
+must define those env vars in your production server using the tools provided by
+your hosting service.
 
 C) Install/Update your Vendors
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

form/direct_submit.rst

@@ -28,7 +28,7 @@ submissions::
             return $this->redirectToRoute('task_success');
         }
 
-        return $this->render('@App/Default/new.html.twig', array(
+        return $this->render('default/new.html.twig', array(
             'form' => $form->createView(),
         ));
     }
@@ -67,7 +67,7 @@ method, pass the submitted data directly to
             }
         }
 
-        return $this->render('@App/Default/new.html.twig', array(
+        return $this->render('default/new.html.twig', array(
             'form' => $form->createView(),
         ));
     }
@@ -126,7 +126,7 @@ a convenient shortcut to the previous example::
             }
         }
 
-        return $this->render('@App/Default/new.html.twig', array(
+        return $this->render('default/new.html.twig', array(
             'form' => $form->createView(),
         ));
     }

form/dynamic_form_modification.rst

@@ -569,7 +569,7 @@ your application. Assume that you have a sport meetup creation controller::
             }
 
             return $this->render(
-                '@App/Meetup/create.html.twig',
+                'meetup/create.html.twig',
                 array('form' => $form->createView())
             );
         }
@@ -584,7 +584,7 @@ field according to the current selection in the ``sport`` field:
 
     .. code-block:: html+twig
 
-        {# app/Resources/views/Meetup/create.html.twig #}
+        {# app/Resources/views/meetup/create.html.twig #}
         {{ form_start(form) }}
             {{ form_row(form.sport) }}    {# <select id="meetup_sport" ... #}
             {{ form_row(form.position) }} {# <select id="meetup_position" ... #}

form/form_collections.rst

@@ -177,7 +177,7 @@ In your controller, you'll create a new form from the ``TaskType``::
                 // ... maybe do some form processing, like saving the Task and Tag objects
             }
 
-            return $this->render('@App/Task/new.html.twig', array(
+            return $this->render('task/new.html.twig', array(
                 'form' => $form->createView(),
             ));
         }
@@ -193,7 +193,7 @@ zero tags when first created).
 
     .. code-block:: html+twig
 
-        {# src/AppBundle/Resources/views/Task/new.html.twig #}
+        {# app/Resources/views/task/new.html.twig #}
 
         {# ... #}
 

profiler/data_collector.rst

@@ -197,7 +197,7 @@ block and set the value of two variables called ``icon`` and ``text``:
 
     .. code-block:: twig
 
-        {{ include('@App/data_collector/icon.svg') }}
+        {{ include('data_collector/icon.svg') }}
 
     You are encouraged to use the latter technique for your own toolbar panels.