Merge branch '2.6' into 2.7

* 2.6: (45 commits)
  Removed duplicate "long"s
  terminate file with newline
  move title back and move description to separate file as suggested in PR symfony#4892
  move title out of included file as suggested in PR symfony#4892
  Add possible values for widget_type
  [symfony#4842] Making 2 sentences
  changes as suggested by WouterJ in pull request symfony#4842
  Add meaning of yellow icon for number of queries
  Fixing bad link name
  fix typo in event flow diagrams
  Many fixes thanks to stof, WouterJ, xabbuh and dupuchba
  added Jakub as a merger for the DomCrawler component
  [symfony#5094] Removing mkdir - it's not needed (thanks xabbuh)
  some tweaks to symfony#4601
  Moving index down to correct section
  [symfony#4989] Language tweaks and making the example simpler
  Remove useless setLocale() call and add code block with locale setter
  Finaly touches on translation locale setting note
  Review note about setting the translator locale in a controller.
  Update translation.rst
  ...

best_practices/forms.rst

@@ -207,3 +207,21 @@ Second, we recommend using ``$form->isSubmitted()`` in the ``if`` statement
 for clarity. This isn't technically needed, since ``isValid()`` first calls
 ``isSubmitted()``. But without this, the flow doesn't read well as it *looks*
 like the form is *always* processed (even on the GET request).
+
+Custom Form Field Types
+-----------------------
+
+.. best-practice::
+
+    Add the ``app_`` prefix to your custom form field types to avoid collisions.
+
+Custom form field types inherit from the ``AbstractType`` class, which defines the
+``getName()`` method to configure the name of that form type. These names must
+be unique in the application.
+
+If a custom form type uses the same name as any of the Symfony's built-in form
+types, it will override it. The same happens when the custom form type matches
+any of the types defined by the third-party bundles installed in your application.
+
+Add the ``app_`` prefix to your custom form field types to avoid name collisions
+that can lead to hard to debug errors.

book/controller.rst

@@ -451,7 +451,7 @@ Or, if you want to redirect externally, just use ``redirect()`` and pass it the
     }
 
 By default, the ``redirectToRoute()`` method performs a 302 (temporary) redirect. To
-perform a 301 (permanent) redirect, modify the second argument::
+perform a 301 (permanent) redirect, modify the third argument::
 
     public function indexAction()
     {

book/doctrine.rst

@@ -646,6 +646,9 @@ to easily fetch objects based on multiple conditions::
 
     If you click the icon, the profiler will open, showing you the exact
     queries that were made.
+
+    The icon will turn yellow if there were more than 50 queries on the
+    page. This could indicate that something is not correct.
 
 Updating an Object
 ~~~~~~~~~~~~~~~~~~

book/forms.rst

@@ -1061,9 +1061,16 @@ that will house the logic for building the task form::
         }
     }
 
-This new class contains all the directions needed to create the task form
-(note that the ``getName()`` method should return a unique identifier for this
-form "type"). It can be used to quickly build a form object in the controller::
+.. caution::
+
+    The ``getName()`` method returns the identifier of this form "type". These
+    identifiers must be unique in the application. Unless you want to override
+    a built-in type, they should be different from the default Symfony types
+    and from any type defined by a third-party bundle installed in your application.
+    Consider prefixing your types with ``app_`` to avoid identifier collisions.
+
+This new class contains all the directions needed to create the task form. It can
+be used to quickly build a form object in the controller::
 
     // src/AppBundle/Controller/DefaultController.php
 

book/http_fundamentals.rst

@@ -460,7 +460,7 @@ by adding an entry for ``/contact`` to your routing configuration file:
 
 When someone visits the ``/contact`` page, this route is matched, and the
 specified controller is executed. As you'll learn in the :doc:`routing chapter </book/routing>`,
-the ``AcmeDemoBundle:Main:contact`` string is a short syntax that points to a
+the ``AppBundle:Main:contact`` string is a short syntax that points to a
 specific PHP method ``contactAction`` inside a class called ``MainController``::
 
     // src/AppBundle/Controller/MainController.php

book/translation.rst

@@ -427,17 +427,28 @@ via the ``request`` object::
     public function indexAction(Request $request)
     {
         $locale = $request->getLocale();
-
-        $request->setLocale('en_US');
     }
 
-.. tip::
+To set the user's locale, you may want to create a custom event listener
+so that it's set before any other parts of the system (i.e. the translator)
+need it::
 
-    Read :doc:`/cookbook/session/locale_sticky_session` to learn how to store
-    the user's locale in the session.
+        public function onKernelRequest(GetResponseEvent $event)
+        {
+            $request = $event->getRequest();
 
-.. index::
-   single: Translations; Fallback and default locale
+            // some logic to determine the $locale
+            $request->getSession()->set('_locale', $locale);
+        }
+
+Read :doc:`/cookbook/session/locale_sticky_session` for more on the topic.
+
+.. note::
+
+    Setting the locale using ``$request->setLocale()`` in the controller
+    is too late to affect the translator. Either set the locale via a listener
+    (like above), the URL (see next) or call ``setLocale()`` directly on
+    the ``translator`` service.
 
 See the :ref:`book-translation-locale-url` section below about setting the
 locale via routing.
@@ -518,6 +529,9 @@ in your application.
     Read :doc:`/cookbook/routing/service_container_parameters` to learn how to
     avoid hardcoding the ``_locale`` requirement in all your routes.
 
+.. index::
+   single: Translations; Fallback and default locale
+
 Setting a default Locale
 ~~~~~~~~~~~~~~~~~~~~~~~~
 

components/using_components.rst

@@ -36,12 +36,6 @@ whatever component you want.
     file in your directory. In that case, no worries! Just run
     ``php composer.phar require symfony/finder``.
 
-If you know you need a specific version of the library, add that to the command:
-
-.. code-block:: bash
-
-    $ composer require symfony/finder
-
 **3.** Write your code!
 
 Once Composer has downloaded the component(s), all you need to do is include
@@ -51,7 +45,8 @@ immediately::
 
     // File example: src/script.php
 
-    // update this to the path to the "vendor/" directory, relative to this file
+    // update this to the path to the "vendor/"
+    // directory, relative to this file
     require_once __DIR__.'/../vendor/autoload.php';
 
     use Symfony\Component\Finder\Finder;

contributing/code/core_team.rst

@@ -60,14 +60,19 @@ Active Core Members
     MonologBridge_, and TwigBridge_ components;
 
   * **Kévin Dunglas** (`dunglas`_) can merge into the Serializer_
-    component.
+    component;
+
+  * **Abdellatif AitBoudad** (`aitboudad`_) can merge into the Translation_
+    component;
+
+  * **Jakub Zalas** (`jakzal`_) can merge into the DomCrawler_ component.
 
 * **Deciders** (``@symfony/deciders`` on GitHub):
 
-  * **Jakub Zalas** (`jakzal`_);
   * **Jordi Boggiano** (`seldaek`_);
   * **Lukas Kahwe Smith** (`lsmith77`_);
-  * **Ryan Weaver** (`weaverryan`_).
+  * **Ryan Weaver** (`weaverryan`_);
+  * **Christian Flothmann** (`xabbuh`_).
 
 Core Membership Application
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -165,6 +170,7 @@ discretion of the **Project Leader**.
 .. _PropertyAccess: https://github.com/symfony/PropertyAccess
 .. _Routing: https://github.com/symfony/Routing
 .. _Serializer: https://github.com/symfony/Serializer
+.. _Translation: https://github.com/symfony/Translation
 .. _Stopwatch: https://github.com/symfony/Stopwatch
 .. _TwigBridge: https://github.com/symfony/TwigBridge
 .. _Validator: https://github.com/symfony/Validator
@@ -181,3 +187,5 @@ discretion of the **Project Leader**.
 .. _`Seldaek`: https://github.com/Seldaek/
 .. _`lsmith77`: https://github.com/lsmith77/
 .. _`weaverryan`: https://github.com/weaverryan/
+.. _`aitboudad`: https://github.com/aitboudad/
+.. _`xabbuh`: https://github.com/xabbuh/

cookbook/assetic/apply_to_option.rst

@@ -9,7 +9,7 @@ as you'll see here, files that have a specific extension. To show you how
 to handle each option, suppose that you want to use Assetic's CoffeeScript
 filter, which compiles CoffeeScript files into JavaScript.
 
-The main configuration is just the paths to coffee, node and node_modules.
+The main configuration is just the paths to ``coffee``, ``node`` and ``node_modules``.
 An example configuration might look like this:
 
 .. configuration-block::
@@ -102,8 +102,7 @@ You can also combine multiple CoffeeScript files into a single output file:
             <script src="<?php echo $view->escape($url) ?>"></script>
         <?php endforeach ?>
 
-Both the files will now be served up as a single file compiled into regular
-JavaScript.
+Both files will now be served up as a single file compiled into regular JavaScript.
 
 .. _cookbook-assetic-apply-to:
 
@@ -117,10 +116,10 @@ since they will ultimately all be served as JavaScript. Unfortunately just
 adding the JavaScript files to the files to be combined as above will not
 work as the regular JavaScript files will not survive the CoffeeScript compilation.
 
-This problem can be avoided by using the ``apply_to`` option in the config,
-which allows you to specify which filter should always be applied to particular
-file extensions. In this case you can specify that the ``coffee`` filter is
-applied to all ``.coffee`` files:
+This problem can be avoided by using the ``apply_to`` option, which allows you
+to specify which filter should always be applied to particular file extensions.
+In this case you can specify that the ``coffee`` filter is applied to all
+``.coffee`` files:
 
 .. configuration-block::
 
@@ -161,10 +160,10 @@ applied to all ``.coffee`` files:
             ),
         ));
 
