Merge branch '4.2'

javiereguiluz · javiereguiluz · commit 62e0690c375c · 2019-02-28T13:07:12.000+01:00
* 4.2:
  Be keen to newcomers
  Fix \"API Platform\" case and various relative fixes
  Add missing index entry for web_link.rst
diff --git a/best_practices/business-logic.rst b/best_practices/business-logic.rst
@@ -57,8 +57,8 @@ post URL. Let's create a new ``Slugger`` class inside ``src/Utils/``::
     }
 
 If you're using the :ref:`default services.yaml configuration <service-container-services-load-example>`,
-this class is auto-registered as a service whose ID is ``App\Utils\Slugger`` (or
-simply ``Slugger::class`` if the class is already imported in your code).
+this class is auto-registered as a service with the ID ``App\Utils\Slugger`` (to
+prevent against typos, import the class and write ``Slugger::class`` in your code).
 
 .. best-practice::
 
diff --git a/bundles/configuration.rst b/bundles/configuration.rst
@@ -48,8 +48,8 @@ Using the Bundle Extension
 --------------------------
 
 Imagine you are creating a new bundle - AcmeSocialBundle - which provides
-integration with Twitter, etc. To make your bundle easy to use, you want to
-allow users to configure it with some configuration that looks like this:
+integration with Twitter. To make your bundle configurable to the user, you
+can add some configuration that looks like this:
 
 .. configuration-block::
 
diff --git a/components/dom_crawler.rst b/components/dom_crawler.rst
@@ -36,7 +36,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 easily::
+which are basically nodes that you can traverse::
 
     use Symfony\Component\DomCrawler\Crawler;
 
diff --git a/components/expression_language/extending.rst b/components/expression_language/extending.rst
@@ -127,7 +127,7 @@ or by using the second argument of the constructor::
         {
             public function __construct(CacheItemPoolInterface $parser = null, array $providers = [])
             {
-                // prepends the default provider to let users override it easily
+                // prepends the default provider to let users override it
                 array_unshift($providers, new StringExpressionLanguageProvider());
 
                 parent::__construct($parser, $providers);
diff --git a/components/http_foundation/sessions.rst b/components/http_foundation/sessions.rst
@@ -226,8 +226,7 @@ store it again::
         ],
     ];
 
-So any processing of this might quickly get ugly, even simply adding a token to
-the array::
+So any processing of this might quickly get ugly, even adding a token to the array::
 
     $tokens = $session->get('tokens');
     $tokens['c'] = $value;
diff --git a/components/http_kernel.rst b/components/http_kernel.rst
@@ -47,12 +47,12 @@ This is a simplified overview of the request workflow in Symfony applications:
 #. The **browser** displays the **resource** to the **user**.
 
 Typically, some sort of framework or system is built to handle all the repetitive
-tasks (e.g. routing, security, etc) so that a developer can easily build
-each *page* of the application. Exactly *how* these systems are built varies
-greatly. The HttpKernel component provides an interface that formalizes
-the process of starting with a request and creating the appropriate response.
-The component is meant to be the heart of any application or framework, no
-matter how varied the architecture of that system::
+tasks (e.g. routing, security, etc) so that a developer can build each *page* of
+the application. Exactly *how* these systems are built varies greatly. The HttpKernel
+component provides an interface that formalizes the process of starting with a
+request and creating the appropriate response. The component is meant to be the
+heart of any application or framework, no matter how varied the architecture of
+that system::
 
     namespace Symfony\Component\HttpKernel;
 
diff --git a/components/options_resolver.rst b/components/options_resolver.rst
@@ -522,8 +522,8 @@ Options without Default Values
 In some cases, it is useful to define an option without setting a default value.
 This is useful if you need to know whether or not the user *actually* set
 an option or not. For example, if you set the default value for an option,
-it's not possible to know whether the user passed this value or if it simply
-comes from the default::
+it's not possible to know whether the user passed this value or if it comes
+from the default::
 
     // ...
     class Mailer
diff --git a/components/serializer.rst b/components/serializer.rst
@@ -1424,7 +1424,7 @@ Learn more
 .. seealso::
 
     Normalizers for the Symfony Serializer Component supporting popular web API formats
