Merge branch '3.4' into 4.2

* 3.4:
  Removed more belittling words and expressions

Author: javiereguiluz

_build/maintainer_guide.rst

@@ -120,8 +120,8 @@ Step 2: Merge the pull request
 Never use GitHub's web interface (or desktop clients) to merge PRs or to solve
 merge conflicts. Always use the ``gh`` tool for anything related to merges.
 
-We require 2 approval votes from team members before merging a PR, except if
-it's a typo, a small change or an obvious error.
+We require two approval votes from team members before merging a PR, except if
+it's a typo, a small change or clearly an error.
 
 If a PR contains lots of commits, there's no need to ask the contributor to
 squash them. The ``gh`` tool does that automatically. The only exceptions are

best_practices/business-logic.rst

@@ -109,8 +109,8 @@ distributed among developers, with a slight preference towards YAML.
 Both formats have the same performance, so this is ultimately a matter of
 personal taste.
 
-We recommend YAML because it's friendly to newcomers and concise. You can
-use any of the other formats if you prefer another format.
+We recommend YAML because it's friendly to newcomers and concise, but you can
+use whatever format you like.
 
 Using a Persistence Layer
 -------------------------

best_practices/configuration.rst

@@ -138,8 +138,8 @@ Constants can be used for example in your Twig templates thanks to the
         Displaying the {{ constant('NUMBER_OF_ITEMS', post) }} most recent results.
     </p>
 
-And Doctrine entities and repositories can now easily access these values,
-whereas they cannot access the container parameters::
+And Doctrine entities and repositories can access these values too, whereas they
+cannot access the container parameters::
 
     namespace App\Repository;
 
@@ -155,7 +155,7 @@ whereas they cannot access the container parameters::
     }
 
 The only notable disadvantage of using constants for this kind of configuration
-values is that you cannot redefine them easily in your tests.
+values is that it's complicated to redefine their values in your tests.
 
 Parameter Naming
 ----------------

best_practices/controllers.rst

@@ -89,10 +89,10 @@ The ``@Template`` annotation is useful, but also involves some magic. We
 don't think its benefit is worth the magic, and so recommend against using
 it.
 
-Most of the time, ``@Template`` is used without any parameters, which makes
-it more difficult to know which template is being rendered. It also makes
-it less obvious to beginners that a controller should always return a Response
-object (unless you're using a view layer).
+Most of the time, ``@Template`` is used without any parameters, which makes it
+more difficult to know which template is being rendered. It also hides the fact
+that a controller should always return a Response object (unless you're using a
+view layer).
 
 What does the Controller look like
 ----------------------------------

best_practices/security.rst

@@ -18,10 +18,10 @@ primarily under the ``firewalls`` key.
     API only), we recommend having only *one* firewall entry with the ``anonymous``
     key enabled.
 
-Most applications only have one authentication system and one set of users.
-For this reason, you only need *one* firewall entry. There are exceptions
-of course, especially if you have separated web and API sections on your
-site. But the point is to keep things simple.
+Most applications only have one authentication system and one set of users. For
+this reason, you only need *one* firewall entry. If you have separated web and
+API sections on your site, you will need more firewall entries. But the point is
+to keep things simple.
 
 Additionally, you should use the ``anonymous`` key under your firewall. If
 you need to require users to be logged in for different sections of your

best_practices/tests.rst

@@ -106,8 +106,8 @@ The built-in functional testing client is great, but it can't be used to
 test any JavaScript behavior on your pages. If you need to test this, consider
 using the `Mink`_ library from within PHPUnit.
 
-Of course, if you have a heavy JavaScript front-end, you should consider using
-pure JavaScript-based testing tools.
+If you have a heavy JavaScript frontend, you should consider using pure
+JavaScript-based testing tools.
 
 Learn More about Functional Tests
 ---------------------------------

components/dom_crawler.rst

@@ -34,7 +34,7 @@ The :class:`Symfony\\Component\\DomCrawler\\Crawler` class provides methods
 to query and manipulate HTML and XML documents.
 
 An instance of the Crawler represents a set of :phpclass:`DOMElement` objects,
-which are basically nodes that you can traverse::
+which are nodes that can be traversed as follows::
 
     use Symfony\Component\DomCrawler\Crawler;
 

components/dotenv.rst

@@ -88,11 +88,12 @@ defined in previously loaded files:
 #. If there's a ``.env.$env.local`` file, this one is loaded. Otherwise, it falls
    back to ``.env.$env``.
 
