Merge branch '3.4' into 4.0

* 3.4: (25 commits)
  Fixed merge errors
  Client's history clear alternative
  Don't mention the abandoned JMSTranslationBundle
  Reworded the console verbosity article to explain SHELL_VERBOSITY too
  Added a tip about tests and BCrypt
  Document that Doctrine associations don't work across different entity managers
  Update entity_provider.rst
  Reword
  Make require as a dev dependency
  Fixed invalid form validation reference
  use a class based service ID
  Merged new example in older example, removing some text
  Fix typo
  Document typed arrays in optionsresolver
  Fixed a wrong reference
  Document that Doctrine associations don't work across different entity managers
  Don't use OutputInterface::VERBOSITY constants, use PHP methods instead
  Mention the new behavior of dump() which returns the passed value
  Mentioned APP_ENV for Flex apps
  Updated LDAP documentation for Symfony 3.1
  ...

Author: javiereguiluz

best_practices/i18n.rst

@@ -36,9 +36,8 @@ XLIFF notes allow you to define that context.
 
 .. tip::
 
-    The Apache-licensed `JMSTranslationBundle`_ offers you a web interface for
-    viewing and editing these translation files. It also has advanced extractors
-    that can read your project and automatically update the XLIFF files.
+    The `PHP Translation Bundle`_ includes advanced extractors that can read
+    your project and automatically update the XLIFF files.
 
 Translation Keys
 ----------------
@@ -80,4 +79,4 @@ English in the application would be:
 
 Next: :doc:`/best_practices/security`
 
-.. _`JMSTranslationBundle`: https://github.com/schmittjoh/JMSTranslationBundle
+.. _`PHP Translation Bundle`: https://github.com/php-translation/symfony-bundle

components/browser_kit.rst

@@ -226,7 +226,7 @@ also delete all the cookies::
     $client = new Client();
     $client->request('GET', '/');
 
-    // delete history
+    // reset the client (history and cookies are cleared too)
     $client->restart();
 
 Learn more

components/ldap.rst

@@ -73,6 +73,52 @@ LDAP server), you may query the LDAP server using the
 
     // ...
 
-    $ldap->query('dc=symfony,dc=com', '(&(objectclass=person)(ou=Maintainers))');
+    $query = $ldap->query('dc=symfony,dc=com', '(&(objectclass=person)(ou=Maintainers))');
+    $results = $query->execute();
+
+    foreach ($results as $entry) {
+        // Do something with the results
+    }
+
+By default, LDAP entries are lazy-loaded. If you wish to fetch
+all entries in a single call and do something with the results'
+array, you may use the
+:method:`Symfony\\Component\\Ldap\\Adapter\\ExtLdap\\Collection::toArray` method::
+
+    // ...
+
+    $query = $ldap->query('dc=symfony,dc=com', '(&(objectclass=person)(ou=Maintainers))');
+    $results = $query->execute()->toArray();
+
+    // Do something with the results array
+
+Creating or updating entries
+----------------------------
+
+Since version 3.1, The Ldap component provides means to create
+new LDAP entries, update or even delete existing ones::
+
+    use Symfony\Component\Ldap\Entry;
+    // ...
+
+    $entry = new Entry('cn=Fabien Potencier,dc=symfony,dc=com', array(
+        'sn' => array('fabpot'),
+        'objectClass' => array('inetOrgPerson'),
+    ));
+
+    $em = $ldap->getEntryManager();
+
+    // Creating a new entry
+    $em->add($entry);
+
+    // Finding and updating an existing entry
+    $query = $ldap->query('dc=symfony,dc=com', '(&(objectclass=person)(ou=Maintainers))');
+    $result = $query->execute();
+    $entry = $result[0];
+    $entry->addAttribute('email', array('fabpot@symfony.com'));
+    $em->update($entry);
+
+    // Removing an existing entry
+    $em->remove(new Entry('cn=Test User,dc=symfony,dc=com'));
 
 .. _Packagist: https://packagist.org/packages/symfony/ldap

components/options_resolver.rst

