Merge branch '4.1'

* 4.1:
  review doc chapter for belittling words
  review getting started chapter for belittling words
  review best practice chapter for belittling words

Author: javiereguiluz

best_practices/business-logic.rst

@@ -110,7 +110,7 @@ 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
-of course use whatever format you like.
+use any of the other formats if you prefer another format.
 
 Using a Persistence Layer
 -------------------------

best_practices/controllers.rst

@@ -181,7 +181,7 @@ When Things Get More Advanced
 
 The above example works without any configuration because the wildcard name
 ``{id}`` matches the name of the property on the entity. If this isn't true, or
-if you have even more complex logic, the easiest thing to do is just query for
+if you have even more complex logic, your best choice is to query for
 the entity manually. In our application, we have this situation in
 ``CommentController``::
 

best_practices/introduction.rst

@@ -49,8 +49,8 @@ It's also a moving target that will continue to improve.
 
 Keep in mind that these are **optional recommendations** that you and your
 team may or may not follow to develop Symfony applications. If you want to
-continue using your own best practices and methodologies, you can of course
-do it. Symfony is flexible enough to adapt to your needs. That will never
+continue using your own best practices and methodologies, you can still do
+that. Symfony is flexible enough to adapt to your needs. That will never
 change.
 
 Who this Book Is for (Hint: It's not a Tutorial)

best_practices/templates.rst

@@ -58,7 +58,7 @@ Twig Extensions
 
 Our application needs a custom ``md2html`` Twig filter so that we can transform
 the Markdown contents of each post into HTML. To do this, create a new
-``Markdown`` class that will be used later by the Twig extension. It just needs
+``Markdown`` class that will be used later by the Twig extension. It needs
 to define one single method to transform Markdown content into HTML::
 
     namespace App\Utils;

best_practices/tests.rst

@@ -27,8 +27,8 @@ functional tests, you can quickly spot any big errors before you deploy them:
     Define a functional test that at least checks if your application pages
     are successfully loading.
 
-A functional test like this is simple to implement thanks to
-:ref:`PHPUnit data providers <testing-data-providers>`::
+:ref:`PHPUnit data providers <testing-data-providers>` help you implement
+functional tests::
 
     // tests/ApplicationAvailabilityFunctionalTest.php
     namespace App\Tests;

bundles/best_practices.rst

@@ -23,7 +23,7 @@ vendor segment, followed by zero or more category segments, and it ends with the
 namespace short name, which must end with ``Bundle``.
 
 A namespace becomes a bundle as soon as you add a bundle class to it. The
-bundle class name must follow these simple rules:
+bundle class name must follow these rules:
 
 * Use only alphanumeric characters and underscores;
 * Use a StudlyCaps name (i.e. camelCase with the first letter uppercased);
@@ -467,8 +467,9 @@ Retrieve the configuration parameters in your code from the container::
 
     $container->getParameter('acme_blog.author.email');
 
-Even if this mechanism is simple enough, you should consider using the more
-advanced :doc:`semantic bundle configuration </bundles/configuration>`.
+While this mechanism requires the least effort, you should consider using the
+more advanced :doc:`semantic bundle configuration </bundles/configuration>` to
+make your configuration more robust.
 
 Versioning
 ----------

bundles/override.rst

@@ -68,7 +68,7 @@ the routes from any bundle, then they must be manually imported from somewhere
 in your application (e.g. ``config/routes.yaml``).
 
 The easiest way to "override" a bundle's routing is to never import it at
-all. Instead of importing a third-party bundle's routing, simply copy
+all. Instead of importing a third-party bundle's routing, copy
 that routing file into your application, modify it, and import it instead.
 
 Controllers

configuration/configuration_organization.rst

@@ -5,7 +5,7 @@ How to Organize Configuration Files
 ===================================
 
 The Symfony skeleton defines three :doc:`execution environments </configuration/environments>`
-called ``dev``, ``prod`` and ``test``. An environment simply represents a way
+called ``dev``, ``prod`` and ``test``. An environment represents a way
 to execute the same codebase with different configurations.
 
 In order to select the configuration file to load for each environment, Symfony
@@ -129,9 +129,9 @@ Global Configuration Files
 
 Some system administrators may prefer to store sensitive parameters in files
 outside the project directory. Imagine that the database credentials for your
-website are stored in the ``/etc/sites/mysite.com/parameters.yaml`` file. Loading
-this file is as simple as indicating the full file path when importing it from
-any other configuration file:
+website are stored in the ``/etc/sites/mysite.com/parameters.yaml`` file. You
+can load files from outside the project folder by indicating the full file path
+when importing it from any other configuration file:
 
 .. configuration-block::
 

configuration/environments.rst

@@ -203,7 +203,7 @@ Creating a new Environment
 --------------------------
 
 Since an environment is nothing more than a string that corresponds to a set of
-configuration, creating a new environment is quite easy.
+configuration, you can also create your own environments for specific purposes.
 
 Suppose, for example, that before deployment, you need to benchmark your
 application. One way to benchmark the application is to use near-production
@@ -359,7 +359,7 @@ includes the following:
 
 .. note::
 
-    You can easily change the directory location and name. For more information
+    You can change the directory location and name. For more information
     read the article :doc:`/configuration/override_dir_structure`.
 
 Going further

configuration/front_controllers_and_kernel.rst

@@ -51,7 +51,7 @@ You can choose the front controller that's used by adding it in the URL, like:
      http://localhost/index.php/some/path/...
 
 As you can see, this URL contains the PHP script to be used as the front
-controller. You can use that to easily switch to a custom made front controller
+controller. You can use that to switch to a custom made front controller
 that is located in the ``public/`` directory.
 
 .. seealso::
@@ -123,7 +123,7 @@ controller to make use of the new kernel.
 The Environments
 ----------------
 
-As just mentioned, the ``Kernel`` has to implement another method -
+As mentioned above, the ``Kernel`` has to implement another method -
 :method:`Symfony\\Bundle\\FrameworkBundle\\Kernel\\MicroKernelTrait::configureContainer`.
 This method is responsible for loading the application's configuration from the
 right *environment*.

configuration/micro_kernel_trait.rst

@@ -5,8 +5,8 @@ The default ``Kernel`` class included in Symfony applications uses a
 :class:`Symfony\\Bundle\\FrameworkBundle\\Kernel\\MicroKernelTrait` to configure
 the bundles, the routes and the service container in the same class.
 
-This micro-kernel approach is so flexible that let you control your application
-structure and features quite easily.
+This micro-kernel approach is flexible, allowing you to control your application
+structure and features.
 
 A Single-File Symfony Application
 ---------------------------------

configuration/multiple_kernels.rst

@@ -124,7 +124,7 @@ According to the above code, this config will live in one or multiple files
 stored in ``config/api/`` and ``config/api/ENVIRONMENT_NAME/`` directories.
 
 The new configuration files can be created from scratch when you load just a few
-bundles, because it will be very simple. Otherwise, duplicate the existing
+bundles, because it will be small. Otherwise, duplicate the existing
 config files in ``config/packages/`` or better, import them and override the
 needed options.
 

configuration/override_dir_structure.rst

@@ -5,7 +5,7 @@ How to Override Symfony's default Directory Structure
 =====================================================
 
 Symfony automatically ships with a default directory structure. You can
-easily override this directory structure to create your own. The default
+override this directory structure to create your own. The default
 directory structure is:
 
 .. code-block:: text

console/input.rst

@@ -71,7 +71,7 @@ to greet all your friends). Only the last argument can be a list::
             'Who do you want to greet (separate multiple names with a space)?'
         );
 