-This might look complicated at first glance but it gives you the opportunity to commit
-multiple environment-specific files that can then be adjusted to your local environment
-easily. Given you commit ``.env``, ``.env.test`` and ``.env.dev`` to represent different
-configuration settings for your environments, each of them can be adjusted by using
-``.env.local``, ``.env.test.local`` and ``.env.dev.local`` respectively.
+This might look complicated at first glance but it gives you the opportunity to
+commit multiple environment-specific files that can then be adjusted to your
+local environment. Given you commit ``.env``, ``.env.test`` and ``.env.dev`` to
+represent different configuration settings for your environments, each of them
+can be adjusted by using ``.env.local``, ``.env.test.local`` and
+``.env.dev.local`` respectively.
 
 .. note::
 

components/form.rst

@@ -163,10 +163,10 @@ You can disable CSRF protection per form using the ``csrf_protection`` option::
 Twig Templating
 ~~~~~~~~~~~~~~~
 
-If you're using the Form component to process HTML forms, you'll need a way
-to render your form as HTML form fields (complete with field values,
-errors, and labels). If you use `Twig`_ as your template engine, the Form
-component offers a rich integration.
+If you're using the Form component to process HTML forms, you'll need a way to
+render your form as HTML form fields (complete with field values, errors, and
+labels). If you use `Twig`_ as your template engine, the Form component offers a
+rich integration.
 
 To use the integration, you'll need the twig bridge, which provides integration
 between Twig and several Symfony components:

components/http_foundation/session_testing.rst

@@ -6,8 +6,8 @@ Testing with Sessions
 =====================
 
 Symfony is designed from the ground up with code-testability in mind. In order
-to make your code which utilizes session easily testable, we provide two separate
-mock storage mechanisms for both unit testing and functional testing.
+to test your code which utilizes sessions, we provide two separate mock storage
+mechanisms for both unit testing and functional testing.
 
 Testing code using real sessions is tricky because PHP's workflow state is global
 and it is not possible to have multiple concurrent sessions in the same PHP

components/security/authorization.rst

@@ -159,8 +159,8 @@ role::
 
 .. note::
 
-    When you make your own voter, you can use its constructor
-    to inject any dependencies it needs to come to a decision.
+    When you make your own voter, you can use its constructor to inject any
+    dependencies it needs to come to a decision.
 
 Roles
 -----

configuration/front_controllers_and_kernel.rst

@@ -101,9 +101,9 @@ This class uses the name of the environment - which is passed to the Kernel's
 method and is available via :method:`Symfony\\Component\\HttpKernel\\Kernel::getEnvironment` -
 to decide which bundles to enable. The logic for that is in ``registerBundles()``.
 
-You are, of course, free to create your own, alternative or additional
-``Kernel`` variants. All you need is to adapt your (or add a new) front
-controller to make use of the new kernel.
+You are free to create your own, alternative or additional ``Kernel`` variants.
+All you need is to adapt your (or add a new) front controller to make use of the
+new kernel.
 
 .. note::
 

contributing/code/bugs.rst

@@ -26,7 +26,7 @@ If your problem definitely looks like a bug, report it using the official bug
 * Describe the steps needed to reproduce the bug with short code examples
   (providing a unit test that illustrates the bug is best);
 
-* If the bug you experienced is not obvious or affects more than one layer,
+* If the bug you experienced is not simple or affects more than one layer,
   providing a simple failing unit test may not be sufficient. In this case,
   please :doc:`provide a reproducer </contributing/code/reproducer>`;
 

contributing/code/reproducer.rst

@@ -2,11 +2,11 @@ Creating a Bug Reproducer
 =========================
 
 The main Symfony code repository receives thousands of issues reports per year.
-Some of those issues are so obvious or easy to understand, that Symfony Core
-developers can fix them without any other information. However, other issues are
-much harder to understand because developers can't easily reproduce them in their
-computers. That's when we'll ask you to create a "bug reproducer", which is the
-minimum amount of code needed to make the bug appear when executed.
+Some of those issues are easy to understand and the Symfony Core developers can
+fix them without any other information. However, other issues are much harder to
+understand because developers can't reproduce them in their computers. That's
+when we'll ask you to create a "bug reproducer", which is the minimum amount of
+code needed to make the bug appear when executed.
 
 Reproducing Simple Bugs
 -----------------------

contributing/community/reviews.rst

@@ -24,7 +24,7 @@ On the `Symfony issue tracker`_, you can find many items in a `Needs Review`_
 status:
 
 * **Bug Reports**: Bug reports need to be checked for completeness.
-  Is any important information missing? Can the bug be *easily* reproduced?
+  Is any important information missing? Can the bug be reproduced?
 
 * **Pull Requests**: Pull requests contain code that fixes a bug or implements
   new functionality. Reviews of pull requests ensure that they are implemented