-    (JSON-LD, GraphQL, HAL and JSONAPI) are available as part of the `API Platform`_ project.
+    (JSON-LD, GraphQL, OpenAPI, HAL, JSON:API) are available as part of the `API Platform`_ project.
 
 .. seealso::
 
diff --git a/components/yaml/yaml_format.rst b/components/yaml/yaml_format.rst
@@ -286,8 +286,8 @@ Comments can be added in YAML by prefixing them with a hash mark (``#``):
 
 .. note::
 
-    Comments are simply ignored by the YAML parser and do not need to be
-    indented according to the current level of nesting in a collection.
+    Comments are ignored by the YAML parser and do not need to be indented
+    according to the current level of nesting in a collection.
 
 Explicit Typing
 ---------------
diff --git a/configuration/environments.rst b/configuration/environments.rst
@@ -8,10 +8,10 @@ Every application is the combination of code and a set of configuration that
 dictates how that code should function. The configuration may define the database
 being used, if something should be cached or how verbose logging should be.
 
-In Symfony, the idea of "environments" is the idea that the same codebase can be
-run using multiple different configurations. For example, the ``dev`` environment
-should use configuration that makes development easy and friendly, while the
-``prod`` environment should use a set of configuration optimized for speed.
+In Symfony, the idea of "environments" is that the same codebase can be run using
+multiple different configurations. For example, the ``dev`` environment should use
+configuration that makes development comfortable and friendly, while the ``prod``
+environment should use a set of configuration optimized for speed and security.
 
 .. index::
    single: Environments; Configuration files
diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst
@@ -22,7 +22,7 @@ method signature.
 
 Also, not every BC break has the same impact on application code. While some BC
 breaks require you to make significant changes to your classes or your
-architecture, others are fixed as easily as changing the name of a method.
+architecture, others are fixed by changing the name of a method.
 
 That's why we created this page for you. The section "Using Symfony Code" will
 tell you how you can ensure that your application won't break completely when
diff --git a/contributing/code/conventions.rst b/contributing/code/conventions.rst
@@ -85,8 +85,7 @@ Deprecations
 From time to time, some classes and/or methods are deprecated in the
 framework; that happens when a feature implementation cannot be changed
 because of backward compatibility issues, but we still want to propose a
-"better" alternative. In that case, the old implementation can simply be
-**deprecated**.
+"better" alternative. In that case, the old implementation can be **deprecated**.
 
 A feature is marked as deprecated by adding a ``@deprecated`` phpdoc to
 relevant classes, methods, properties, ...::
diff --git a/contributing/code/experimental.rst b/contributing/code/experimental.rst
@@ -5,8 +5,8 @@ All Symfony features benefit from our :doc:`Backward Compatibility Promise
 </contributing/code/bc>` to give developers the confidence to upgrade to new
 versions safely and more often.
 
-But sometimes, a new feature is controversial. Or finding a good API is not
-easy. In such cases, we prefer to gather feedback from real-world usage, adapt
+But sometimes, a new feature is controversial or you cannot find a convincing API.
+In such cases, we prefer to gather feedback from real-world usage, adapt
 the API, or remove it altogether. Doing so is not possible with a no BC-break
 approach.
 
diff --git a/controller.rst b/controller.rst
@@ -7,8 +7,8 @@ Controller
 A controller is a PHP function you create that reads information from the
 ``Request`` object and creates and returns a ``Response`` object. The response could
 be an HTML page, JSON, XML, a file download, a redirect, a 404 error or anything
-else you can dream up. The controller executes whatever arbitrary logic
-*your application* needs to render the content of a page.
+else. The controller executes whatever arbitrary logic *your application* needs
+to render the content of a page.
 
 .. tip::
 
diff --git a/doctrine/associations.rst b/doctrine/associations.rst
@@ -398,7 +398,7 @@ you.
 .. image:: /_images/doctrine/mapping_relations_proxy.png
     :align: center
 
-What's important is the fact that you have easy access to the product's related
+What's important is the fact that you have access to the product's related
 category, but the category data isn't actually retrieved until you ask for
 the category (i.e. it's "lazily loaded").
 
diff --git a/doctrine/dbal.rst b/doctrine/dbal.rst
@@ -13,8 +13,9 @@ How to Use Doctrine DBAL
 
 The `Doctrine`_ Database Abstraction Layer (DBAL) is an abstraction layer that
 sits on top of `PDO`_ and offers an intuitive and flexible API for communicating
-with the most popular relational databases. In other words, the DBAL library
-makes it easy to execute queries and perform other database actions.
+with the most popular relational databases. The DBAL library allows you to write
+queries independently of your ORM models, e.g. for building reports or direct
+data manipulations.
 
 .. tip::
 
diff --git a/email.rst b/email.rst
@@ -122,9 +122,9 @@ setting up a regular SMTP server. To do that, update the ``MAILER_URL`` of your
     # username is your full Gmail or Google Apps email address
     MAILER_URL=gmail://username:password@localhost
 
-The ``gmail`` transport is simply a shortcut that uses the ``smtp`` transport,
-``ssl`` encryption, ``login`` auth mode and ``smtp.gmail.com`` host. If your app
-uses other encryption or auth mode, you must override those values
+The ``gmail`` transport is a shortcut that uses the ``smtp`` transport, ``ssl``
+encryption, ``login`` auth mode and ``smtp.gmail.com`` host. If your app uses
+other encryption or auth mode, you must override those values
 (:doc:`see mailer config reference </reference/configuration/swiftmailer>`):
 
 .. code-block:: bash
diff --git a/http_cache/esi.rst b/http_cache/esi.rst
@@ -250,6 +250,6 @@ The ``render_esi`` helper supports two other useful options:
 ``ignore_errors``
     If set to true, an ``onerror`` attribute will be added to the ESI with a value
     of ``continue`` indicating that, in the event of a failure, the gateway cache
-    will simply remove the ESI tag silently.
+    will remove the ESI tag silently.
 
 .. _`ESI`: http://www.w3.org/TR/esi-lang
diff --git a/messenger/handler_results.rst b/messenger/handler_results.rst
@@ -36,8 +36,8 @@ buses are central pieces of the application. Read Martin Fowler's
 As queries are usually synchronous and expected to be handled once,
 getting the result from the handler is a common need.
 
-To make this easy, you can leverage the ``HandleTrait`` in any class that has
-a ``$messageBus`` property::
+To avoid boilerplate code, you can leverage the ``HandleTrait`` in any class
+that has a ``$messageBus`` property::
 
     // src/Action/ListItems.php
     namespace App\Action;
diff --git a/quick_tour/flex_recipes.rst b/quick_tour/flex_recipes.rst
@@ -174,7 +174,7 @@ Are you building an API? You can already return JSON easily from any controller:
         }
     }
 
