Merge branch '3.4' into 4.2

* 3.4:
  be keen to newcomers
  Uncomment some code in "Configuring Babel"
  Fix typo: if -> of

best_practices/controllers.rst

@@ -128,7 +128,7 @@ Fetching Services
 
 If you extend the base ``AbstractController`` class, you can't access services
 directly from the container via ``$this->container->get()`` or ``$this->get()``.
-Instead, you must use dependency injection to fetch services: most easily done by
+Instead, you must use dependency injection to fetch services by
 :ref:`type-hinting action method arguments <controller-accessing-services>`:
 
 .. best-practice::
@@ -218,9 +218,9 @@ flexible::
         // ...
     }
 
-The point is this: the ParamConverter shortcut is great for simple situations.
-But you shouldn't forget that querying for entities directly is still very
-easy.
+The point is this: the ParamConverter shortcut is great for most situations.
+However, there is nothing wrong with querying for entities directly if the
+ParamConverter would get complicated.
 
 Pre and Post Hooks
 ------------------

best_practices/security.rst

@@ -105,8 +105,7 @@ The @Security Annotation
 ------------------------
 
 For controlling access on a controller-by-controller basis, use the ``@Security``
-annotation whenever possible. It's easy to read and is placed consistently
-above each action.
+annotation whenever possible. Placing it above each action makes it consistent and readable.
 
 In our application, you need the ``ROLE_ADMIN`` in order to create a new post.
 Using ``@Security``, this looks like:
@@ -153,7 +152,7 @@ Notice that this requires the use of the `ParamConverter`_, which automatically
 queries for the ``Post`` object and puts it on the ``$post`` argument. This
 is what makes it possible to use the ``post`` variable in the expression.
 
-This has one major drawback: an expression in an annotation cannot easily
+This has one major drawback: an expression in an annotation cannot
 be reused in other parts of the application. Imagine that you want to add
 a link in a template that will only be seen by authors. Right now you'll
 need to repeat the expression code using Twig syntax:
@@ -164,7 +163,7 @@ need to repeat the expression code using Twig syntax:
         <a href=""> ... </a>
     {% endif %}
 
-The easiest solution - if your logic is simple enough - is to add a new method
+A good solution - if your logic is simple enough - can be to add a new method
 to the ``Post`` entity that checks if a given user is its author::
 
     // src/Entity/Post.php

best_practices/templates.rst

@@ -44,7 +44,7 @@ and ``edit_form.html.twig`` instead of ``EditForm.html.twig``).
     Use a prefixed underscore for partial templates in template names.
 
 You often want to reuse template code using the ``include`` function to avoid
-redundant code. To determine those partials easily in the filesystem you should
+redundant code. To determine those partials in the filesystem you should
 prefix partials and any other template without HTML body or ``extends`` tag
 with a single underscore.
 

bundles/best_practices.rst

@@ -4,10 +4,10 @@
 Best Practices for Reusable Bundles
 ===================================
 
-This article is all about how to structure your **reusable bundles** so that
-they're easy to configure and extend. Reusable bundles are those meant to be
-shared privately across many company projects or publicly so any Symfony project
-can install them.
+This article is all about how to structure your **reusable bundles** to be
+configurable and extendable. Reusable bundles are those meant to be shared
+privately across many company projects or publicly so any Symfony project can
+install them.
 
 .. index::
    pair: Bundle; Naming conventions

configuration/external_parameters.rst

@@ -7,8 +7,7 @@ How to Set external Parameters in the Service Container
 In :doc:`/configuration`, you learned how to manage your application
 configuration. At times, it may benefit your application to store certain
 credentials outside of your project code. Database configuration is one such
-example. The flexibility of the Symfony service container allows you to easily
-do this.
+example. The flexibility of the Symfony service container allows you to do this.
 
 .. _config-env-vars:
 

configuration/front_controllers_and_kernel.rst