@@ -146,7 +146,7 @@ Pick a pull request from the `PRs in need of review`_ and follow these steps:
    * Does the PR stay within scope to address *only* that issue?
    * Does the PR contain automated tests? Do those tests cover all relevant
      edge cases?
-   * Does the PR contain sufficient comments to easily understand its code?
+   * Does the PR contain sufficient comments to understand its code?
    * Does the code break backward compatibility? If yes, does the PR header say
      so?
    * Does the PR contain deprecations? If yes, does the PR header say so? Does

create_framework/http_foundation.rst

@@ -9,10 +9,9 @@ top of the Symfony components is better than creating a framework from scratch.
 
 .. note::
 
-    We won't talk about the obvious and traditional benefits of using a
-    framework when working on big applications with more than a few
-    developers; the Internet has already plenty of good resources on that
-    topic.
+    We won't talk about the traditional benefits of using a framework when
+    working on big applications with more than a few developers; the Internet
+    has already plenty of good resources on that topic.
 
 Even if the "application" we wrote in the previous chapter was simple enough,
 it suffers from a few problems::
@@ -87,9 +86,9 @@ reading this book now and go back to whatever code you were working on before.
 
 .. note::
 
-    Of course, using a framework should give you more than just security and
-    testability, but the more important thing to keep in mind is that the
-    framework you choose must allow you to write better code faster.
+    Using a framework should give you more than just security and testability,
+    but the more important thing to keep in mind is that the framework you
+    choose must allow you to write better code faster.
 
 Going OOP with the HttpFoundation Component
 -------------------------------------------

create_framework/http_kernel_httpkernel_class.rst

@@ -104,8 +104,8 @@ The error controller reads as follows::
         }
     }
 
-Voilà! Clean and customizable error management without efforts. And
-if your ``ErrorController`` throws an exception, HttpKernel will handle it nicely.
+*Voilà!* Clean and customizable error management without efforts. And if your
+``ErrorController`` throws an exception, HttpKernel will handle it nicely.
 
 In chapter two, we talked about the ``Response::prepare()`` method, which
 ensures that a Response is compliant with the HTTP specification. It is

create_framework/introduction.rst

@@ -38,8 +38,8 @@ you can use as is or as a start for your very own. It will start with a simple
 framework and more features will be added with time. Eventually, you will have
 a fully-featured full-stack web framework.
 
-And each step will be the occasion to learn more about some of the
-Symfony Components.
+And each step will be the occasion to learn more about some of the Symfony
+Components.
 
 Many modern web frameworks advertize themselves as being MVC frameworks. This
 tutorial won't talk about the MVC pattern, as the Symfony Components are able to

create_framework/templating.rst

@@ -69,8 +69,8 @@ the ``_controller`` route attribute::
         $response = new Response('An error occurred', 500);
     }
 