@@ -317,14 +317,27 @@ correctly. To validate the types of the options, call
         public function configureOptions(OptionsResolver $resolver)
         {
             // ...
+
+            // specify one allowed type
             $resolver->setAllowedTypes('host', 'string');
+
+            // specify multiple allowed types
             $resolver->setAllowedTypes('port', array('null', 'int'));
+
+            // check all items in an array recursively for a type
+            $resolver->setAllowedTypes('dates', 'DateTime[]');
+            $resolver->setAllowedtypes('ports', 'int[]');
         }
     }
 
-For each option, you can define either just one type or an array of acceptable
-types. You can pass any type for which an ``is_<type>()`` function is defined
-in PHP. Additionally, you may pass fully qualified class or interface names.
+You can pass any type for which an ``is_<type>()`` function is defined in PHP.
+You may also pass fully qualified class or interface names (which is checked
+using ``instanceof``). Additionally, you can validate all items in an array
+recursively by suffixing the type with ``[]``.
+
+.. versionadded:: 3.4
+    Validating types of array items recursively was introduced in Symfony 3.4.
+    Prior to Symfony 3.4, only scalar values could be validated.
 
 If you pass an invalid option now, an
 :class:`Symfony\\Component\\OptionsResolver\\Exception\\InvalidOptionsException`

components/phpunit_bridge.rst

@@ -113,8 +113,25 @@ in the **Unsilenced** section of the deprecation report.
 Mark Tests as Legacy
 --------------------
 
-Add the ``@group legacy`` annotation to a test class or method to mark it
-as legacy.
+There are three ways to mark a test as legacy:
+
+* (**Recommended**) Add the ``@group legacy`` annotation to its class or method;
+
+* Make its class name start with the ``Legacy`` prefix;
+
+* Make its method name start with ``testLegacy*()`` instead of ``test*()``.
+
+.. note::
+
+    If your data provider calls code that would usually trigger a deprecation,
+    you can prefix its name with ``provideLegacy`` or ``getLegacy`` to silent
+    these deprecations. If your data provider does not execute deprecated
+    code, it is not required to choose a special naming just because the
+    test being fed by the data provider is marked as legacy.
+
+    Also be aware that choosing one of the two legacy prefixes will not mark
+    tests as legacy that make use of this data provider. You still have to
+    mark them as legacy tests explicitly.
 
 Configuration
 -------------

components/var_dumper.rst

@@ -50,6 +50,9 @@ For example::
 
     dump($someVar);
 
+    // dump() returns the passed value, so you can dump an object and keep using it
+    dump($someObject)->someMethod();
+
 By default, the output format and destination are selected based on your
 current PHP SAPI:
 

console/verbosity.rst

@@ -1,18 +1,41 @@
 Verbosity Levels
 ================
 
-The console has five verbosity levels. These are defined in the
-:class:`Symfony\\Component\\Console\\Output\\OutputInterface`:
-
-===========================================  ==================================  =====================
-Value                                        Meaning                             Console option
-===========================================  ==================================  =====================
-``OutputInterface::VERBOSITY_QUIET``         Do not output any messages          ``-q`` or ``--quiet``
-``OutputInterface::VERBOSITY_NORMAL``        The default verbosity level         (none)
-``OutputInterface::VERBOSITY_VERBOSE``       Increased verbosity of messages     ``-v``
-``OutputInterface::VERBOSITY_VERY_VERBOSE``  Informative non essential messages  ``-vv``
-``OutputInterface::VERBOSITY_DEBUG``         Debug messages                      ``-vvv``
-===========================================  ==================================  =====================
+Console commands have different verbosity levels, which determine the messages
+displayed in their output. By default, commands display only the most useful
+messages, but you can control their verbosity with the ``-q`` and ``-v`` options:
+
+.. code-block:: terminal
+
+    # do not output any message (not even the command result messages)
+    $ php bin/console some-command -q
+    $ php bin/console some-command --quiet
+
+    # normal behavior, no option required (display only the useful messages)
+    $ php bin/console some-command
+
+    # increase verbosity of messages
+    $ php bin/console some-command -v
+
+    # display also the informative non essential messages
+    $ php bin/console some-command -vv
+
+    # display all messages (useful to debug errors)
+    $ php bin/console some-command -vvv
+
+The verbosity level can also be controlled globally for all commands with the
+``SHELL_VERBOSITY`` environment variable (the ``-q`` and ``-v`` options still
+have more precedence over the value of ``SHELL_VERBOSITY``):
+
+=====================  =========================  ===========================================
+Console option         ``SHELL_VERBOSITY`` value  Equivalent PHP constant
+=====================  =========================  ===========================================
+``-q`` or ``--quiet``  ``-1``                     ``OutputInterface::VERBOSITY_QUIET``
+(none)                 ``0``                      ``OutputInterface::VERBOSITY_NORMAL``
+``-v``                 ``1``                      ``OutputInterface::VERBOSITY_VERBOSE``
+``-vv``                ``2``                      ``OutputInterface::VERBOSITY_VERY_VERBOSE``
+``-vvv``               ``3``                      ``OutputInterface::VERBOSITY_DEBUG``
+=====================  =========================  ===========================================
 
 It is possible to print a message in a command for only a specific verbosity
 level. For example::