@@ -138,9 +138,8 @@ the ``configureContainer()`` method to decide which configuration files to load.
 
 Symfony's default ``Kernel`` class implements this method by loading first the
 config files found on ``config/packages/*`` and then, the files found on
-``config/packages/ENVIRONMENT_NAME/``. You are, of course, free to implement
-this method differently if you need a more sophisticated way of loading your
-configuration.
+``config/packages/ENVIRONMENT_NAME/``. You are free to implement this method
+differently if you need a more sophisticated way of loading your configuration.
 
 .. _front controller: https://en.wikipedia.org/wiki/Front_Controller_pattern
 .. _decorate: https://en.wikipedia.org/wiki/Decorator_pattern

configuration/override_dir_structure.rst

@@ -185,7 +185,7 @@ Override the ``public`` Directory
 
 If you need to rename or move your ``public`` directory, the only thing you need
 to guarantee is that the path to the ``var`` directory is still correct in your
-``index.php`` front controller. If you simply renamed the directory, you're
+``index.php`` front controller. If you renamed the directory, you're
 fine. But if you moved it in some way, you may need to modify these paths inside
 those files::
 

console/style.rst

@@ -226,7 +226,7 @@ User Input Methods
 
         $io->ask('What is your name?');
 
-    You can pass the default value as the second argument so the user can simply
+    You can pass the default value as the second argument so the user can
     hit the <Enter> key to select that value::
 
         $io->ask('Where are you from?', 'United States');
@@ -262,7 +262,7 @@ User Input Methods
 
         $io->confirm('Restart the web server?');
 
-    You can pass the default value as the second argument so the user can simply
+    You can pass the default value as the second argument so the user can
     hit the <Enter> key to select that value::
 
         $io->confirm('Restart the web server?', true);
@@ -273,7 +273,7 @@ User Input Methods
 
         $io->choice('Select the queue to analyze', ['queue1', 'queue2', 'queue3']);
 
-    You can pass the default value as the third argument so the user can simply
+    You can pass the default value as the third argument so the user can
     hit the <Enter> key to select that value::
 
         $io->choice('Select the queue to analyze', ['queue1', 'queue2', 'queue3'], 'queue1');

create_framework/http_foundation.rst

@@ -52,7 +52,7 @@ As you can see for yourself, the simple code we had written first is not that
 simple anymore if we want to avoid PHP warnings/notices and make the code
 more secure.
 
-Beyond security, this code is not even easily testable. Even if there is not
+Beyond security, this code can be complex to test. Even if there is not
 much to test, it strikes me that writing unit tests for the simplest possible
 snippet of PHP code is not natural and feels ugly. Here is a tentative PHPUnit
 unit test for the above code::
@@ -126,10 +126,10 @@ containing the new requirement.
 .. sidebar:: Class Autoloading
 
     When installing a new dependency, Composer also generates a
-    ``vendor/autoload.php`` file that allows any class to be easily
-    `autoloaded`_. Without autoloading, you would need to require the file
-    where a class is defined before being able to use it. But thanks to
-    `PSR-4`_, we can just let Composer and PHP do the hard work for us.
+    ``vendor/autoload.php`` file that allows any class to be `autoloaded`_.
+    Without autoloading, you would need to require the file where a class
+    is defined before being able to use it. But thanks to `PSR-4`_,
+    we can just let Composer and PHP do the hard work for us.
 
 Now, let's rewrite our application by using the ``Request`` and the
 ``Response`` classes::

email/dev_environment.rst

@@ -6,10 +6,10 @@ How to Work with Emails during Development
 
 When developing an application which sends email, you will often
 not want to actually send the email to the specified recipient during
-development. If you are using the default Symfony mailer, you
-can achieve this through configuration settings without having to
-make any changes to your application's code at all. There are two main
-choices when it comes to handling email during development: (a) disabling the
+development. If you are using the SwiftmailerBundle with Symfony, you
+can achieve this through configuration settings without having to make
+any changes to your application's code at all. There are two main choices
+when it comes to handling email during development: (a) disabling the
 sending of email altogether or (b) sending all email to a specific
 address (with optional exceptions).
 

email/testing.rst

@@ -10,7 +10,7 @@ SwiftmailerBundle, which leverages the power of the `Swift Mailer`_ library.
 To functionally test that an email was sent, and even assert the email subject,
 content or any other headers, you can use :doc:`the Symfony Profiler </profiler>`.
 
-Start with a simple controller action that sends an email::
+Start with a controller action that sends an email::
 
     public function sendEmail($name, \Swift_Mailer $mailer)
     {

form/create_custom_field_type.rst

@@ -270,8 +270,8 @@ link for details), create a ``shipping_widget`` block to handle this:
 Using the Field Type
 --------------------
 
-You can now use your custom field type immediately, by creating a
-new instance of the type in one of your forms::
+You can now use your custom field type by creating a new instance of the type in
+one of your forms::
 
     // src/Form/Type/OrderType.php
     namespace App\Form\Type;

form/data_transformers.rst

@@ -252,7 +252,7 @@ that message with the ``invalid_message`` option (see below).
 Using the Transformer
 ~~~~~~~~~~~~~~~~~~~~~
 
-Next, you need to use the ``IssueToNumberTransformer`` object inside if ``TaskType``
+Next, you need to use the ``IssueToNumberTransformer`` object inside of ``TaskType``
 and add it to the ``issue`` field. No problem! Add a ``__construct()`` method
 and type-hint the new class::
 
@@ -302,7 +302,7 @@ know to pass your ``TaskType`` an instance of the ``IssueToNumberTransformer``.
 
 Now, you can use your ``TaskType``::
 
-    // e.g. in a controller somewhere
+    // e.g. somewhere in a controller
     $form = $this->createForm(TaskType::class, $task);
 
     // ...

form/direct_submit.rst

@@ -4,8 +4,7 @@
 How to Use the submit() Function to Handle Form Submissions
 ===========================================================
 
-With the ``handleRequest()`` method, you can handle form
-submissions::
+Handle the form submission with the ``handleRequest()`` method::
 
     use Symfony\Component\HttpFoundation\Request;
     // ...

form/embedded.rst

@@ -6,8 +6,8 @@ How to Embed Forms
 
 Often, you'll want to build a form that will include fields from many different
 objects. For example, a registration form may contain data belonging to
-a ``User`` object as well as many ``Address`` objects. Fortunately, this
-is easy and natural with the Form component.
+a ``User`` object as well as many ``Address`` objects. Fortunately this can
+be achieved by the Form component.
 
 .. _forms-embedding-single-object:
 

form/form_collections.rst

@@ -510,9 +510,8 @@ you will learn about next!).
     of the relationship is modified.
 
     The trick is to make sure that the single "Task" is set on each "Tag".
-    One way to do this is to add some extra logic to ``addTag()``,
-    which is called by the form type since ``by_reference`` is set to
-    ``false``::
+    One way to do this is to add some extra logic to ``addTag()``, which
+    is called by the form type since ``by_reference`` is set to ``false``::
 
         // src/Entity/Task.php
 

forms.rst

@@ -10,8 +10,8 @@ Forms
     Do you prefer video tutorials? Check out the `Symfony Forms screencast series`_.
 
 Dealing with HTML forms is one of the most common - and challenging - tasks for
-a web developer. Symfony integrates a Form component that makes dealing with
-forms easy. In this article, you'll build a complex form from the ground up,
+a web developer. Symfony integrates a Form component that helps you dealing
+with forms. In this article, you'll build a complex form from the ground up,
 learning the most important features of the form library along the way.
 
 Installation
@@ -70,12 +70,12 @@ going to need to build a form. But before you begin, first focus on the generic
         }
     }
 
-This class is a "plain-old-PHP-object" because, so far, it has nothing
-to do with Symfony or any other library. It's a normal PHP object
-that directly solves a problem inside *your* application (i.e. the need to
-represent a task in your application). By the end of this article,
-you'll be able to submit data to a ``Task`` instance (via an HTML form), validate
-its data and persist it to the database.
+This class is a "plain-old-PHP-object" because, so far, it has nothing to do
+with Symfony or any other library. It's a normal PHP object that directly solves
+a problem inside *your* application (i.e. the need to represent a task in your
+application). By the end of this article, you'll be able to submit data to a
+``Task`` instance (via an HTML form), validate its data and persist it to the
+database.
 
 .. index::
    single: Forms; Create a form in a controller

frontend.rst

@@ -28,7 +28,8 @@ to solve the most common Webpack use cases.
 .. tip::
 
     Encore is made by `Symfony`_ and works *beautifully* in Symfony applications.
-    But it can easily be used in any application... in any language!
+    But it can be used in any PHP application and even with other server side
+    programming languages!
 
 .. _encore-toc:
 

frontend/encore/advanced-config.rst

@@ -1,9 +1,9 @@
 Advanced Webpack Config
 =======================
 
-Encore generates the Webpack configuration that's used in your
+Summarized, Encore generates the Webpack configuration that's used in your
 ``webpack.config.js`` file. Encore doesn't support adding all of Webpack's
-`configuration options`_, because many can be easily added on your own.
+`configuration options`_, because many can be added on your own.
 
 For example, suppose you need to set `Webpack's watchOptions`_ setting. To do that,
 modify the config after fetching it from Encore:

frontend/encore/babel.rst

@@ -18,17 +18,19 @@ Need to extend the Babel configuration further? The easiest way is via
 
         .configureBabel(function(babelConfig) {
             // add additional presets
-            // babelConfig.presets.push('@babel/preset-flow');
+            babelConfig.presets.push('@babel/preset-flow');
 
             // no plugins are added by default, but you can add some
-            // babelConfig.plugins.push('styled-jsx/babel');
+            babelConfig.plugins.push('styled-jsx/babel');
         }, {
             // node_modules is not processed through Babel by default
             // but you can whitelist specific modules to process
-            // include_node_modules: ['foundation-sites']
+            include_node_modules: ['foundation-sites'],
 
-            // or completely control the exclude
-            // exclude: /bower_components/
+            // or completely control the exclude rule (note that you
+            // can't use both "include_node_modules" and "exclude" at
+            // the same time)
+            exclude: /bower_components/
         })
     ;
 

frontend/encore/cdn.rst

@@ -1,9 +1,8 @@
 Using a CDN
 ===========
 
-Are you deploying to a CDN? That's awesome :) - and configuring Encore for that is
-easy. Once you've made sure that your built files are uploaded to the CDN, configure
-it in Encore:
+Are you deploying to a CDN? That's awesome :) Once you've made sure that your
+built files are uploaded to the CDN, configure it in Encore:
 
 .. code-block:: diff
 

logging/formatter.rst

@@ -3,9 +3,8 @@ How to Define a Custom Logging Formatter
 
 Each logging handler uses a ``Formatter`` to format the record before logging
 it. All Monolog handlers use an instance of
-``Monolog\Formatter\LineFormatter`` by default but you can configure a
-different one. Your formatter must implement
-``Monolog\Formatter\FormatterInterface``.
+``Monolog\Formatter\LineFormatter`` by default but you can replace it.
+Your formatter must implement ``Monolog\Formatter\FormatterInterface``.
 
 For example, to use the built-in ``JsonFormatter``, register it as a service then
 configure your handler to use it:

logging/monolog_email.rst

@@ -138,8 +138,8 @@ is then passed onto the ``deduplicated`` handler.
     set the ``action_level`` to ``error`` instead of ``critical``. See the
     code above for an example.
 
-The ``deduplicated`` handler keeps all the messages for a request and
-then passes them onto the nested handler in one go, but only if the records are
+The ``deduplicated`` handler keeps all the messages for a request and then
+passes them onto the nested handler in one go, but only if the records are
 unique over a given period of time (60 seconds by default). If the records are
 duplicates they are discarded. Adding this handler reduces the amount of
 notifications to a manageable level, specially in critical failure scenarios.

reference/constraints/Bic.rst

@@ -23,7 +23,7 @@ check that the BIC is associated with a given IBAN.
 Basic Usage
 -----------
 
-To use the Bic validator, simply apply it to a property on an object that
+To use the Bic validator, apply it to a property on an object that
 will contain a Business Identifier Code (BIC).
 
 .. configuration-block::

reference/constraints/Callback.rst

@@ -3,9 +3,9 @@ Callback
 
 The purpose of the Callback constraint is to create completely custom
 validation rules and to assign any validation errors to specific fields
-on your object. If you're using validation with forms, this means that you
-can make these custom errors display next to a specific field, instead of
-simply at the top of your form.
+on your object. If you're using validation with forms, this means that
+instead of displaying custom errors at the top of the form, you can
+display them next to the field they apply to.
 
 This process works by specifying one or more *callback* methods, each of
 which will be called during the validation process. Each of those methods

reference/constraints/CardScheme.rst

@@ -20,7 +20,7 @@ a payment through a payment gateway.
 Basic Usage
 -----------
 
-To use the ``CardScheme`` validator, simply apply it to a property or method
+To use the ``CardScheme`` validator, apply it to a property or method
 on an object that will contain a credit card number.
 
 .. configuration-block::

reference/constraints/Choice.rst

@@ -127,8 +127,7 @@ Supplying the Choices with a Callback Function
 
 You can also use a callback function to specify your options. This is useful
 if you want to keep your choices in some central location so that, for example,
-you can easily access those choices for validation or for building a select
-form element::
+you can access those choices for validation or for building a select form element::
 
     // src/Entity/Author.php
     namespace App\Entity;