Merge branch '3.3' into 3.4

* 3.3: (31 commits)
  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
  Minor change
  Add reference to docs in frontend page
  Add typescript loader documentation
  Explained how to run tests in multiple kernel apps
  Fixed the explanation about PHPUnit event listeners in PHPUnitBridge
  Fix minor typo
  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
  ...

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

@@ -114,7 +114,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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

doctrine.rst

@@ -506,7 +506,7 @@ a controller, this is pretty easy. Add the following method to the
     {
         // you can fetch the EntityManager via $this->getDoctrine()
         // or you can add an argument to your action: createAction(EntityManagerInterface $em)
-        $em = $this->get('doctrine')->getManager();
+        $em = $this->getDoctrine()->getManager();
 
         $product = new Product();
         $product->setName('Keyboard');

doctrine/multiple_entity_managers.rst

@@ -185,21 +185,19 @@ When working with multiple entity managers to update your schema:
 If you *do* omit the entity manager's name when asking for it,
 the default entity manager (i.e. ``default``) is returned::
 
-    use Doctrine\ORM\EntityManagerInterface;
-    use Doctrine\Common\Persistence\ManagerRegistry;
+    // ...
 
     class UserController extends Controller
     {
-        public function indexAction(EntityManagerInterface $em, ManagerRegistry $doctrine)
+        public function indexAction()
         {
-            // All 4  return the "default" entity manager
-            // $em from the EntityManagerInterface
-            $em = $doctrine->getManager();
-            $em = $doctrine->getManager('default');
+            // All 3 return the "default" entity manager
+            $em = $this->getDoctrine()->getManager();
+            $em = $this->getDoctrine()->getManager('default');
             $em = $this->get('doctrine.orm.default_entity_manager');
 
             // Both of these return the "customer" entity manager
-            $customerEm = $doctrine->getManager('customer');
+            $customerEm = $this->getDoctrine()->getManager('customer');
             $customerEm = $this->get('doctrine.orm.customer_entity_manager');
         }
     }
@@ -210,26 +208,29 @@ entity manager to persist and fetch its entities.
 
 The same applies to repository calls::
 
-    use Doctrine\Common\Persistence\ManagerRegistry;
     use AcmeStoreBundle\Entity\Customer;
     use AcmeStoreBundle\Entity\Product;
+    // ...
 
     class UserController extends Controller
     {
-        public function indexAction(ManagerRegistry $doctrine)
+        public function indexAction()
         {
             // Retrieves a repository managed by the "default" em
-            $products = $doctrine->getRepository(Product::class)
+            $products = $this->getDoctrine()
+                ->getRepository(Product::class)
                 ->findAll()
             ;
 
             // Explicit way to deal with the "default" em
-            $products = $doctrine->getRepository(Product::class, 'default')
+            $products = $this->getDoctrine()
+                ->getRepository(Product::class, 'default')
                 ->findAll()
             ;
 
             // Retrieves a repository managed by the "customer" em
-            $customers = $doctrine->getRepository(Customer::class, 'customer')
+            $customers = $this->getDoctrine()
+                ->getRepository(Customer::class, 'customer')
                 ->findAll()
             ;
         }

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 #}
 
         {# ... #}
 

frontend.rst

@@ -43,6 +43,7 @@ Adding more Features
 * :doc:`Enabling Vue.js (vue-loader) </frontend/encore/vuejs>`
 * :doc:`Configuring Babel </frontend/encore/babel>`
 * :doc:`Source maps </frontend/encore/sourcemaps>`
+* :doc:`Enabling TypeScript (ts-loader) </frontend/encore/typescript>`
 
 Optimizing
 ..........

frontend/encore/babel.rst

@@ -15,8 +15,9 @@ Need to extend the Babel configuration further? The easiest way is via
 
     Encore
         // ...
-
-        // modify the default Babel configuration
+        
+        // first, install any presets you want to use (e.g. yarn add babel-preset-es2017)
+        // then, modify the default Babel configuration
         .configureBabel(function(babelConfig) {
             babelConfig.presets.push('es2017');
         })

frontend/encore/typescript.rst

@@ -0,0 +1,46 @@
+Enabling TypeScript (ts-loader)
+===============================
+
+Want to use `TypeScript`_? No problem! First, install the dependencies:
+
+.. code-block:: terminal
+
+    $ yarn add --dev typescript ts-loader
+
+Then, activate the ``ts-loader`` in ``webpack.config.js``:
+
+.. code-block:: diff
+
+    // webpack.config.js
+    // ...
+
+    Encore
+        // ...
+        .addEntry('main', './assets/main.ts')
+
+        .enableTypeScriptLoader()
+    ;
+
+That's it! Any ``.ts`` files that you require will be processed correctly. You can
+also configure the `ts-loader options`_ via a callback:
+
+.. code-block:: javascript
+
+    .enableTypeScriptLoader(function (typeScriptConfigOptions) {
+        typeScriptConfigOptions.transpileOnly = true;
+        typeScriptConfigOptions.configFileName = '/path/to/tsconfig.json';
+    });
+
+If React assets are enabled (``.enableReactPreset()``), any ``.tsx`` file will be
+processed as well by ``ts-loader``.
+
+Loader usage can be checked better in its `README`_ documentation.
+
+    "Use webpack like normal, including ``webpack --watch`` and ``webpack-dev-server``,
+    or through another build system using the Node.js API."
+
+    -- Running section of ts-loader documentation
+
+.. _`TypeScript`: https://www.typescriptlang.org/
+.. _`ts-loader options`: https://github.com/TypeStrong/ts-loader#options
+.. _`README`: https://github.com/TypeStrong/ts-loader#typescript-loader-for-webpack

frontend/encore/versus-assetic.rst

@@ -3,7 +3,7 @@ Encore Versus Assetic?
 
 Symfony originally shipped with support for :doc:`Assetic </assetic>`: a
 pure PHP library capable of processing, combining and minifying CSS and JavaScript
-files. And while Encore is now the recommended way or processing your assets, Assetic
+files. And while Encore is now the recommended way of processing your assets, Assetic
 still works well.
 
 So what are the differences between Assetic and Encore?

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.