-But for a *truly* rich API, try installing `Api Platform`_:
+But for a *truly* rich API, try installing `API Platform`_:
 
 .. code-block:: terminal
 
@@ -259,5 +259,5 @@ build features *without* sacrificing code quality or performance. It's all about
 the service container, and it's Symfony's super power. Read on: about :doc:`/quick_tour/the_architecture`.
 
 .. _`https://flex.symfony.com`: https://flex.symfony.com
-.. _`Api Platform`: https://api-platform.com/
+.. _`API Platform`: https://api-platform.com/
 .. _`Twig`: https://twig.symfony.com/
diff --git a/security.rst b/security.rst
@@ -619,7 +619,7 @@ See :doc:`/security/securing_services`.
 Checking to see if a User is Logged In (IS_AUTHENTICATED_FULLY)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you *only* want to check if a user is simply logged in (you don't care about roles),
+If you *only* want to check if a user is logged in (you don't care about roles),
 you have two options. First, if you've given *every* user ``ROLE_USER``, you can
 just check for that role. Otherwise, you can use a special "attribute" in place
 of a role::
diff --git a/security/guard_authentication.rst b/security/guard_authentication.rst
@@ -6,15 +6,15 @@ Custom Authentication System with Guard (API Token Example)
 
 Whether you need to build a traditional login form, an API token authentication system
 or you need to integrate with some proprietary single-sign-on system, the Guard
-component can make it easy... and fun!
+component will be the right choice!
 
 Guard authentication can be used to:
 
 * :doc:`Build a Login Form </security/form_login_setup>`,
 * Create an API token authentication system (done on this page!)
 * `Social Authentication`_ (or use `HWIOAuthBundle`_ for a robust, but non-Guard solution)
 
-or anything else you dream up. In this example, we'll build an API token authentication
+or anything else. In this example, we'll build an API token authentication
 system so we can learn more about Guard in detail.
 
 Step 1) Prepare your User Class
diff --git a/serializer.rst b/serializer.rst
@@ -202,8 +202,19 @@ value:
 Going Further with the Serializer
 ---------------------------------
 
-`ApiPlatform`_ provides an API system supporting `JSON-LD`_ and `Hydra Core Vocabulary`_
-hypermedia formats. It is built on top of the Symfony Framework and its Serializer
+`API Platform`_ provides an API system supporting the following formats:
+
+* `JSON-LD`_ along with the `Hydra Core Vocabulary`_
+* `OpenAPI`_ v2 (formerly Swagger) and v3
+* `GraphQL`_
+* `JSON:API`_
+* `HAL`_
+* JSON
+* XML
+* YAML
+* CSV
+
+It is built on top of the Symfony Framework and its Serializer
 component. It provides custom normalizers and a custom encoder, custom metadata
 and a caching system.
 
@@ -218,7 +229,11 @@ take a look at how this bundle works.
     serializer/custom_normalizer
 
 .. _`APCu`: https://github.com/krakjoe/apcu
-.. _`ApiPlatform`: https://github.com/api-platform/core
+.. _`API Platform`: https://api-platform.com
 .. _`JSON-LD`: http://json-ld.org
 .. _`Hydra Core Vocabulary`: http://hydra-cg.com
+.. _`OpenAPI`: https://www.openapis.org
+.. _`GraphQL`: https://graphql.org
+.. _`JSON:API`: https://jsonapi.org
+.. _`HAL`: http://stateless.co/hal_specification.html
 .. _`Data URIs`: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs
diff --git a/service_container/service_subscribers_locators.rst b/service_container/service_subscribers_locators.rst
@@ -380,8 +380,8 @@ provides an implementation for
 :class:`Symfony\\Component\\DependencyInjection\\ServiceSubscriberInterface`
 that looks through all methods in your class that have no arguments and a return
 type. It provides a ``ServiceLocator`` for the services of those return types.
-The service id is ``__METHOD__``. This allows you to easily add dependencies
-to your services based on type-hinted helper methods::
+The service id is ``__METHOD__``. This allows you to add dependencies to your
+services based on type-hinted helper methods::
 
     // src/Service/MyService.php
     namespace App\Service;
diff --git a/templating.rst b/templating.rst
@@ -23,7 +23,7 @@ code.
 Templates
 ---------
 
-A template is simply a text file that can generate any text-based format
+A template is a text file that can generate any text-based format
 (HTML, XML, CSV, LaTeX ...). The most familiar type of template is a *PHP*
 template - a text file parsed by PHP that contains a mix of text and PHP code:
 
@@ -386,10 +386,9 @@ the last part of the extension (e.g. ``.twig`` or ``.php``) specifies which
 of these two *engines* should be used. The first part of the extension,
 (e.g. ``.html``, ``.css``, etc) is the final format that the template will
 generate. Unlike the engine, which determines how Symfony parses the template,
-this is simply an organizational tactic used in case the same resource needs
-to be rendered as HTML (``index.html.twig``), XML (``index.xml.twig``),
-or any other format. For more information, read the :doc:`/templating/formats`
-section.
+this is an organizational tactic used in case the same resource needs to be
+rendered as HTML (``index.html.twig``), XML (``index.xml.twig``), or any other
+format. For more information, read the :doc:`/templating/formats` section.
 
 .. index::
    single: Templating; Tags and helpers
diff --git a/templating/PHP.rst b/templating/PHP.rst
@@ -66,9 +66,9 @@ Next, enable the php engine:
             ],
         ]);
 