@@ -31,38 +54,19 @@ level. For example::
                 'Password: '.$input->getArgument('password'),
             ));
 
-            // the user class is only printed when the verbose verbosity level is used
-            if ($output->getVerbosity() >= OutputInterface::VERBOSITY_VERBOSE) {
+            // available methods: ->isQuiet(), ->isVerbose(), ->isVeryVerbose(), ->isDebug()
+            if ($output->isVerbose()) {
                 $output->writeln('User class: '.get_class($user));
             }
 
-            // alternatively you can pass the verbosity level to writeln()
+            // alternatively you can pass the verbosity level PHP constant to writeln()
             $output->writeln(
                 'Will only be printed in verbose mode or higher',
                 OutputInterface::VERBOSITY_VERBOSE
             );
         }
     }
 
-There are also more semantic methods you can use to test for each of the
-verbosity levels::
-
-    if ($output->isQuiet()) {
-        // ...
-    }
-
-    if ($output->isVerbose()) {
-        // ...
-    }
-
-    if ($output->isVeryVerbose()) {
-        // ...
-    }
-
-    if ($output->isDebug()) {
-        // ...
-    }
-
 When the quiet level is used, all output is suppressed as the default
 :method:`Symfony\\Component\\Console\\Output\\Output::write` method returns
 without actually printing.

deployment.rst

@@ -156,8 +156,9 @@ as you normally do:
 .. caution::
 
     If you get a "class not found" error during this step, you may need to
-    run ``export SYMFONY_ENV=prod`` before running this command so that
-    the ``post-install-cmd`` scripts run in the ``prod`` environment.
+    run ``export SYMFONY_ENV=prod`` (or ``export APP_ENV=prod`` if you're
+    using :doc:`Symfony Flex </setup/flex>`) before running this command so
+    that the ``post-install-cmd`` scripts run in the ``prod`` environment.
 
 D) Clear your Symfony Cache
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

doctrine/multiple_entity_managers.rst

@@ -16,6 +16,12 @@ entity manager that connects to another database might handle the rest.
     usually required. Be sure you actually need multiple entity managers before
     adding in this layer of complexity.
 
+.. caution::
+
+    Entities cannot define associations across different entity managers. If you
+    need that, there are `several alternatives <https://stackoverflow.com/a/11494543/2804294>`_
+    that require some custom setup.
+
 The following configuration code shows how you can configure two entity managers:
 
 .. configuration-block::

form/disabling_validation.rst

@@ -18,5 +18,10 @@ these cases you can set the ``validation_groups`` option to ``false``::
 
 Note that when you do that, the form will still run basic integrity checks,
 for example whether an uploaded file was too large or whether non-existing
-fields were submitted. If you want to suppress validation, you can use the
-:ref:`POST_SUBMIT event <form-dynamic-form-modification-suppressing-form-validation>`.
+fields were submitted.
+
+The submission of extra form fields can be controlled with the
+`allow_extra_fields config option`_ and the maximum upload file size should be
+handled via your PHP and web server configuration.
+
+.. _`allow_extra_fields config option`: https://symfony.com/doc/current/reference/forms/types/form.html#allow-extra-fields