-A route can now be associated with any controller and within a
-controller, you can still use the ``render_template()`` to render a template::
+A route can now be associated with any controller and within a controller, you
+can still use the ``render_template()`` to render a template::
 
     $routes->add('hello', new Routing\Route('/hello/{name}', [
         'name' => 'World',

deployment.rst

@@ -63,8 +63,8 @@ manually taking other steps (see `Common Post-Deployment Tasks`_).
 Using Platforms as a Service
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Using a Platform as a Service (PaaS) can be a great way to deploy your Symfony app
-quickly and easily. There are many PaaS - below are a few that work well with Symfony:
+Using a Platform as a Service (PaaS) can be a great way to deploy your Symfony
+app quickly. There are many PaaS - below are a few that work well with Symfony:
 
 * `Symfony Cloud`_
 * `Heroku`_

doctrine.rst

@@ -242,9 +242,9 @@ your production database up-to-date.
 Migrations & Adding more Fields
 -------------------------------
 
-But what if you need to add a new field property to ``Product``, like a ``description``?
-You can edit the class to add the new property. But, you can also use ``make:entity``
-again:
+But what if you need to add a new field property to ``Product``, like a
+``description``? You can edit the class to add the new property. But, you can
+also use ``make:entity`` again:
 
 .. code-block:: terminal
 

email/spool.rst

@@ -141,9 +141,9 @@ You can also set the time limit in seconds:
 
     $ APP_ENV=prod php bin/console swiftmailer:spool:send --time-limit=10
 
-You will most likely not want to run this command manually in reality. Instead, the
-console command should be triggered by a cron job or scheduled task and run
-at a regular interval.
+In practice you will not want to run this manually. Instead, the console command
+should be triggered by a cron job or scheduled task and run at a regular
+interval.
 
 .. caution::
 

form/form_customization.rst

@@ -305,8 +305,8 @@ form_rest(form_view, variables)
 
 This renders all fields that have not yet been rendered for the given form.
 It's a good idea to always have this somewhere inside your form as it'll
-render hidden fields for you and make any fields you forgot to render more
-obvious (since it'll render the field for you).
+render hidden fields for you and make any fields you forgot to render easier to
+spot (since it'll render the field for you).
 
 .. code-block:: twig
 

frontend/encore/shared-entry.rst

@@ -30,7 +30,7 @@ then ``jquery`` would be packaged into *both* files, which is wasteful. By makin
 *no longer* be packaged into any other files. The same is true for any CSS.
 
 Because ``app.js`` contains all the common code that other entry files depend on,
-it's obvious that its script (and link) tag must be on every page.
+its script (and link) tag must be on every page.
 
 .. tip::
 

frontend/encore/simple-example.rst

@@ -23,7 +23,7 @@ application: it will *require* all of the dependencies it needs (e.g. jQuery or
 
 Encore's job (via Webpack) is simple: to read and follow *all* of the ``require``
 statements and create one final ``app.js`` (and ``app.css``) that contains *everything*
-your app needs. Of course, Encore can do a lot more: minify files, pre-process Sass/LESS,
+your app needs. Encore can do a lot more: minify files, pre-process Sass/LESS,
 support React, Vue.js, etc.
 
 Configuring Encore/Webpack

http_cache.rst

@@ -13,7 +13,7 @@ Caching on the Shoulders of Giants
 ----------------------------------
 
 With HTTP Caching, you cache the full output of a page (i.e. the response) and bypass
-your application *entirely* on subsequent requests. Of course, caching entire responses
+your application *entirely* on subsequent requests. Caching entire responses
 isn't always possible for highly dynamic sites, or is it? With
 :doc:`Edge Side Includes (ESI) </http_cache/esi>`, you can use the power of HTTP caching
 on only *fragments* of your site.

introduction/from_flat_php_to_symfony.rst

@@ -133,7 +133,7 @@ of *your* code that processes user input and prepares the response.
 
 In this case, the controller prepares data from the database and then includes
 a template to present that data. With the controller isolated, you could
-easily change *just* the template file if you needed to render the blog
+change *just* the template file if you needed to render the blog
 entries in some other format (e.g. ``list.json.php`` for JSON format).
 
 Isolating the Application (Domain) Logic
@@ -243,9 +243,8 @@ the ``templates/layout.php``:
 You now have a setup that will allow you to reuse the layout.
 Unfortunately, to accomplish this, you're forced to use a few ugly
 PHP functions (``ob_start()``, ``ob_get_clean()``) in the template. Symfony
-uses a :doc:`Templating </components/templating>` component
-that allows this to be accomplished cleanly and easily. You'll see it in
-action shortly.
+solves this using a :doc:`Templating </components/templating>` component.
+You'll see it in action shortly.
 
 Adding a Blog "show" Page
 -------------------------
@@ -307,7 +306,7 @@ Creating the second page now requires very little work and no code is duplicated
 this page introduces even more lingering problems that a framework can solve
 for you. For example, a missing or invalid ``id`` query parameter will cause
 the page to crash. It would be better if this caused a 404 page to be rendered,
-but this can't really be done easily yet.
+but this can't really be done yet.
 
 Another major problem is that each individual controller file must include
 the ``model.php`` file. What if each controller file suddenly needed to include

introduction/http_fundamentals.rst

@@ -275,11 +275,11 @@ and more.
     that you can use in *any* PHP project. This also contains classes for handling
     sessions, file uploads and more.
 
-If Symfony offered nothing else, you would already have a toolkit for conveniently
-accessing request information and an object-oriented interface for creating
-the response. Even as you learn the many powerful features in Symfony, keep
-in mind that the goal of your application is always *to interpret a request
-and create the appropriate response based on your application logic*.
+If Symfony offered nothing else, you would already have a toolkit for accessing
+request information and an object-oriented interface for creating the response.
+Even as you learn the many powerful features in Symfony, keep in mind that the
+goal of your application is always *to interpret a request and create the
+appropriate response based on your application logic*.
 
 The Journey from the Request to the Response
 --------------------------------------------

page_creation.rst

@@ -264,8 +264,8 @@ Great news! You've already worked inside the most important directories in your
 project:
 
 ``config/``
-    Contains... configuration of course!. You will configure routes, :doc:`services </service_container>`
-    and packages.
+    Contains... configuration!. You will configure routes,
+    :doc:`services </service_container>` and packages.
 
 ``src/``
     All your PHP code lives here.