-You can now render a PHP template instead of a Twig one simply by using the
-``.php`` extension in the template name instead of ``.twig``. The controller
-below renders the ``index.html.php`` template::
+You can now render a PHP template instead of a Twig one by using the ``.php``
+extension in the template name instead of ``.twig``. The controller below
+renders the ``index.html.php`` template::
 
     // src/Controller/HelloController.php
 
diff --git a/templating/formats.rst b/templating/formats.rst
@@ -6,7 +6,7 @@ How to Work with Different Output Formats in Templates
 
 Templates are a generic way to render content in *any* format. While in
 most cases you'll use templates to render HTML content, a template can just
-as easily generate JavaScript, CSS, XML or any other format you can dream of.
+generate JavaScript, CSS, XML or any other format.
 
 For example, the same "resource" is often rendered in several formats.
 To render an article index page in XML, include the format in the
diff --git a/templating/inheritance.rst b/templating/inheritance.rst
@@ -47,9 +47,8 @@ Notice that this template extends the section template (``blog/layout.html.twig`
 which in turn extends the base application layout (``base.html.twig``). This is
 the common three-level inheritance model.
 
-When building your application, you may choose to follow this method or simply
+When building your application, you may choose to follow this method or
 make each page template extend the base application template directly
 (e.g. ``{% extends 'base.html.twig' %}``). The three-template model is a
 best-practice method used by vendor bundles so that the base template for a
-bundle can be easily overridden to properly extend your application's base
-layout.
+bundle can be overridden to properly extend your application's base layout.
diff --git a/templating/render_without_controller.rst b/templating/render_without_controller.rst
@@ -54,8 +54,8 @@ can do this without creating a controller:
 
         return $routes;
 
-The ``TemplateController`` will simply render whatever template you've passed as
-the ``template`` default value.
+The ``TemplateController`` will render whatever template you've passed as the
+``template`` default value.
 
 You can also use this trick when rendering embedded controllers
 from within a template. But since the purpose of rendering a controller from
diff --git a/testing/database.rst b/testing/database.rst
@@ -67,7 +67,7 @@ Suppose the class you want to test looks like this::
     }
 
 Since the ``EntityManagerInterface`` gets injected into the class through the constructor,
-it's easy to pass a mock object within a test::
+you can pass a mock object within a test::
 
     // tests/Salary/SalaryCalculatorTest.php
     namespace App\Tests\Salary;
diff --git a/web_link.rst b/web_link.rst
@@ -1,3 +1,6 @@
+.. index::
+   single: Web Link
+
 Asset Preloading and Resource Hints with HTTP/2 and WebLink
 ===========================================================
 

Original file line number	Diff line number	Diff line change
@@ -57,8 +57,8 @@ post URL. Let's create a new ``Slugger`` class inside ``src/Utils/``::
`57`	`57`	`}`
`58`	`58`
`59`	`59`	If you're using the :ref:`default services.yaml configuration <service-container-services-load-example>`,
`60`		-this class is auto-registered as a service whose ID is ``App\Utils\Slugger`` (or
`61`		-simply ``Slugger::class`` if the class is already imported in your code).
	`60`	+this class is auto-registered as a service with the ID ``App\Utils\Slugger`` (to
	`61`	+prevent against typos, import the class and write ``Slugger::class`` in your code).
`62`	`62`
`63`	`63`	`.. best-practice::`
`64`	`64`
Original file line number	Diff line number	Diff line change
`@@ -127,7 +127,7 @@ or by using the second argument of the constructor::`
`127`	`127`	`{`
`128`	`128`	`public function __construct(CacheItemPoolInterface $parser = null, array $providers = [])`
`129`	`129`	`{`
`130`		`- // prepends the default provider to let users override it easily`
	`130`	`+ // prepends the default provider to let users override it`
`131`	`131`	`array_unshift($providers, new StringExpressionLanguageProvider());`
`132`	`132`
`133`	`133`	`parent::__construct($parser, $providers);`