Merge branch '3.2' into 3.3

* 3.2:
  Revert "[symfony#7939] revert some changes (revert them for 3.2)"
  [symfony#7939] revert some changes (revert them for 3.2)
  Minor reword
  Update twig_reference.rst
  [symfony#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
  fixed typo in choice.rst regarding choice_loader
  File example update
  [symfony#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

@@ -468,8 +468,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

@@ -56,10 +56,16 @@ to register a new `test listener`_ called ``SymfonyTestsListener``:
 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
 
@@ -76,6 +82,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.project_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

@@ -111,7 +111,7 @@ service and use it directly::
 
         public function indexAction($name)
         {
-            $content = $this->twig->renderResponse(
+            $content = $this->twig->render(
                 'hello/index.html.twig',
                 array('name' => $name)
             );

deployment.rst

@@ -120,11 +120,20 @@ Check if your server meets the requirements by running:
 
     $ php bin/symfony_requirements
 
-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/dynamic_form_modification.rst

@@ -528,7 +528,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())
             );
         }
@@ -543,7 +543,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

@@ -161,7 +161,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.
 

reference/configuration/framework.rst

@@ -63,7 +63,9 @@ Configuration
     * `gc_divisor`_
     * `gc_probability`_
     * `gc_maxlifetime`_
+    * `use_strict_mode`_
     * `save_path`_
+    * `metadata_update_threshold`_
 * `assets`_
     * `base_path`_
     * `base_urls`_
@@ -766,6 +768,17 @@ This determines the number of seconds after which data will be seen as "garbage"
 and potentially cleaned up. Garbage collection may occur during session
 start and depends on `gc_divisor`_ and `gc_probability`_.
 
+use_strict_mode
+...............
+
+**type**: ``boolean`` **default**: ``false``
+
+This specifies whether the session module will use the strict session id mode.
+If this mode is enabled, the module does not accept uninitialized session IDs.
+If an uninitialized session ID is sent from browser, a new session ID is sent
+to browser. Applications are protected from session fixation via session
+adoption with strict mode.
+
 save_path
 .........
 
@@ -812,6 +825,19 @@ setting the value to ``null``:
             ),
         ));
 
+metadata_update_threshold
+.........................
+
+**type**: ``integer`` **default**: ``0``
+
+This is how many seconds to wait between two session metadata updates. It will
+also prevent the session handler to write if the session has not changed.
+
+.. seealso::
+
+    You can see an example of the usage of this in
+    :doc:`/session/limit_metadata_writes`.
+
 assets
 ~~~~~~
 

reference/configuration/twig.rst

@@ -25,7 +25,7 @@ TwigBundle Configuration ("twig")
                 - foundation_5_layout.html.twig
 
                 # Example:
-                - @App/form.html.twig
+                - form.html.twig
 
             globals:
 
@@ -77,7 +77,7 @@ TwigBundle Configuration ("twig")
                 optimizations="true"
             >
                 <twig:form-theme>form_div_layout.html.twig</twig:form-theme> <!-- Default -->
-                <twig:form-theme>@App/form.html.twig</twig:form-theme>
+                <twig:form-theme>form.html.twig</twig:form-theme>
 
                 <twig:global key="foo" id="bar" type="service" />
                 <twig:global key="pi">3.14</twig:global>
@@ -93,7 +93,7 @@ TwigBundle Configuration ("twig")
         $container->loadFromExtension('twig', array(
             'form_themes' => array(
                 'form_div_layout.html.twig', // Default
-                '@App/form.html.twig',
+                'form.html.twig',
              ),
              'globals' => array(
                  'foo' => '@bar',

reference/forms/types/choice.rst

@@ -198,7 +198,7 @@ if you want to take advantage of lazy loading::
     $builder->add('constants', ChoiceType::class, array(
         'choice_loader' => new CallbackChoiceLoader(function() {
             return StaticClass::getConstants();
-        },
+        }),
     ));
 
 This will cause the call of ``StaticClass::getConstants()`` to not happen if the

reference/forms/types/file.rst

@@ -52,7 +52,8 @@ be used to move the ``attachment`` file to a permanent location::
         if ($form->isSubmitted() && $form->isValid()) {
             $someNewFilename = ...
 
-            $form['attachment']->getData()->move($dir, $someNewFilename);
+            $file = $form['attachment']->getData();
+            $file->move($dir, $someNewFilename);
 
             // ...
         }

reference/twig_reference.rst

@@ -569,14 +569,18 @@ file_excerpt
 
 .. code-block:: twig
 
-    {{ file|file_excerpt(line = null) }}
+    {{ file|file_excerpt(line, srcContext = 3) }}
 
 ``file``
     **type**: ``string``
-``line`` *(optional)*
+``line``
+    **type**: ``integer``
+``srcContext`` *(optional)*
     **type**: ``integer``
 
-Generates an excerpt of seven lines around the given ``line``.
+Generates an excerpt of a code file around the given ``line`` number. The
+``srcContext`` argument defines the total number of lines to display around the
+given line number (use ``-1`` to display the whole file).
 
 format_file
 ~~~~~~~~~~~
@@ -613,12 +617,14 @@ file_link
 
 .. code-block:: twig
 
-    {{ file|file_link(line = null) }}
+    {{ file|file_link(line) }}
 
-``line`` *(optional)*
+``file``
+    **type**: ``string``
+``line``
     **type**: ``integer``
 
-Generates a link to the provided file (and optionally line number) using
+Generates a link to the provided file and line number using
 a preconfigured scheme.
 
 .. _reference-twig-tags:

security/csrf_in_login_form.rst

@@ -16,9 +16,44 @@ for CSRF. In this article you'll learn how you can use it in your login form.
 Configuring CSRF Protection
 ---------------------------
 
-First, configure the Security component so it can use CSRF protection.
-The Security component needs a CSRF token provider. You can set this to use the default
-provider available in the Security component:
+First, make sure that the CSRF protection is enabled in the main cofiguration
+file:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        framework:
+            # ...
+            csrf_protection: ~
+
+    .. code-block:: xml
+
+        <!-- app/config/config.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony
+                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <framework:config>
+                <framework:csrf-protection enabled="true" />
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/config.php
+        $container->loadFromExtension('framework', array(
+            'csrf_protection' => null,
+        ));
+
+Then, the security component needs a CSRF token provider. You can set this to
+use the default provider available in the security component:
 
 .. configuration-block::