Merge remote-tracking branch 'upstream/2.7' into 2.7

Author: javiereguiluz

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

@@ -37,10 +37,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
 
@@ -57,6 +63,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

@@ -177,7 +177,7 @@ Symfony's base controller::
         public function indexAction($name)
         {
             return $this->render(
-                '@App/Hello/index.html.twig',
+                'hello/index.html.twig',
                 array('name' => $name)
             );
         }
@@ -213,7 +213,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/create_custom_field_type.rst

@@ -35,7 +35,8 @@ for form fields, which is ``<BundleName>\Form\Type``. Make sure the field extend
                     'Standard Shipping' => 'standard',
                     'Expedited Shipping' => 'expedited',
                     'Priority Shipping' => 'priority',
-                )
+                ),
+                'choices_as_values' => true,
             ));
         }
 
@@ -395,6 +396,7 @@ method to ``ShippingType``, which receives the shipping configuration::
         {
             $resolver->setDefaults(array(
                 'choices' => array_flip($this->shippingOptions),
+                'choices_as_values' => true,
             ));
         }
 

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

@@ -490,9 +490,10 @@ sport like this::
                     $positions = null === $sport ? array() : $sport->getAvailablePositions();
 
                     $form->add('position', 'entity', array(
-                        'class'       => 'AppBundle:Position',
+                        'class' => 'AppBundle:Position',
                         'placeholder' => '',
-                        'choices'     => $positions,
+                        'choices' => $positions,
+                        'choices_as_values' => true,
                     ));
                 }
             );
@@ -553,9 +554,10 @@ The type would now look like::
                 $positions = null === $sport ? array() : $sport->getAvailablePositions();
 
                 $form->add('position', 'entity', array(
-                    'class'       => 'AppBundle:Position',
+                    'class' => 'AppBundle:Position',
                     'placeholder' => '',
-                    'choices'     => $positions,
+                    'choices' => $positions,
+                    'choices_as_values' => true,
                 ));
             };
 
@@ -616,7 +618,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())
             );
         }
@@ -631,7 +633,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

@@ -184,7 +184,7 @@ In your controller, you'll now initialize a new instance of ``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(),
             ));
         }
@@ -200,7 +200,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 #}
 
         {# ... #}