-To use this, just specify as many names as you want:
+To use this, specify as many names as you want:
 
 .. code-block:: terminal
 

console/lazy_commands.rst

@@ -42,7 +42,7 @@ Built-in Command Loaders
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 The :class:`Symfony\\Component\\Console\\CommandLoader\\FactoryCommandLoader`
-class provides a simple way of getting commands lazily loaded as it takes an
+class provides a way of getting commands lazily loaded as it takes an
 array of ``Command`` factories as its only constructor argument::
 
     use Symfony\Component\Console\CommandLoader\FactoryCommandLoader;

console/style.rst

@@ -336,7 +336,7 @@ Defining your Own Styles
 ------------------------
 
 If you don't like the design of the commands that use the Symfony Style, you can
-define your own set of console styles. Just create a class that implements the
+define your own set of console styles. Create a class that implements the
 :class:`Symfony\\Component\\Console\\Style\\StyleInterface`::
 
     namespace App\Console;

contributing/code/git.rst

@@ -10,7 +10,7 @@ Pull Requests
 Whenever a pull request is merged, all the information contained in the pull
 request (including comments) is saved in the repository.
 
-You can easily spot pull request merges as the commit message always follows
+You can identify pull request merges as the commit message always follows
 this pattern:
 
 .. code-block:: text