-With this, you no longer need to specify the ``coffee`` filter in the template.
-You can also list regular JavaScript files, all of which will be combined
-and rendered as a single JavaScript file (with only the ``.coffee`` files
-being run through the CoffeeScript filter):
+With this option, you no longer need to specify the ``coffee`` filter in the
+template. You can also list regular JavaScript files, all of which will be
+combined and rendered as a single JavaScript file (with only the ``.coffee``
+files being run through the CoffeeScript filter):
 
 .. configuration-block::
 

cookbook/assetic/asset_management.rst

@@ -73,9 +73,9 @@ To include JavaScript files, use the ``javascripts`` tag in any template:
 
 .. note::
 
-    If you're using the default block names from the Symfony Standard Edition,
-    the ``javascripts`` tag will most commonly live in the ``javascripts``
-    block:
+    If your application templates use the default block names from the Symfony
+    Standard Edition, the ``javascripts`` tag will most commonly live in the
+    ``javascripts`` block:
 
     .. code-block:: html+jinja
 
@@ -108,8 +108,8 @@ that reference images by their relative path. See :ref:`cookbook-assetic-cssrewr
 Including CSS Stylesheets
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To bring in CSS stylesheets, you can use the same methodologies seen
-above, except with the ``stylesheets`` tag:
+To bring in CSS stylesheets, you can use the same technique explained above,
+except with the ``stylesheets`` tag:
 
 .. configuration-block::
 
@@ -130,9 +130,9 @@ above, except with the ``stylesheets`` tag:
 
 .. note::
 
-    If you're using the default block names from the Symfony Standard Edition,
-    the ``stylesheets`` tag will most commonly live in the ``stylesheets``
-    block:
+    If your application templates use the default block names from the Symfony
+    Standard Edition, the ``stylesheets`` tag will most commonly live in the
+    ``stylesheets`` block:
 
     .. code-block:: html+jinja
 
@@ -204,7 +204,7 @@ Combining Assets
 ~~~~~~~~~~~~~~~~
 
 One feature of Assetic is that it will combine many files into one. This helps
-to reduce the number of HTTP requests, which is great for front end performance.
+to reduce the number of HTTP requests, which is great for frontend performance.
 It also allows you to maintain the files more easily by splitting them into
 manageable parts. This can help with re-usability as you can easily split
 project-specific files from those which can be used in other applications,
@@ -350,7 +350,7 @@ Filters
 
 Once they're managed by Assetic, you can apply filters to your assets before
 they are served. This includes filters that compress the output of your assets
-for smaller file sizes (and better front-end optimization). Other filters
+for smaller file sizes (and better frontend optimization). Other filters
 can compile JavaScript file from CoffeeScript files and process SASS into CSS.
 In fact, Assetic has a long list of available filters.
 
@@ -366,8 +366,8 @@ To use a filter, you first need to specify it in the Assetic configuration.
 Adding a filter here doesn't mean it's being used - it just means that it's
 available to use (you'll use the filter below).
 
-For example to use the UglifyJS JavaScript minifier the following config should
-be added:
+For example to use the UglifyJS JavaScript minifier the following configuration
+should be defined:
 
 .. configuration-block::
 
@@ -489,8 +489,8 @@ environment is just too slow.
 
 .. _cookbook-assetic-dump-prod:
 
-Instead, each time you use your app in the ``prod`` environment (and therefore,
-each time you deploy), you should run the following task:
+Instead, each time you use your application in the ``prod`` environment (and therefore,
+each time you deploy), you should run the following command:
 
 .. code-block:: bash
 
@@ -532,7 +532,7 @@ the following change in your ``config_dev.yml`` file:
         ));
 
 Next, since Symfony is no longer generating these assets for you, you'll
-need to dump them manually. To do so, run the following:
+need to dump them manually. To do so, run the following command:
 
 .. code-block:: bash
 
@@ -547,8 +547,8 @@ assets will be regenerated automatically *as they change*:
 
     $ php app/console assetic:watch
 
-The ``assetic:watch`` command was introduced in AsseticBundle 2.4. In prior 
-versions, you had to use the ``--watch`` option of the ``assetic:dump`` 
+The ``assetic:watch`` command was introduced in AsseticBundle 2.4. In prior
+versions, you had to use the ``--watch`` option of the ``assetic:dump``
 command for the same behavior.
 
 Since running this command in the ``dev`` environment may generate a bunch

cookbook/assetic/jpeg_optimize.rst

@@ -13,8 +13,9 @@ for your end users.
 Using Jpegoptim
 ---------------
 
-`Jpegoptim`_ is a utility for optimizing JPEG files. To use it with Assetic,
-add the following to the Assetic config:
+`Jpegoptim`_ is a utility for optimizing JPEG files. To use it with Assetic, make
+sure to have it already installed on your system and then, configure its location
+using the ``bin`` option of the ``jpegoptim`` filter:
 
 .. configuration-block::
 
@@ -46,11 +47,6 @@ add the following to the Assetic config:
             ),
         ));
 
-.. note::
-
-    Notice that to use jpegoptim, you must have it already installed on your
-    system. The ``bin`` option points to the location of the compiled binary.
-
 It can now be used from a template:
 
 .. configuration-block::
@@ -74,9 +70,9 @@ It can now be used from a template:
 Removing all EXIF Data
 ~~~~~~~~~~~~~~~~~~~~~~
 
-By default, running this filter only removes some of the meta information
-stored in the file. Any EXIF data and comments are not removed, but you can
-remove these by using the ``strip_all`` option:
+By default, the ``jpegoptim`` filter removes some of the meta information stored
+in the image. To remove all EXIF data and comments, set the ``strip_all`` option
+to ``true``:
 
 .. configuration-block::
 
@@ -111,13 +107,13 @@ remove these by using the ``strip_all`` option:
             ),
         ));
 
-Lowering maximum Quality
+Lowering Maximum Quality
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-The quality level of the JPEG is not affected by default. You can gain
-further file size reductions by setting the max quality setting lower than
-the current level of the images. This will of course be at the expense of
-image quality:
+By default, the ``jpegoptim`` filter doesn't alter the quality level of the JPEG
+image. Use the ``max`` option to configure the maximum quality setting (in a
+scale of ``0`` to ``100``). The reduction in the image file size will of course
+be at the expense of its quality:
 
 .. configuration-block::
 
@@ -157,7 +153,7 @@ Shorter Syntax: Twig Function
 
 If you're using Twig, it's possible to achieve all of this with a shorter
 syntax by enabling and using a special Twig function. Start by adding the
-following config:
+following configuration:
 
 .. configuration-block::
 
@@ -206,7 +202,8 @@ The Twig template can now be changed to the following:
 
     <img src="{{ jpegoptim('@AppBundle/Resources/public/images/example.jpg') }}" alt="Example"/>
 
-You can specify the output directory in the config in the following way:
+You can also specify the output directory for images in the Assetic configuration
+file:
 
 .. configuration-block::