Merge branch '3.4' into 4.0

* 3.4:
  Mentioned the ability of PropertyNormalizer to handle parent classes
  Reverted the cache:clear warm up deprecation
  Documented how to load and dump translation notes
  [BrowserKit] Add snippet: how to upload a file
  uploading example: explaining the need for md5
  soap_web_service: code style in examples
  Updated the main performance article to make it more actionable
  Improved the docs about multiple Webpack configs
  Added a note about using slashes and the special _format param
  Document new VarCloner::setMinDepth function

Author: javiereguiluz

components/browser_kit.rst

@@ -109,6 +109,9 @@ method (which makes the needed HTTP POST request to submit the form contents)::
     $form['login'] = 'symfonyfan';
     $form['password'] = 'anypass';
 
+    // To upload a file, the value should be the absolute file path
+    $form['file'] = __FILE__;
+
     // submit that form
     $crawler = $client->submit($form);
 

components/serializer.rst

@@ -565,11 +565,15 @@ There are several types of normalizers available:
 
 :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer`
     This normalizer directly reads and writes public properties as well as
-    **private and protected** properties. It supports calling the constructor
-    during the denormalization process.
+    **private and protected** properties (from both the class and all of its
+    parent classes). It supports calling the constructor during the denormalization process.
 
     Objects are normalized to a map of property names to property values.
 
+    .. versionadded:: 3.4
+        The ability to handle parent classes for ``PropertyNormalizer`` was
+        introduced in Symfony 3.4.
+
 :class:`Symfony\\Component\\Serializer\\Normalizer\\JsonSerializableNormalizer`
     This normalizer works with classes that implement :phpclass:`JsonSerializable`.
 

components/translation/usage.rst

@@ -418,5 +418,62 @@ The ``$messages`` variable will have the following structure::
         ),
     );
 
+Adding Notes to Translation Contents
+------------------------------------
+
+.. versionadded: 3.4
+    The feature to load and dump translation notes was introduced in Symfony 3.4.
+
+Sometimes translators need additional context to better decide how to translate
+some content. This context can be provided with notes, which are a collection of
+comments used to store end user readable information. The only format that
+supports loading and dumping notes is XLIFF version 2.0.
+
+If the XLIFF 2.0 document contains ``<notes>`` nodes, they are automatically
+loaded/dumped when using this component inside a Symfony application:
+
+.. code-block:: xml
+
+    <?xml version="1.0" encoding="utf-8"?>
+    <xliff xmlns="urn:oasis:names:tc:xliff:document:2.0" version="2.0"
+           srcLang="fr-FR" trgLang="en-US">
+      <file id="messages.en_US">
+        <unit id="LCa0a2j">
+          <notes>
+            <note category="state">new</note>
+            <note category="approved">true</note>
+            <note category="section" priority="1">user login</note>
+          </notes>
+          <segment>
+            <source>original-content</source>
+            <target>translated-content</target>
+          </segment>
+        </unit>
+      </file>
+    </xliff>
+
+When using the standalone Translation component, call the ``setMetadata()``
+method of the catalogue and pass the notes as arrays. This is for example the
+code needed to generate the previous XLIFF file::
+
+    use Symfony\Component\Translation\MessageCatalogue;
+    use Symfony\Component\Translation\Dumper\XliffFileDumper;
+
+    $catalogue = new MessageCatalogue('en_US');
+    $catalogue->add([
+        'original-content' => 'translated-content',
+    ]);
+    $catalogue->setMetadata('original-content', ['notes' => [
+        ['category' => 'state', 'content' => 'new'],
+        ['category' => 'approved', 'content' => 'true'],
+        ['category' => 'section', 'content' => 'user login', 'priority' => '1'],
+    ]]);
+
+    $dumper = new XliffFileDumper();
+    $dumper->formatCatalogue($catalogue, 'messages', [
+        'default_locale' => 'fr_FR',
+        'xliff_version' => '2.0'
+    ]);
+
 .. _`L10n`: https://en.wikipedia.org/wiki/Internationalization_and_localization
 .. _`ISO 31-11`: https://en.wikipedia.org/wiki/Interval_(mathematics)#Notations_for_intervals

components/var_dumper/advanced.rst

@@ -53,16 +53,23 @@ Before calling :method:`Symfony\\Component\\VarDumper\\Cloner\\VarCloner::cloneV
 you can configure these limits:
 
 :method:`Symfony\\Component\\VarDumper\\Cloner\\VarCloner::setMaxItems`
-    configures the maximum number of items that will be cloned
-    *past the first nesting level*. Items are counted using a breadth-first
+    Configures the maximum number of items that will be cloned
+    *past the minimum nesting depth*. Items are counted using a breadth-first
     algorithm so that lower level items have higher priority than deeply nested
-    items;
+    items. Specifying ``-1`` removes the limit.
 