contributing/code/reproducer.rst

@@ -63,7 +63,7 @@ to a route definition. Then, after creating your project:
 #. Don't edit any of the default Symfony configuration options.
 #. Don't copy your original application code and don't use the same structure
    of controllers, actions, etc. as in your original application.
-#. Create a simple controller and add your routing definition that shows the bug.
+#. Create a small controller and add your routing definition that shows the bug.
 #. Don't create or modify any other file.
 #. Execute ``composer require symfony/web-server-bundle`` and use the ``server:run``
    command to browse to the new route and see if the bug appears or not.

contributing/community/review-comments.rst

@@ -26,7 +26,7 @@ constructive, respectful and helpful reviews and replies.
     your ideas and opinions but helping you to better communicate,
     prevent possible confusion, and keeping the Symfony community a
     welcoming place for everyone. **You are free to disagree with
-    someone's opinions, just don't be disrespectful.**
+    someone's opinions, but don't be disrespectful.**
 
 First of, accept that many programming decisions are opinions.
 Discuss trade offs, which you prefer, and reach a resolution quickly.

controller.rst

@@ -192,7 +192,7 @@ Symfony comes *packed* with a lot of useful objects, called :doc:`services </ser
 These are used for rendering templates, sending emails, querying the database and
 any other "work" you can think of.
 
-If you need a service in a controller, just type-hint an argument with its class
+If you need a service in a controller, type-hint an argument with its class
 (or interface) name. Symfony will automatically pass you the service you need::
 
     use Psr\Log\LoggerInterface
@@ -273,7 +273,7 @@ the argument by its name:
             ))
         ;
 
-You can of course also use normal :ref:`constructor injection <services-constructor-injection>`
+Like with all services, you can also use regular :ref:`constructor injection <services-constructor-injection>`
 in your controllers.
 
 .. versionadded:: 4.1
@@ -358,7 +358,7 @@ The Request object as a Controller Argument
 
 What if you need to read query parameters, grab a request header or get access
 to an uploaded file? All of that information is stored in Symfony's ``Request``
-object. To get it in your controller, just add it as an argument and
+object. To get it in your controller, add it as an argument and
 **type-hint it with the Request class**::
 
     use Symfony\Component\HttpFoundation\Request;

controller/error_pages.rst

@@ -11,7 +11,7 @@ exception in your code.
 
 In the :doc:`development environment </configuration/environments>`,
 Symfony catches all the exceptions and displays a special **exception page**
-with lots of debug information to help you quickly discover the root problem:
+with lots of debug information to help you discover the root problem:
 
 .. image:: /_images/controller/error_pages/exceptions-in-dev-environment.png
    :alt: A typical exception page in the development environment
@@ -198,7 +198,7 @@ If you need a little more flexibility beyond just overriding the template,
 then you can change the controller that renders the error page. For example,
 you might need to pass some additional variables into your template.
 
-To do this, simply create a new controller anywhere in your application and set
+To do this, create a new controller anywhere in your application and set
 the :ref:`twig.exception_controller <config-twig-exception-controller>`
 configuration option to point to it:
 
@@ -249,8 +249,8 @@ will be passed two parameters:
     A :class:`\\Symfony\\Component\\HttpKernel\\Log\\DebugLoggerInterface`
     instance which may be ``null`` in some circumstances.
 
-Instead of creating a new exception controller from scratch you can, of course,
-also extend the default :class:`Symfony\\Bundle\\TwigBundle\\Controller\\ExceptionController`.
+Instead of creating a new exception controller from scratch you can also extend
+the default :class:`Symfony\\Bundle\\TwigBundle\\Controller\\ExceptionController`.
 In that case, you might want to override one or both of the ``showAction()`` and
 ``findTemplate()`` methods. The latter one locates the template to be used.
 

controller/service.rst

@@ -75,7 +75,7 @@ Invokable Controllers
 ---------------------
 
 If your controller implements the ``__invoke()`` method - popular with the
-Action-Domain-Response (ADR) pattern, you can simply refer to the service id
+Action-Domain-Response (ADR) pattern, you can refer to the service id
 without the method (``App\Controller\HelloController`` for example).
 
 Alternatives to base Controller Methods

controller/soap_web_service.rst

@@ -6,8 +6,8 @@
 How to Create a SOAP Web Service in a Symfony Controller
 ========================================================
 
-Setting up a controller to act as a SOAP server is simple with a couple
-tools. You must, of course, have the `PHP SOAP`_ extension installed.
+Setting up a controller to act as a SOAP server is aided by a couple
+tools. Those tools expect you to have the `PHP SOAP`_ extension installed.
 As the PHP SOAP extension cannot currently generate a WSDL, you must either
 create one from scratch or use a 3rd party generator.
 

create_framework/event_dispatcher.rst

@@ -248,8 +248,8 @@ issue: the knowledge of the priorities is "hardcoded" in the front controller,
 instead of being in the listeners themselves. For each application, you have
 to remember to set the appropriate priorities. Moreover, the listener method
 names are also exposed here, which means that refactoring our listeners would
-mean changing all the applications that rely on those listeners. Of course,
-there is a solution: use subscribers instead of listeners::
+mean changing all the applications that rely on those listeners. The solution
+to this dilemma is to use subscribers instead of listeners::
 
     $dispatcher = new EventDispatcher();
     $dispatcher->addSubscriber(new Simplex\ContentLengthListener());

create_framework/front_controller.rst

@@ -61,7 +61,7 @@ which name is exposed to the end user via the URL
 (``http://127.0.0.1:4321/bye.php``): there is a direct mapping between the PHP
 script name and the client URL. This is because the dispatching of the request
 is done by the web server directly. It might be a good idea to move this
-dispatching to our code for better flexibility. This can be easily achieved by
+dispatching to our code for better flexibility. This can be achieved by
 routing all client requests to a single PHP script.
 
 .. tip::

create_framework/http_foundation.rst

@@ -201,7 +201,7 @@ You can also simulate a request::
 
     $request = Request::create('/index.php?name=Fabien');
 
-With the ``Response`` class, you can easily tweak the response::
+With the ``Response`` class, you can tweak the response::
 
     $response = new Response();
 

create_framework/http_kernel_controller_resolver.rst

@@ -109,7 +109,7 @@ correctly::
     public function index($request)
 
 More interesting, ``getArguments()`` is also able to inject any Request
-attribute; the argument just needs to have the same name as the corresponding
+attribute; if the argument has the same name as the corresponding
 attribute::
 
     public function index($year)
@@ -127,7 +127,7 @@ optional attribute of the Request::
 
     public function index($year = 2012)
 
-Let's just inject the ``$year`` request attribute for our controller::
+Let's inject the ``$year`` request attribute for our controller::
 
     class LeapYearController
     {

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 of course,
-if your controller 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
@@ -115,8 +115,7 @@ client; that's what the ``ResponseListener`` does::
     $dispatcher->addSubscriber(new HttpKernel\EventListener\ResponseListener('UTF-8'));
 
 This one was easy too! Let's take another one: do you want out of the box
-support for streamed responses? Just subscribe to
-``StreamedResponseListener``::
+support for streamed responses? Subscribe to ``StreamedResponseListener``::
 
     $dispatcher->addSubscriber(new HttpKernel\EventListener\StreamedResponseListener());
 

create_framework/http_kernel_httpkernelinterface.rst

@@ -92,7 +92,7 @@ to cache a response for 10 seconds, use the ``Response::setTtl()`` method::
 
     If, like me, you are running your framework from the command line by
     simulating requests (``Request::create('/is_leap_year/2012')``), you can
-    easily debug Response instances by dumping their string representation
+    debug Response instances by dumping their string representation
     (``echo $response;``) as it displays all headers as well as the response
     content.
 
@@ -113,9 +113,9 @@ expiration and the validation models of the HTTP specification. If you are not
 comfortable with these concepts, read the `HTTP caching`_ chapter of the
 Symfony documentation.
 
-The Response class contains many other methods that let you configure the
-HTTP cache very easily. One of the most powerful is ``setCache()`` as it
-abstracts the most frequently used caching strategies into one simple array::
+The Response class contains methods that let you configure the
+HTTP cache. One of the most powerful is ``setCache()`` as it
+abstracts the most frequently used caching strategies into a single array::
 
     $date = date_create_from_format('Y-m-d H:i:s', '2005-10-15 10:00:00');
 
@@ -135,7 +135,7 @@ abstracts the most frequently used caching strategies into one simple array::
     $response->setSharedMaxAge(10);
 
 When using the validation model, the ``isNotModified()`` method allows you to
-easily cut on the response time by short-circuiting the response generation as
+cut on the response time by short-circuiting the response generation as
 early as possible::
 
     $response->setETag('whatever_you_compute_as_an_etag');