Merge branch '4.0'

* 4.0: (33 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
  Simplify the setup article
  Added a tip about tests and BCrypt
  Document that Doctrine associations don't work across different entity managers
  Update entity_provider.rst
  Removed the section that explains how to install all components
  Improved the link to the CSRF config referece
  Reword
  Make require as a dev dependency
  Fixed invalid form validation reference
  fix a typo
  use a class based service ID
  Update entity_provider.rst
  Update doctrine.rst
  Merged new example in older example, removing some text
  Fix typo
  Document typed arrays in optionsresolver
  ...

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/process.rst

@@ -20,8 +20,11 @@ You can install the component in 2 different ways:
 Usage
 -----
 
-The :class:`Symfony\\Component\\Process\\Process` class allows you to execute
-a command in a sub-process::
+The :class:`Symfony\\Component\\Process\\Process` class executes a command in a
+sub-process, taking care of the differences between operating system and
+escaping arguments to prevent security issues. It replaces PHP functions like
+:phpfunction:`exec`, :phpfunction:`passthru`, :phpfunction:`shell_exec` and
+:phpfunction:`system`::
 
     use Symfony\Component\Process\Process;
     use Symfony\Component\Process\Exception\ProcessFailedException;
@@ -36,8 +39,18 @@ a command in a sub-process::
 
     echo $process->getOutput();
 
-The component takes care of the subtle differences between the different platforms
-when executing the command.
+.. tip::
+
+    In addition to passing the command binary and its arguments as a string, you
+    can also pass them as an array, which is useful when building a complex
+    command programmatically::
+
+        // traditional string based commands
+        $builder = new Process('ls -lsa');
+        // same example but using an array
+        $builder = new Process(array('ls', '-lsa'));
+        // the array can contain any number of arguments and options
+        $builder = new Process(array('ls', '-l', '-s', '-a'));
 
 The ``getOutput()`` method always returns the whole content of the standard
 output of the command and ``getErrorOutput()`` the content of the error

components/using_components.rst

@@ -56,19 +56,6 @@ immediately::
 
     // ...
 
-Using all of the Components
----------------------------
-
-If you want to use all of the Symfony Components, then instead of adding
-them one by one, you can include the ``symfony/symfony`` package:
-
-.. code-block:: terminal
-
-    $ composer require symfony/symfony
-
-This will also include the Bundle and Bridge libraries, which you may or
-may not actually need.
-
 Now what?
 ---------
 

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.rst

@@ -612,7 +612,7 @@ a new method for this to your repository::
          */
         public function findAllGreaterThanPrice($price): array
         {
-            // automatically knows to selects Products
+            // automatically knows to select Products
             // the "p" is an alias you'll use in the rest of the query
             $qb = $this->createQueryBuilder('p')
                 ->andWhere('p.price > :price')
@@ -623,7 +623,7 @@ a new method for this to your repository::
             return $qb->execute();
 
             // to get just one result:
-            // $product = $query->setMaxResults(1)->getOneOrNullResult();
+            // $product = $qb->setMaxResults(1)->getOneOrNullResult();
         }
     }
 
@@ -654,6 +654,8 @@ In addition to the query builder, you can also query with `Doctrine Query Langua
 
     public function findAllGreaterThanPrice($price): array
     {
+        $em = $this->getEntityManager();
+        
         $query = $em->createQuery(
             'SELECT p
             FROM App\Entity\Product p

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

form/dynamic_form_modification.rst

@@ -613,11 +613,3 @@ field according to the current selection in the ``sport`` field:
 The major benefit of submitting the whole form to just extract the updated
 ``position`` field is that no additional server-side code is needed; all the
 code from above to generate the submitted form can be reused.
-
-.. _form-dynamic-form-modification-suppressing-form-validation:
-
-Suppressing Form Validation
----------------------------
-
-To suppress form validation, set ``validation_groups`` to ``false`` or an empty
-array.