-:method:`Symfony\\Component\\VarDumper\\Cloner\\VarCloner::setMaxString`
-    configures the maximum number of characters that will be cloned before
-    cutting overlong strings;
+:method:`Symfony\\Component\\VarDumper\\Cloner\\VarCloner::setMinDepth`
+    .. versionadded:: 3.4
+        The ``setMinDepth()`` method was introduced in Symfony 3.4.
+
+    Configures the minimum tree depth where we are guaranteed to clone
+    all the items. After this depth is reached, only ``setMaxItems``
+    items will be cloned. The default value is ``1``, which is consistent
+    with older Symfony versions.
 
-In both cases, specifying ``-1`` removes any limit.
+:method:`Symfony\\Component\\VarDumper\\Cloner\\VarCloner::setMaxString`
+    Configures the maximum number of characters that will be cloned before
+    cutting overlong strings.  Specifying ``-1`` removes the limit.
 
 Before dumping it, you can further limit the resulting
 :class:`Symfony\\Component\\VarDumper\\Cloner\\Data` object using the following methods:

controller/soap_web_service.rst

@@ -40,8 +40,8 @@ In this case, the SOAP service will allow the client to call a method called
         {
 
             $message = new \Swift_Message('Hello Service')
-                                    ->setTo('[email protected]')
-                                    ->setBody($name . ' says hi!');
+                ->setTo('[email protected]')
+                ->setBody($name.' says hi!');
 
             $this->mailer->send($message);
 

controller/upload_file.rst

@@ -132,8 +132,7 @@ Finally, you need to update the code of the controller that handles the form::
                 /** @var Symfony\Component\HttpFoundation\File\UploadedFile $file */
                 $file = $product->getBrochure();
 
-                // Generate a unique name for the file before saving it
-                $fileName = md5(uniqid()).'.'.$file->guessExtension();
+                $fileName = $this->generateUniqueFileName().'.'.$file->guessExtension();
 
                 // Move the file to the directory where brochures are stored
                 $file->move(
@@ -154,6 +153,16 @@ Finally, you need to update the code of the controller that handles the form::
                 'form' => $form->createView(),
             ));
         }
+        
+        /**
+         * @return string
+         */
+        private function generateUniqueFileName()
+        {
+            // md5() reduces the similarity of the file names generated by
+            // uniqid(), which is based on timestamps
+            return md5(uniqid());
+        }
     }
 
 Now, create the ``brochures_directory`` parameter that was used in the

deployment.rst

@@ -167,8 +167,7 @@ Make sure you clear and warm-up your Symfony cache:
 
 .. code-block:: terminal
 
-    $ php bin/console cache:clear --env=prod --no-debug --no-warmup
-    $ php bin/console cache:warmup --env=prod
+    $ php bin/console cache:clear --env=prod --no-debug
 
 E) Dump your Assetic Assets
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

frontend/encore/advanced-config.rst

@@ -63,6 +63,9 @@ state of the current configuration to build a new one:
     // build the first configuration
     const firstConfig = Encore.getWebpackConfig();
 
+    // Set a unique name for the config (needed later!)
+    firstConfig.name = 'firstConfig';
+
     // reset Encore to build the second config
     Encore.reset();
 
@@ -79,9 +82,19 @@ state of the current configuration to build a new one:
     // build the second configuration
     const secondConfig = Encore.getWebpackConfig();
 
+    // Set a unique name for the config (needed later!)
+    secondConfig.name = 'secondConfig';
+
     // export the final configuration as an array of multiple configurations
     module.exports = [firstConfig, secondConfig];
 
+When running Encore, both configurations will be built in parallel. If you
+prefer to build configs separately, pass the ``--config-name`` option:
+
+.. code-block:: terminal
+
+    $ yarn run encore dev --config-name firstConfig
+
 .. _`configuration options`: https://webpack.js.org/configuration/
 .. _`Webpack's watchOptions`: https://webpack.js.org/configuration/watch/#watchoptions
 .. _`array of configurations`: https://github.com/webpack/docs/wiki/configuration#multiple-configurations

introduction/from_flat_php_to_symfony2.rst

@@ -578,7 +578,7 @@ nice way to group related pages. The controller functions are also sometimes cal
 The two controllers (or actions) are still lightweight. Each uses the
 :doc:`Doctrine ORM library </doctrine>` to retrieve objects from the
 database and the Templating component to render a template and return a
-``Response`` object. The list ``list.html.twig`` template is now quite a bit simpler,
+``Response`` object. The ``list.html.twig`` template is now quite a bit simpler,
 and uses Twig:
 
 .. code-block:: html+twig
@@ -669,9 +669,9 @@ It's a beautiful thing.
 Where Symfony Delivers
 ----------------------
 
-In the rest of documentation articles, you'll learn more about how each piece of
-Symfony works and how you can organize your project. For now, celebrate at how
-migrating the blog from flat PHP to Symfony has improved life:
+In the rest of the documentation articles, you'll learn more about how each piece of
+Symfony works and how you can organize your project. For now, celebrate how
+migrating the blog from flat PHP to Symfony has improved your life:
 
 * Your application now has **clear and consistently organized code** (though
   Symfony doesn't force you into this). This promotes **reusability** and